Installation
Setup
We recommend using UUIDs for session_id and user_id so traces can be grouped reliably across runs.
Usage
The handler works with both langchain.agents.create_agent and plain LCEL pipelines (prompt | model | parser). Pass it via LangChain’s config["callbacks"]:
The handler must be passed in config["callbacks"] for each invocation. There is no global instrument() step.
What gets traced
Trace name remapping
create_agent compiles to a LangGraph graph internally, so its root run reports name="LangGraph". LCEL pipelines report name="RunnableSequence". The handler rewrites both to "LangChain" so the trace is named consistently — custom user-given chain names are preserved.
Token usage
Token usage is extracted from LangChain’s usage_metadata (primary) or legacy llm_output.token_usage (fallback). The mapping is: input_tokens → prompt_tokens, output_tokens → completion_tokens. Reasoning tokens are subtracted from output_tokens when present.
This example builds a LangChain agent via create_agent with one tool and traces it via LangChainCallbackHandler:
This produces a trace with: CHAIN (root, named “LangChain”) → AGENT (tools node) → LLM (model call) → TOOL (get_weather) → TOOL (get_population) → LLM (final response).
LCEL pipelines
The handler also works for plain LCEL chains. The trace is named “LangChain” by default (the underlying RunnableSequence name is rewritten) so LCEL runs are labeled consistently with agent runs.