Skip to main content

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_tokensprompt_tokens, output_tokenscompletion_tokens. Reasoning tokens are subtracted from output_tokens when present.

Example with tools

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.