How to Debug Agent Execution with Embabel's Logging Profiles

Activate Spring Boot logging profiles such as thinking or streaming-test via the @EnableAgents annotation to capture TRACE-level diagnostics from Embabel's LLM clients, tool-loop engines, and streaming components.

Debugging agent execution in the embabel/embabel-agent framework requires deep visibility into the LLM integration layer, asynchronous tool loops, and response streaming pipelines. By leveraging Embabel's built-in logging profiles, you can dynamically adjust logger levels for specific internal packages without modifying XML configuration files. This guide demonstrates how to enable these profiles and interpret their colour-coded output to diagnose agent behavior effectively.

Understanding Embabel's Built-In Logging Profiles

Embabel Agent ships with predefined Spring Boot profiles that target specific subsystems. When activated, these profiles elevate logger levels from INFO to DEBUG or TRACE for targeted packages, exposing the internal state of agent operations.

Profile	Purpose	Target Packages
thinking	Verbose logging of LLM calls and tool-loop iterations	com.embabel.agent.spi.support.springai.ChatClientLlmOperations (TRACE)com.embabel.common.core.thinking (DEBUG)
streaming-test	Detailed tracing of the streaming pipeline	com.embabel.agent.spi.support.streaming.StreamingLlmOperationsImpl (TRACE)
cost-tracking-it	Diagnostics for cost-tracking calculations	com.embabel.agent.cost (DEBUG)
starwars	Demonstration profile for custom activation patterns	(No specific loggers; validates profile mechanism)

These profiles are processed by the framework's configuration layer to inject the appropriate logging.level properties into the Spring Environment at runtime.

How Logging Profiles Work in the Embabel Agent Framework

The logging profile system relies on three core components that orchestrate profile detection and output formatting.

EnableAgents Annotation

The @EnableAgents annotation, located in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java, serves as the entry point. When applied to a Spring Boot application class, it signals the framework to scan for active profiles and apply Embabel-specific logging configurations.

EnvironmentPostProcessor

The EnvironmentPostProcessor class in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/spi/EnvironmentPostProcessor.java reads the active Spring profiles and programmatically injects logger level mappings. This ensures that when thinking is active, the corresponding packages receive TRACE-level logging before the application context fully initializes.

LoggingPersonality and ColorPalette

To make debug output readable, Embabel provides a custom logging personality. The LoggingPersonality class in embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/LoggingPersonality.java defines the console formatting rules, while ColorPalette in embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java supplies ANSI colour codes. TRACE messages appear in bright cyan, DEBUG in green, and ERROR in red, making it easy to visually distinguish log severity during agent execution.

Enabling Logging Profiles in Your Application

Follow these steps to activate diagnostic logging for your agent.

1. Add the @EnableAgents annotation to your main application class or configuration:

   @SpringBootApplication
   @EnableAgents
   public class MyAgentApplication {
       public static void main(String[] args) {
           SpringApplication.run(MyAgentApplication.class, args);
       }
   }

2. Activate the desired profile using one of three standard Spring Boot mechanisms:

   Via application.yml:

   spring:
     profiles:
       active: thinking

   Via command-line argument:

   java -jar my-agent.jar --spring.profiles.active=thinking

   Programmatically before startup:

   public static void main(String[] args) {
       System.setProperty("spring.profiles.active", "streaming-test");
       SpringApplication.run(MyAgentApplication.class, args);
   }

3. Execute your agent. The console output will now include colour-coded TRACE and DEBUG statements from the targeted subsystems.

Debugging Streaming and Tool Loop Execution

When diagnosing complex interactions like streaming LLM responses or parallel tool loops, the streaming-test and thinking profiles provide granular insight.

Consider a streaming implementation where you need to verify chunk processing:

@SpringBootApplication
@EnableAgents
public class StreamingDebugApplication {
    public static void main(String[] args) {
        System.setProperty("spring.profiles.active", "streaming-test");
        ConfigurableApplicationContext ctx = SpringApplication.run(StreamingDebugApplication.class, args);
        
        // Your agent execution logic here
    }
}

With this configuration, the console displays output similar to:

[2026-08-08 12:34:56.789] TRACE com.embabel.agent.spi.support.streaming.StreamingLlmOperationsImpl - Sending chunk #1 to stream processor
[2026-08-08 12:34:56.791] DEBUG com.embabel.agent.spi.support.springai.ChatClientLlmOperations - LLM response metadata received

The bright cyan TRACE lines indicate low-level streaming operations, while green DEBUG lines show higher-level LLM client interactions.

Reference Implementation in the Test Suite

The embabel/embabel-agent repository validates these logging profiles through integration tests that verify correct logger level assignment.

ParallelToolLoopGuardRailIT

Located in embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/ParallelToolLoopGuardRailIT.java, this test activates the thinking profile to ensure the tool-loop guardrails emit TRACE-level diagnostics during parallel execution scenarios.

LLMOpenAiStreamingBuilderIT

Found in embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/LLMOpenAiStreamingBuilderIT.java, this class uses @ActiveProfiles("streaming-test") to validate that the streaming pipeline produces the expected verbose output when processing OpenAI streaming responses.

LLMOllamaThinkingIT

In embabel-agent-autoconfigure/models/embabel-agent-ollama-autoconfigure/src/test/java/com/embabel/agent/config/models/ollama/LLMOllamaThinkingIT.java, this test demonstrates profile usage with the Ollama backend, confirming that the thinking profile correctly elevates logging for local LLM interactions.

Summary

• Embabel Agent provides built-in Spring Boot logging profiles (thinking, streaming-test, cost-tracking-it) that expose TRACE and DEBUG output for specific agent subsystems.
• The @EnableAgents annotation triggers the EnvironmentPostProcessor to inject logger configurations based on active profiles.
• Colour-coded output is handled by LoggingPersonality and ColorPalette, making it easy to visually scan logs.
• Activate profiles via application.yml, command-line arguments, or system properties to debug LLM calls, tool loops, and streaming without code changes.
• Integration tests like ParallelToolLoopGuardRailIT demonstrate production-ready usage of these diagnostic profiles.

Frequently Asked Questions

How do I enable multiple logging profiles simultaneously?

You can activate multiple profiles by comma-separating them in your configuration. Set spring.profiles.active=thinking,streaming-test in your application.yml or as a command-line argument. The EnvironmentPostProcessor will process each profile and apply the union of their logger level configurations, giving you comprehensive visibility into both the tool loop and streaming subsystems simultaneously.

Will enabling these profiles affect application performance?

Yes, TRACE-level logging generates significant I/O overhead because it captures low-level details like individual streaming chunks and LLM request payloads. According to the source implementation in EnableAgents.java, these profiles are intended for debugging and testing environments only. Always deactivate verbose profiles (thinking, streaming-test) in production deployments to maintain optimal throughput.

Where can I customize the colour scheme for log output?

The colour definitions reside in embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java. This class defines ANSI colour codes as constants that LoggingPersonality references when formatting console output. To implement a custom palette, extend LoggingPersonality and override the formatting methods, or modify the ColorPalette constants before the application context initializes.

Do I need @EnableAgents if I'm only using the cost-tracking profile?

Yes, the @EnableAgents annotation is required regardless of which specific profile you activate. As implemented in EnableAgents.java, this annotation registers the EnvironmentPostProcessor that actually parses the active profiles and injects the corresponding logging.level properties into the Spring Environment. Without this annotation, setting spring.profiles.active=cost-tracking-it will have no effect on the Embabel agent loggers.

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