How to Configure Different Logging Personalities for Embabel Agents

Embabel agents support configurable logging personalities that combine log-level overrides with color palettes, allowing you to switch console themes such as "dark", "light", or "high-contrast" via Spring Boot properties, annotations, or programmatic bean registration.

The embabel/embabel-agent framework extends Spring Boot's logging infrastructure with an abstraction called a logging personality. This feature lets you customize the visual appearance and verbosity of agent console output without modifying core agent code. Understanding how to configure different logging personalities for Embabel agents ensures your monitoring interfaces match your team's accessibility needs and environmental preferences.

What Is a Logging Personality?

A logging personality in Embabel agents is a configuration object that groups two elements: a set of log-level overrides and a color palette. This abstraction, implemented in the LoggingPersonality class, allows runtime switching between visual themes while maintaining consistent log formatting across the agent platform.

Configure Personalities via Application Properties

The simplest way to select a personality is through Spring Boot configuration files. The framework reads the embabel.logging.personality property (with a fallback to logging.personality) at startup and loads the matching LoggingPersonality bean.

This mechanism is driven by the LoggingPersonalityProperties record defined in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/LoggingThemes.java.

Example application.yml Configuration

# src/main/resources/application.yml

embabel:
  logging:
    personality: dark   # options: dark, light, high-contrast

Declare Personalities with @LoggingThemes

For configuration-class-level control, apply the @LoggingThemes annotation to any @Configuration class. This annotation triggers the AgentLoggingEnvironmentPostProcessor, which registers the appropriate LoggingPersonality bean before the application context refreshes.

Annotation-Based Configuration

package com.myapp.config;

import com.embabel.agent.config.annotation.LoggingThemes;
import org.springframework.context.annotation.Configuration;

@Configuration
@LoggingThemes(personality = "light")
class AgentLoggingConfig {
}

The annotation definition resides in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/LoggingThemes.java.

Programmatic Bean Registration

For complete control over color mappings and log levels, manually define a LoggingPersonality bean in your configuration class. This approach bypasses the autoconfiguration mechanism and allows bespoke palette definitions.

Custom Color Palette Implementation

@Configuration
class CustomLoggingConfig {

    @Bean
    public LoggingPersonality myPersonality() {
        ColorPalette palette = new ColorPalette()
                .withInfo("#00ff00")
                .withWarn("#ff8800")
                .withError("#ff0000");
        return new LoggingPersonality(palette);
    }
}

The AgentShellAutoConfigurationTest.java file in embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/test/java/com/embabel/agent/autoconfigure/shell/ demonstrates this pattern, showing how mock LoggingPersonality beans are injected during test execution.

Built-In Logging Personalities

Embabel ships with three predefined personalities optimized for different terminal environments:

• dark: Optimized for dark terminal backgrounds with muted, low-glare colors
• light: High-visibility palette designed for light terminal themes
• high-contrast: Accessibility-focused palette maximizing differentiation between log levels

Summary

• Logging personalities combine log-level overrides with color palettes to control Embabel agent console output.
• Configure personalities via the embabel.logging.personality property in application.yml or application.properties.
• Use the @LoggingThemes annotation on configuration classes to trigger the AgentLoggingEnvironmentPostProcessor.
• Implement custom themes by registering a LoggingPersonality bean with a bespoke ColorPalette.
• Built-in options include dark, light, and high-contrast themes.

Frequently Asked Questions

What property name configures the logging personality in Embabel agents?

Set embabel.logging.personality in your Spring Boot configuration files. The framework also accepts logging.personality as a fallback. This property binds to the LoggingPersonalityProperties record in the autoconfiguration module.

Can I create custom color schemes beyond the built-in personalities?

Yes. Define a @Bean of type LoggingPersonality that accepts a custom ColorPalette. This allows you to specify exact hex codes for INFO, WARN, ERROR, and other log levels, as demonstrated in the AgentShellAutoConfigurationTest.java test suite.

How does the @LoggingThemes annotation work?

The @LoggingThemes annotation triggers the AgentLoggingEnvironmentPostProcessor class, which runs during the Spring Boot environment post-processing phase. It registers the specified LoggingPersonality bean before the application context initializes, ensuring the theme is active during agent startup.

Where are the logging personality classes defined?

The core annotation and properties reside in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/LoggingThemes.java. Test implementations showing bean injection patterns appear in AgentLoggingEnvironmentPostProcessorTest.java and AgentShellAutoConfigurationTest.java.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}