What is Callback Handler?
Callback Handler is a lifecycle hook component that receives events from model calls, tools, retrievers, streams, or orchestration nodes for logging, tracing, metrics, debugging, auditing, or policy enforcement.
How It Works
A Callback Handler is the instrumentation layer of an AI application framework. Instead of embedding logging and tracing code inside every model, tool, retriever, or graph node, callbacks receive standardized lifecycle events such as start, end, error, token, stream chunk, tool call, retrieval result, and node transition. This separation keeps business logic cleaner and makes it possible to connect an AI application to OpenTelemetry, audit logs, cost dashboards, evaluation systems, or live user interfaces.
Key Characteristics
- Lifecycle event interface: observes starts, ends, errors, tokens, streams, tool calls, retrievals, and node transitions
- Separation of concerns: keeps observability and policy hooks outside core business logic
- Streaming support: can forward token or chunk events to user interfaces with low latency
- Operational value: supports cost tracking, latency analysis, debugging, evaluation, and incident response
- Security requirement: must avoid leaking sensitive prompts, retrieved documents, or tool outputs into logs
Common Use Cases
- Creating OpenTelemetry spans for every model call, tool call, and graph node
- Streaming partial model output to a web or chat interface
- Recording token usage, latency, error types, and provider request IDs
- Capturing agent trajectories for debugging and evaluation
- Applying audit policies when an agent attempts a sensitive action
Example
Loading code...Frequently Asked Questions
What events should a Callback Handler capture?
Useful events include component start and end, model tokens, stream chunks, tool calls, retrieval results, errors, retries, graph node transitions, and final outputs. The exact event set depends on the framework.
How is a Callback Handler related to observability?
Callbacks provide the raw lifecycle events that observability systems need. They can create traces, metrics, logs, cost records, and audit events without polluting application business logic.
Can callbacks change application behavior?
Some callbacks are purely observational, while others may enforce policies, cancel execution, redact data, or request human approval. Teams should distinguish read-only callbacks from behavior-changing callbacks.
What is the main risk of callback logging?
The main risk is leaking sensitive data. Prompts, retrieved documents, user data, tool outputs, and credentials must be redacted or excluded according to privacy and security requirements.