Agent Callbacks
Callbacks provide hooks into agent execution, allowing you to monitor progress, log activities, handle errors, and integrate with external systems. The Go AI SDK supports both legacy callbacks and LangChain-style callbacks for enhanced interoperability.
Overview
Agent callbacks enable you to:
- Monitor execution: Track agent progress and decisions
- Log activities: Record tool calls, actions, and results
- Handle errors: Implement custom error recovery logic
- Measure performance: Track token usage and execution time
- Integrate with observability: Connect to logging and monitoring platforms
- Debug agent behavior: Understand decision-making processes
Callback Types
Legacy Callbacks
These callbacks provide basic step-level tracking:
| Callback | Invoked When | Parameters |
|---|---|---|
OnStepStart | Step begins | stepNum int |
OnStepFinish | Step completes | step types.StepResult |
OnToolCall | Tool is called | toolCall types.ToolCall |
OnToolResult | Tool execution completes | toolResult types.ToolResult |
OnFinish | Agent completes | result *AgentResult |
LangChain-Style Callbacks (v6.0.60+)
These callbacks provide fine-grained control and align with LangChain's callback system:
Chain Lifecycle
| Callback | Invoked When | Parameters |
|---|---|---|
OnChainStart | Agent begins execution | input string, messages []types.Message |
OnChainEnd | Agent completes successfully | result *AgentResult |
OnChainError | Agent encounters an error | err error |
Agent Decisions
| Callback | Invoked When | Parameters |
|---|---|---|
OnAgentAction | Agent decides to take an action | action AgentAction |
OnAgentFinish | Agent reaches a final answer | finish AgentFinish |
Tool Lifecycle
| Callback | Invoked When | Parameters |
|---|---|---|
OnToolStart | Tool execution begins | toolCall types.ToolCall |
OnToolEnd | Tool completes successfully | toolResult types.ToolResult |
OnToolError | Tool execution fails | toolCall types.ToolCall, err error |
Basic Usage
import (
"context"
"log"
"github.com/digitallysavvy/go-ai/pkg/agent"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
)
myAgent := agent.NewToolLoopAgent(agent.AgentConfig{
Model: model,
System: "You are a helpful assistant.",
Tools: tools,
// Legacy callbacks
OnStepStart: func(stepNum int) {
log.Printf("Starting step %d", stepNum)
},
OnStepFinish: func(step types.StepResult) {
log.Printf("Step %d finished: %s", step.StepNumber, step.FinishReason)
},
// LangChain-style callbacks
OnChainStart: func(input string, messages []types.Message) {
log.Printf("Agent starting with input: %s", input)
},
OnChainEnd: func(result *agent.AgentResult) {
log.Printf("Agent completed in %d steps", len(result.Steps))
},
OnChainError: func(err error) {
log.Printf("Agent error: %v", err)
},
})
Common Use Cases
Logging Agent Execution
Track the complete execution flow:
import (
"fmt"
"time"
)
var startTime time.Time
config := agent.AgentConfig{
Model: model,
Tools: tools,
OnChainStart: func(input string, messages []types.Message) {
startTime = time.Now()
fmt.Printf("\n=== Agent Started ===\n")
fmt.Printf("Input: %s\n", input)
},
OnAgentAction: func(action agent.AgentAction) {
fmt.Printf("\n[Step %d] Agent Action\n", action.StepNumber)
fmt.Printf(" Tool: %s\n", action.ToolCall.ToolName)
if action.Reasoning != "" {
fmt.Printf(" Reasoning: %s\n", action.Reasoning)
}
},
OnAgentFinish: func(finish agent.AgentFinish) {
fmt.Printf("\n[Step %d] Agent Finished\n", finish.StepNumber)
fmt.Printf(" Output: %s\n", finish.Output)
fmt.Printf(" Reason: %s\n", finish.FinishReason)
},
OnChainEnd: func(result *agent.AgentResult) {
duration := time.Since(startTime)
fmt.Printf("\n=== Agent Completed ===\n")
fmt.Printf("Duration: %s\n", duration)
fmt.Printf("Steps: %d\n", len(result.Steps))
fmt.Printf("Tool calls: %d\n", len(result.ToolResults))
fmt.Printf("Total tokens: %d\n", result.Usage.GetTotalTokens())
},
}
Tracking Token Usage and Costs
Monitor API usage for cost tracking:
type UsageTracker struct {
totalTokens int64
totalCost float64
toolCallCount int
costPerToken float64 // Cost per 1000 tokens
}
func (t *UsageTracker) addUsage(tokens int64) {
t.totalTokens += tokens
t.totalCost += float64(tokens) * t.costPerToken / 1000.0
}
tracker := &UsageTracker{
costPerToken: 0.002, // $0.002 per 1K tokens (example rate)
}
config := agent.AgentConfig{
Model: model,
Tools: tools,
OnStepFinish: func(step types.StepResult) {
if step.Usage.GetTotalTokens() > 0 {
tracker.addUsage(step.Usage.GetTotalTokens())
}
},
OnToolEnd: func(toolResult types.ToolResult) {
tracker.toolCallCount++
},
OnChainEnd: func(result *agent.AgentResult) {
fmt.Printf("\n=== Usage Summary ===\n")
fmt.Printf("Total tokens: %d\n", tracker.totalTokens)
fmt.Printf("Estimated cost: $%.4f\n", tracker.totalCost)
fmt.Printf("Tool calls: %d\n", tracker.toolCallCount)
fmt.Printf("Average tokens per step: %d\n",
tracker.totalTokens/int64(len(result.Steps)))
},
}
Error Handling and Recovery
Implement custom error handling:
config := agent.AgentConfig{
Model: model,
Tools: tools,
OnChainError: func(err error) {
log.Printf("Chain error occurred: %v", err)
// Send alert
sendAlert("Agent execution failed", err.Error())
// Log to external service
logToObservability("agent.error", map[string]interface{}{
"error": err.Error(),
"timestamp": time.Now(),
})
},
OnToolError: func(toolCall types.ToolCall, err error) {
log.Printf("Tool %s failed: %v", toolCall.ToolName, err)
// Track tool failures
metrics.IncrementCounter("tool.failures", map[string]string{
"tool_name": toolCall.ToolName,
})
// Implement retry logic elsewhere if needed
// (Note: callbacks should not modify execution flow directly)
},
}
Performance Monitoring
Track execution time for each component:
type PerformanceMonitor struct {
toolTimes map[string]time.Duration
toolStarts map[string]time.Time
stepTimes []time.Duration
stepStart time.Time
}
func NewPerformanceMonitor() *PerformanceMonitor {
return &PerformanceMonitor{
toolTimes: make(map[string]time.Duration),
toolStarts: make(map[string]time.Time),
stepTimes: make([]time.Duration, 0),
}
}
monitor := NewPerformanceMonitor()
config := agent.AgentConfig{
Model: model,
Tools: tools,
OnStepStart: func(stepNum int) {
monitor.stepStart = time.Now()
},
OnStepFinish: func(step types.StepResult) {
duration := time.Since(monitor.stepStart)
monitor.stepTimes = append(monitor.stepTimes, duration)
},
OnToolStart: func(toolCall types.ToolCall) {
monitor.toolStarts[toolCall.ID] = time.Now()
},
OnToolEnd: func(toolResult types.ToolResult) {
if startTime, ok := monitor.toolStarts[toolResult.ToolCallID]; ok {
duration := time.Since(startTime)
monitor.toolTimes[toolResult.ToolName] += duration
delete(monitor.toolStarts, toolResult.ToolCallID)
}
},
OnChainEnd: func(result *agent.AgentResult) {
fmt.Printf("\n=== Performance Report ===\n")
// Step timings
var totalStepTime time.Duration
for i, duration := range monitor.stepTimes {
fmt.Printf("Step %d: %s\n", i+1, duration)
totalStepTime += duration
}
fmt.Printf("Average step time: %s\n",
totalStepTime/time.Duration(len(monitor.stepTimes)))
// Tool timings
fmt.Printf("\nTool execution times:\n")
for toolName, duration := range monitor.toolTimes {
fmt.Printf(" %s: %s\n", toolName, duration)
}
},
}
Integration with Observability Platforms
Connect to external monitoring systems:
import (
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/trace"
)
tracer := otel.Tracer("agent-execution")
config := agent.AgentConfig{
Model: model,
Tools: tools,
OnChainStart: func(input string, messages []types.Message) {
ctx, span := tracer.Start(context.Background(), "agent.execute")
span.SetAttributes(attribute.String("input", input))
// Store ctx for later use
},
OnAgentAction: func(action agent.AgentAction) {
_, span := tracer.Start(context.Background(), "agent.action")
span.SetAttributes(
attribute.String("tool", action.ToolCall.ToolName),
attribute.Int("step", action.StepNumber),
)
defer span.End()
},
OnToolStart: func(toolCall types.ToolCall) {
_, span := tracer.Start(context.Background(), "tool.execute")
span.SetAttributes(attribute.String("tool", toolCall.ToolName))
// Store span for completion in OnToolEnd
},
OnChainEnd: func(result *agent.AgentResult) {
// Complete the main span
// span.SetAttributes(...)
// span.End()
},
}
Data Types
AgentAction
Represents an action the agent has decided to take:
type AgentAction struct {
ToolCall types.ToolCall // The tool being called
StepNumber int // Step when action was decided
Reasoning string // Agent's reasoning for the action
RunID string // Unique identifier for this agent execution chain
ParentRunID string // ID of the parent run (empty for top-level runs)
Tags []string // User-defined labels for categorizing runs
}
AgentFinish
Represents the agent's final decision:
type AgentFinish struct {
Output string // Final output text
StepNumber int // Step when agent finished
FinishReason types.FinishReason // Why the agent finished
Metadata map[string]interface{} // Additional metadata
RunID string // Unique identifier for this agent execution chain
ParentRunID string // ID of the parent run (empty for top-level runs)
Tags []string // User-defined labels for categorizing runs
}
Best Practices
1. Keep Callbacks Fast
Callbacks are invoked during execution. Long-running operations can slow down the agent:
// ❌ Bad: Slow synchronous operation
OnToolEnd: func(toolResult types.ToolResult) {
saveToDatabaseSync(toolResult) // Blocks execution
},
// ✅ Good: Async logging
OnToolEnd: func(toolResult types.ToolResult) {
go saveToDatabaseAsync(toolResult) // Non-blocking
},
2. Handle Errors in Callbacks
Panics in callbacks can crash your application:
OnChainEnd: func(result *agent.AgentResult) {
defer func() {
if r := recover(); r != nil {
log.Printf("Callback panic: %v", r)
}
}()
// Your callback code
},
3. Don't Modify Agent State
Callbacks should observe, not modify:
// ❌ Bad: Trying to modify execution
OnAgentAction: func(action agent.AgentAction) {
// Don't try to cancel or modify the action
},
// ✅ Good: Just observe and log
OnAgentAction: func(action agent.AgentAction) {
log.Printf("Agent is calling: %s", action.ToolCall.ToolName)
},
4. Use Appropriate Callback Level
Choose between legacy and LangChain-style callbacks based on your needs:
- Legacy callbacks: Simple step tracking, basic monitoring
- LangChain-style callbacks: Detailed lifecycle management, LangChain compatibility, fine-grained control
5. Thread Safety
If callbacks access shared state, ensure thread safety:
type SafeCounter struct {
mu sync.Mutex
count int
}
func (c *SafeCounter) Increment() {
c.mu.Lock()
defer c.mu.Unlock()
c.count++
}
counter := &SafeCounter{}
config := agent.AgentConfig{
OnToolEnd: func(toolResult types.ToolResult) {
counter.Increment() // Thread-safe
},
}
Combining Callbacks
You can use both legacy and LangChain-style callbacks together:
config := agent.AgentConfig{
Model: model,
Tools: tools,
// Legacy - for backward compatibility
OnStepFinish: func(step types.StepResult) {
// Your existing logic
},
// LangChain-style - for new features
OnChainStart: func(input string, messages []types.Message) {
// Enhanced tracking
},
OnAgentAction: func(action agent.AgentAction) {
// Fine-grained action monitoring
},
}
Run Tracking (v6.0.61+)
Run tracking enables you to correlate all callbacks, actions, and events from a single agent execution using unique identifiers. This is particularly useful for observability, debugging, and distributed tracing.
Run Tracking Fields
Each AgentAction and AgentFinish includes:
RunID: Unique identifier for this agent execution chainParentRunID: ID of the parent run (for subagents/nested executions)Tags: User-defined labels for categorizing runs
Automatic RunID Generation
Run IDs are automatically generated when an agent starts:
agent := agent.NewToolLoopAgent(agent.AgentConfig{
Model: model,
OnAgentAction: func(action agent.AgentAction) {
// RunID is automatically populated
log.Printf("Action in run %s: %s", action.RunID, action.ToolCall.ToolName)
},
})
result, err := agent.Execute(context.Background(), "question")
// RunID is automatically generated and propagated
Custom Run IDs and Tags
Provide your own run ID and tags using context helpers:
import "github.com/digitallysavvy/go-ai/pkg/agent"
ctx := context.Background()
// Option 1: Add tags only (RunID auto-generated)
ctx = agent.WithTags(ctx, []string{"production", "user:123", "session:abc"})
// Option 2: Custom RunID
ctx = agent.WithRunID(ctx, "my-custom-run-id-123")
ctx = agent.WithTags(ctx, []string{"experiment", "variant:A"})
// Option 3: Nested execution (subagent tracking)
parentCtx := agent.WithRunID(ctx, "parent-run-456")
subagentCtx := agent.WithParentRunID(parentCtx, "parent-run-456")
subagentCtx = agent.WithRunID(subagentCtx, "subagent-run-789")
result, err := myAgent.Generate(ctx, agent.AgentGenerateOptions{Prompt: "question"})
Retrieving Run Tracking Info
Extract run tracking information from context:
runID := agent.GetRunID(ctx)
parentRunID := agent.GetParentRunID(ctx)
tags := agent.GetTags(ctx)
log.Printf("Executing run %s with tags: %v", runID, tags)
Use Cases for Run Tracking
1. Distributed Tracing
Correlate agent execution with other services:
import "go.opentelemetry.io/otel/trace"
// Get trace ID from OpenTelemetry
span := trace.SpanFromContext(ctx)
traceID := span.SpanContext().TraceID().String()
// Use trace ID as run ID for correlation
ctx = agent.WithRunID(ctx, traceID)
ctx = agent.WithTags(ctx, []string{"service:agent", "env:production"})
config := agent.AgentConfig{
Model: model,
OnAgentAction: func(action agent.AgentAction) {
// Log with trace ID for correlation
log.Printf("[trace=%s] Agent action: %s",
action.RunID, action.ToolCall.ToolName)
},
}
2. Multi-Tenant Observability
Track executions by user or session:
// Tag runs with user/session info
ctx = agent.WithTags(ctx, []string{
fmt.Sprintf("user:%s", userID),
fmt.Sprintf("session:%s", sessionID),
"plan:premium",
})
config := agent.AgentConfig{
OnAgentFinish: func(finish agent.AgentFinish) {
// Store metrics tagged by user
metrics.RecordAgentCompletion(
finish.RunID,
finish.Tags,
len(finish.Metadata),
)
},
}
3. A/B Testing and Experiments
Track different agent configurations:
experimentID := "exp-123-variant-A"
ctx = agent.WithRunID(ctx, experimentID)
ctx = agent.WithTags(ctx, []string{
"experiment:prompt-variations",
"variant:A",
"temperature:0.7",
})
config := agent.AgentConfig{
OnChainEnd: func(result *agent.AgentResult) {
// Log results for experiment analysis
experimentTracker.LogResult(experimentID, result)
},
}
4. Subagent Hierarchies
Track parent-child relationships in delegations:
func executeWithSubagent(parentCtx context.Context) {
parentRunID := agent.GetRunID(parentCtx)
// Create subagent context with parent tracking
subagentCtx := agent.WithParentRunID(context.Background(), parentRunID)
subagentCtx = agent.WithTags(subagentCtx, []string{"type:subagent", "role:researcher"})
subagent := agent.NewToolLoopAgent(agent.AgentConfig{
Model: model,
OnChainStart: func(input string, messages []types.Message) {
runID := agent.GetRunID(subagentCtx)
log.Printf("Subagent %s starting (parent: %s)", runID, parentRunID)
},
})
result, err := subagent.Execute(subagentCtx, "research question")
}
5. Performance Analysis
Group and analyze runs by tags:
ctx = agent.WithTags(ctx, []string{
"tool:search",
"complexity:high",
"priority:p0",
})
config := agent.AgentConfig{
OnChainEnd: func(result *agent.AgentResult) {
// Store metrics for later analysis
analytics.RecordExecution(analytics.Execution{
RunID: agent.GetRunID(ctx),
Tags: agent.GetTags(ctx),
Duration: time.Since(startTime),
TokensUsed: result.Usage.GetTotalTokens(),
StepCount: len(result.Steps),
})
},
}
// Later: Query executions by tags
highComplexityRuns := analytics.FindByTag("complexity:high")
Examples
See complete examples in examples/agents/callbacks/:
- onstepfinish: Basic step tracking with OnStepFinish
- early-stopping: Token limit monitoring with callbacks
- langchain-style: Comprehensive example of all LangChain-style callbacks (includes run tracking demo)
Next Steps
- Explore Agent Workflows for complex agent patterns
- Learn about Loop Control for execution management
- See Agent Configuration for more options
Introduced in v6.0.60: LangChain-style callbacks (OnChainStart, OnChainEnd, OnChainError, OnAgentAction, OnAgentFinish, OnToolStart, OnToolEnd, OnToolError)
Introduced in v6.0.61: Run tracking with RunID, ParentRunID, and Tags fields in AgentAction and AgentFinish