Debug agent behavior
Inspect prompts, tool calls, intermediate steps, and outputs while developing an agent.
AI Agents · Const
Tracing
Tracing records the steps an agent takes from input to output as LangSmith runs. Enable it with LangSmith environment variables to inspect execution and debug LangGraph applications.
How it works
Tracing records an application's execution as a sequence of runs, allowing LangSmith to display the steps from input to output. For a LangGraph.js application, enable it with environment variables; LangSmith then visualizes graph execution and helps debug agent behavior.
Syntax
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>Parameters
| Name | Type | Description |
|---|---|---|
LANGSMITH_TRACING | environment variable | Set to true to enable LangSmith tracing. |
LANGSMITH_API_KEY | environment variable | LangSmith API key used for authentication. |
Returns
A LangSmith trace containing runs for the application's execution.
Key points
- A trace models the complete path an application follows from its input to its output.
- Every step within that path is recorded as an individual run.
- Tracing supports debugging a locally running application.
- The basic setup uses environment variables to turn tracing on and authenticate with LangSmith.
- Without another project configuration, traces are sent to the default LangSmith project.
Common mistakes
- In serverless deployments, set background callbacks to finish tracing before the function exits.
- Custom SDK calls and functions need an appropriate tracing wrapper to appear as nested traces.
Example: Enable LangGraph tracing
import { ChatOpenAI } from "@langchain/openai";
import { StateGraph, START, END, Annotation } from "@langchain/langgraph";
const State = Annotation.Root({
messages: Annotation<any[]>({ reducer: (a, b) => a.concat(b), default: () => [] }),
});
const model = new ChatOpenAI({ model: "gpt-4o-mini" });
const graph = new StateGraph(State)
.addNode("agent", async (state) => ({ messages: [await model.invoke(state.messages)] }))
.addEdge(START, "agent")
.addEdge("agent", END)
.compile();
const result = await graph.invoke({ messages: ["Explain tracing"] });
console.log(result.messages.at(-1)?.content);Run the graph with LangSmith tracing enabled through the environment.
When to use it
Monitor production runs
Review execution paths and failures in a deployed application.
Understand execution flow
Analyze how graph nodes and model calls contribute to an answer.
Interview questions
QWhat does tracing provide for a LangGraph application?
Tracing represents an application's work as a sequence of runs, where each step from input to output can be inspected in LangSmith. It is enabled for LangGraph applications through the LangSmith tracing configuration.
Follow-up: How would you trace a custom function? Wrap or decorate it with the supported traceable utility so LangSmith can nest its run.
QHow is LangSmith tracing enabled?
Set LANGSMITH_TRACING=true and provide LANGSMITH_API_KEY. Once configured, LangSmith can visualize the application's execution steps.
Follow-up: How can tracing be disabled locally? Set LANGSMITH_TRACING=false so trace data is not sent.
QAre custom functions and SDK calls traced automatically?
LangGraph and LangChain modules can be traced automatically after the tracing environment is configured. Other SDKs or custom functions must be wrapped appropriately for their runs to be included and nested.
Follow-up: What serverless concern must be handled? Ensure tracing is not left in background mode when the execution context may end early.
Related
LangSmithLangGraphLangChainTracertraceableLANGSMITH_TRACING_BACKGROUND