A LangChain callback handler is an object with named methods that LangChain calls automatically whenever certain things happen inside a chain or agent run. You subclass `BaseCallbackHandler` and override the methods for the events you care about.
The events are scoped to things LangChain itself controls. There are four big categories: LLM calls, chain runs, tool invocations, and retriever lookups, each with start, end, and error variants (for example `on_llm_start`, `on_llm_end`, `on_llm_error`). Agents add two more: `on_agent_action` and `on_agent_finish`.
Things outside LangChain are not in the surface. GPU kernel timings live inside the model server. User logins live in your auth layer. The callback API cannot see either, and you should not try to instrument them through it.
This surface is what tracing vendors like LangSmith and Langfuse hook into to build their UIs.
The LangChain callback surface is a fixed set of lifecycle hooks for the operations the framework actually orchestrates. The four main triples are LLM calls, chains, tools, and retrievers. Each shaped as `_start`, `_end`, `_error`. Agents add `on_agent_action` and `on_agent_finish` because the agent loop is a distinct control structure that emits per-step decisions.
What you hook by subclassing `BaseCallbackHandler` is uniform across these events. You get a run id, a parent run id (which lets you reconstruct a trace tree), the inputs at start, and the outputs at end. This is enough to build a complete causal trace of one user request without modifying any chain code.
The distractors in the question are a useful test of mental model. `on_gpu_kernel_*` sits inside the model server, TensorRT, vLLM, the CUDA driver, and is invisible to the application layer LangChain occupies. `on_user_*` sits in the auth layer, Auth0, Clerk, your own session middleware, and is invisible to LangChain for the same reason.
Knowing this matters because the same callbacks are how LangSmith, Langfuse, Phoenix, Helicone, and OpenTelemetry exporters wire in. Pick the wrong scope and your tracing vendor sees nothing.
Quick reference
TL;DR
LangChain's BaseCallbackHandler exposes start/end/error events for LLM calls, chains, tools, and retrievers, plus agent action/finish, and nothing about GPU or auth.
Imagine a relay race coach who can only stopwatch the runners on her own team. She can clock when each runner starts a leg, when they finish, and whether they dropped the baton. She cannot clock the scoreboard wiring or the parking attendants because those are not her runners. LangChain's coach watches its own runners, model calls, chains, tools, retrievers, and tells you when each one started, ended, or tripped. Anything happening outside her team, like graphics-card timings or login screens, lives on a different scoreboard entirely.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
Capturing hardware-level signals like GPU utilization or kernel timings Those live in the model server; instrument it directly with NVML or vendor exporters
Auditing authentication or session events for compliance reporting Auth events live in your identity layer; piping them through LangChain couples concerns that should stay separate
Token by token streaming metrics for a hot inference path with strict latency budgets Per-call callbacks add overhead; streaming-level instrumentation belongs in the streaming layer itself
Quick scan · 2–4 min
Everything important, quickly.
5 minutes: the four event categories, the agent events, the scope boundary, and the tracing-vendor wiring pattern.