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))
addMessageProcessor(TraceFeatureMessageFileWriter(outputFile, fileSystem::sink))
// Optionally filter messages
messageFilter = { message ->
// Only trace LLM calls and tool calls
message is BeforeLLMCallEvent || message is ToolCallEvent
}
}
}Content copied to clipboard
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)
BeforeLLMCallEvent (runId: session-456, prompt: Please analyze the following code...)
AfterLLMCallEvent (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)Content copied to clipboard