agents-features-trace/ai.koog.agents.features.tracing.feature/Tracing

Tracing

Feature that collects comprehensive tracing data during agent execution and sends it to configured feature message processors.

Tracing is crucial for evaluation and analysis of the working agent, as it captures detailed information about:

All LLM calls and their responses
Prompts sent to LLMs
Tool calls, arguments, and results
Graph node visits and execution flow
Agent lifecycle events (creation, start, finish, errors)
Strategy execution events

This data can be used for debugging, performance analysis, auditing, and improving agent behavior.

Example of installing tracing to an agent:

val agent = AIAgent(
    promptExecutor = executor,
    strategy = strategy,
    // other parameters...
) {
    install(Tracing) {
        // Configure message processors to handle trace events
        addMessageProcessor(TraceFeatureMessageLogWriter(logger))

        val fileWriter = TraceFeatureMessageFileWriter(
            outputFile,
            { path: Path -> SystemFileSystem.sink(path).buffered() }
        )
        addMessageProcessor(fileWriter)

        // Optionally filter messages
        fileWriter.setMessageFilter { message ->
            // Only trace LLM calls and tool calls
            message is LLMCallStartingEvent || message is ToolCallEvent
        }
    }
}

Example of logs produced by tracing:

AIAgentStartedEvent (agentId: agent-123, runId: session-456, strategyName: my-agent-strategy)
AIAgentStrategyStartEvent (runId: session-456, strategyName: my-agent-strategy)
AIAgentNodeExecutionStartEvent (runId: session-456, nodeName: definePrompt, input: user query)
AIAgentNodeExecutionEndEvent (runId: session-456, nodeName: definePrompt, input: user query, output: processed query)
LLMCallStartingEvent (runId: session-456, prompt: Please analyze the following code...)
LLMCallCompletedEvent (runId: session-456, response: I've analyzed the code and found...)
ToolCallEvent (runId: session-456, toolName: readFile, toolArgs: {"path": "src/main.py"})
ToolCallResultEvent (runId: session-456, toolName: readFile, toolArgs: {"path": "src/main.py"}, result: "def main():...")
AIAgentStrategyFinishedEvent (runId: session-456, strategyName: my-agent-strategy, result: Success)
AIAgentFinishedEvent (agentId: agent-123, runId: session-456, result: Success)

Constructors

Tracing

constructor()

Types

Feature

object Feature : AIAgentGraphFeature<TraceFeatureConfig, Tracing>

Companion object implementing agent feature, handling Tracing creation and installation.