What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To debug a LangGraph agent, first enable LangSmith tracing and reproduce the failing input. Follow the trace’s nested runs to identify the model call, tool, or retrieval involved; use Studio Graph mode to inspect nodes and intermediate state; then use checkpoint history to replay or branch execution when you need to test a change. Traces explain what happened, while checkpoints let you resume or fork graph execution.
1. Enable tracing and reproduce the problem
For LangGraph applications using LangChain components, LangChain’s official observability guide documents enabling tracing with LANGSMITH_TRACING=true and providing LANGSMITH_API_KEY. Configure your model provider’s credentials separately. If your LangSmith workspace is outside the default US region, set the regional LANGSMITH_ENDPOINT described in the JavaScript observability guide.
Run the input that produces the failure after tracing is enabled. Add useful context—such as environment, application version, tags, or metadata—so you can distinguish a local reproduction from a production run. The documented LangSmith integration traces LangChain calls automatically in its example, but provider credentials and workspace configuration still need to be correct.
If no trace appears
- Confirm tracing is enabled and that the API key points to the intended LangSmith workspace.
- Check that
LANGSMITH_ENDPOINTmatches the workspace region when it is not in the default US region. - For JavaScript serverless deployments, check whether callback background settings affect delivery; the LangSmith JavaScript guide discusses this distinction.
2. Follow the trace to the failing work
LangSmith represents a trace as a collection of nested runs. A run is one unit of work, such as a model call, tool invocation, or retrieval. In the trace’s Details view, inspect the run tree and its inputs, outputs, errors, and timing to find where the result first diverges from what you expected. The LangChain observability guide explains the tracing workflow and available views.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
Use Trajectory when you need the agent’s sequence of messages and tool calls in a simpler, ordered conversation view. It is easier to scan for the flow of interaction, but it does not provide the same execution detail as the nested trace tree. Choose Details to investigate which particular run failed or returned unexpected data; choose Trajectory to understand the agent’s conversational sequence.
When a custom call is missing
Automatic instrumentation does not necessarily capture arbitrary custom functions or direct provider SDK calls. Add a LangSmith tracing wrapper or decorator—@traceable in Python or traceable in JavaScript, as applicable—to create nested runs for work that would otherwise be invisible. The Python and JavaScript guides describe tracing setup and instrumentation.
3. Inspect graph nodes and intermediate state in Studio
A trace shows execution runs, but the graph-level question—what state did the agent have as it moved through nodes?—is better answered in LangGraph Studio. Its Graph mode visualizes traversed nodes and intermediate states. LangChain describes Studio as an agent IDE for visualization, interaction, and debugging of systems implementing the Agent Server API protocol; the Studio documentation explains its requirements and connections.
Studio can connect to deployed graphs or to graphs running locally through Agent Server. It is not required for basic LangSmith tracing. Use it when you need to see graph structure and state interactively; use the trace when you need to inspect nested model, tool, or retrieval runs.
4. Replay from a checkpoint or test a fork
When the graph persists checkpoints, LangGraph’s time-travel APIs let you inspect prior state and continue execution from a selected point. This is distinct from trace inspection: a trace helps explain a run, while a checkpoint provides saved graph state from which execution can resume or branch. The time-travel guide covers checkpoint history, replay, and forking.
Replay downstream work
- Use
get_state_historyto find the checkpoint immediately before the node you want to investigate. - Take the configuration associated with that checkpoint and invoke the graph from it.
- Inspect the new downstream execution to see how the later nodes behave from that saved state.
Replay re-executes downstream nodes; it does not simply read their results from cache. LLM calls, API requests, and interrupts may run again and return different results. If those operations cause external side effects, account for that before replaying.
Fork with a changed state
- Choose a prior checkpoint in the thread’s state history.
- Use
update_statewith that checkpoint configuration to change the state value you want to test. - Invoke using the resulting configuration and compare the new branch’s routing or output with the original execution.
A fork preserves the prior history and creates a new branch; it does not erase or roll back the original thread. This is useful for testing a specific hypothesis, such as whether a changed value would have sent the graph down a different route.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.5. Protect sensitive data and know the trace limit
Trace inputs and outputs can contain application data. Before sending them to an observability service, decide what the application is allowed to log. LangChain’s Python observability documentation shows an anonymizer that redacts matching sensitive data before trace transmission; apply suitable data minimization or redaction for your own requirements.
Recommended Free Tools
LangChain’s LangSmith observability concepts documentation states that a trace can contain up to 25,000 runs and that additional runs sent after that maximum are rejected. This is a LangSmith trace limit, not a limit on how many nodes a LangGraph can contain. See LangSmith observability concepts.
The official documentation pages cited here do not establish a stable LangGraph or LangSmith version number or publication date. APIs and examples can evolve, so check them against the versions installed in your application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
