groundy
Agents & Frameworks

How to Debug LangGraph Agents With LangSmith Trajectory and Details Views

LangSmith Trajectory shows top-level chat, while Details reveals execution paths. Verify instrumentation and region settings before trusting either view for debugging LangGr

Published 7 references
On this page11 sections

Use LangSmith’s Trajectory view to inspect the conversation, not to certify the run. LangChain’s tracing documentation defines Trajectory as a simplified, chat-like rendering of messages from the top-level trace: the user’s initial request, tool calls, and the agent’s final response. When the question is what the graph actually executed, open the trace and switch to Details view.

Before either view can help, tracing has to cover the code your graph uses. LangChain-module graphs need only the documented environment-variable setup. Other SDKs and custom functions require explicit wrapping, and non-US accounts need the correct regional endpoint. A clean transcript produced after incomplete instrumentation is a debugging lead, not verification.

A clean transcript is not the whole run record

The distinction matters because an agent run can be much larger than its visible conversation. LangChain’s observability documentation describes agent traces as deeply nested, with heavy payloads: a single conversation can generate megabytes of data across dozens of runs and tool calls. That is a vendor description rather than an independent measurement of your application, but it establishes the structural problem. A chat-shaped projection cannot simultaneously be the complete record of a deeply nested run.

This is an old debugging principle, not an agent-specific one. The 2003 paper on omniscient debugging argues that recording every state change makes the information needed for debugging available, including the ability to reason backwards through execution. That research does not establish what LangSmith records or displays. It does clarify why a summary should not be confused with the underlying execution evidence.

For a LangGraph developer, the practical failure mode is straightforward: the final answer can look reasonable while the interesting mistake sits elsewhere, such as in an intermediate prompt, a tool output, a state transition, or the path taken through the graph. Independent coverage of LangGraph also identifies debugging complex graphs as a challenge. That does not demonstrate a particular LangSmith failure, but it supports replacing ad-hoc transcript reading with a repeatable inspection procedure.

Set up tracing for the code you actually run

Current documentation supports tracing LangGraph agents in Python and JavaScript, whether they use LangChain modules or other SDKs. LangGraph’s repository identifies LangGraph.js as the JavaScript and TypeScript counterpart. The instrumentation path depends on the dependencies inside the graph, not merely on the fact that the outer framework is LangGraph.

That distinction is easy to miss because LangGraph examples often use LangChain integrations. The current LangGraph overview explicitly says LangGraph does not require LangChain. Consequently, there are two setup cases:

  1. The graph uses LangChain modules. According to the LangGraph tracing guide, you only need to set a few environment variables. When runnables are invoked normally, LangSmith infers the appropriate tracing configuration. Use that guide for the current variable names and values rather than assuming that tracing is enabled by default.

  2. The graph uses other SDKs or custom functions. Wrap or decorate those operations. The documentation names @traceable for Python, traceable for JavaScript, and SDK wrappers such as wrap_openai as examples. LangSmith then automatically nests traces from the wrapped methods.

The second requirement deserves an inventory of the graph before debugging begins. The documentation promises automatic nesting for wrapped methods; it does not promise equivalent trace coverage for arbitrary unwrapped calls. It is therefore a bounded inference, not a reported product test, that a graph mixing LangChain modules with unwrapped SDK calls could present a plausible top-level conversation while parts of its execution produce no nested trace data.

I would resolve that instrumentation question before interpreting either view. Otherwise, an empty or thinner-than-expected portion of a trace is difficult to distinguish from an agent behavior that simply did not occur.

Check the region before blaming the graph

For accounts outside the default US region, set LANGSMITH_ENDPOINT to the API URL for the account’s region. LangChain’s guide says that without this setting, the API key is not recognized and requests fail to authenticate. The documented regions are GCP US, GCP EU, GCP APAC, and AWS US; its EU example is:

LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com

If a non-US setup produces authentication failures or missing traces, this is the first documented configuration check. It is not an exhaustive diagnosis of missing-trace causes. The supplied documentation establishes this regional failure mode, but it does not enumerate other reasons a trace may be absent.

Trajectory answers a deliberately narrow question

Trajectory is useful when the debugging question concerns the conversation’s top-level shape. Its documented contents include:

  • the user’s initial request;
  • tool calls drawn from the top-level trace; and
  • the agent’s final response.

That makes it a reasonable first stop for questions such as whether the run received the expected request, whether the visible tool-call sequence matches the intended interaction, or whether the final response belongs to the conversation you thought you ran.

Its scope is also its limitation. LangChain calls it a simplified conversation history and says it pulls messages from the top-level trace. The documentation does not say that this view exposes every nested run, intermediate prompt, state transition, or runtime measurement. You should therefore avoid converting “the conversation looks right” into “the graph followed the right path” or “every tool executed correctly.”

This is especially important when the output is fluent. A plausible answer establishes that there is a plausible answer in the projection. It does not, by itself, settle the execution history that produced it.

Details is the next inspection surface, not a documented field list

To open Details view, click the trace and use the Details toggle at the top right, according to the tracing guide. That is the documented navigation procedure.

The guide does not enumerate the fields, tabs, or omissions in Details view. Other sources establish why execution-level inspection belongs there without supplying a precise field specification. LangGraph’s repository describes LangSmith debugging as visualizing execution paths, capturing state transitions, and providing runtime metrics. Separately, IBM’s LangSmith explainer says developers can inspect individual prompts and responses, intermediate steps in chains and agents, and tool calls with their outputs.

Those sources support using Details when the question concerns execution evidence. They do not prove that every named item appears under a particular label in the current Details UI. Treat execution paths, state transitions, runtime metrics, and intermediate-step inspection as the kinds of evidence to seek in the full trace, not as a guaranteed checklist for every deployment.

Match the view to the debugging question

The following procedure is an editorial synthesis of the documented view scope and tracing behavior. It is not a LangChain field-by-field specification.

Debugging questionBest first moveWhat it can help establishRemaining limit
Did the top-level request, tool calls, and final response form the expected conversation?Start with TrajectoryThe documented chat-shaped projection of top-level messagesIt does not establish that every nested operation is represented
Which path did the graph take?Open Details and inspect the execution evidenceLangSmith is documented as supporting execution-path visualization for LangGraphThe exact presentation and fields must be checked in your UI
How did graph state change during the run?Use DetailsState-transition capture is part of LangChain’s description of LangSmith debuggingThe tracing guide does not enumerate a state-transition field in Details
Which prompt, model response, or tool output led to the result?Use Details and inspect the relevant nested traceIndependent documentation describes inspection of prompts, responses, intermediate steps, and tool outputsUnwrapped operations may not have nested trace data
Where did runtime cost or latency accumulate?Start with Details and look for runtime evidenceLangChain describes detailed runtime metrics as part of LangSmith debuggingNo particular metric, tab, or plan availability is established here
Why is there no trace, or why does coverage look incomplete?Check setup before either viewRegional authentication and required wrapping are documented failure pointsOther missing-trace causes remain unverified

The table’s central rule is that a view cannot recover evidence that was never collected. If instrumentation or authentication failed, changing from Trajectory to Details is not the first fix.

When traces are missing or thinner than expected

Work through collection in this order:

  1. Confirm the account region. A non-US account without LANGSMITH_ENDPOINT has a documented authentication failure mode.
  2. Classify the graph’s dependencies. LangChain modules follow the environment-variable path; other SDKs and custom functions need the appropriate decorator or wrapper.
  3. Check coverage at integration boundaries. Pay particular attention to direct SDK calls and custom functions sitting between LangChain-managed steps. The documentation’s automatic-nesting promise applies after wrapping.
  4. Inspect a reproducible run again. This is an editorial recommendation rather than a documented recovery guarantee: correcting setup and rerunning a small failing case gives you a cleaner trace to interpret than continuing to reason from an incomplete one.

Do not generalize this into a complete missing-trace troubleshooting guide. The evidence supports regional authentication and instrumentation gaps as checks. Network failures, permissions beyond the documented regional case, sampling behavior, and other possible causes are not established by the supplied research.

The decision, with the documentation’s limits intact

For routine conversation inspection, start with Trajectory and keep the conclusion narrow: whether the top-level exchange looks as expected. For a wrong branch, suspicious state, unexpected intermediate output, or runtime investigation, toggle to Details and inspect the execution trace. If a release decision depends on those execution facts, I would not accept a clean Trajectory transcript as sufficient evidence.

This procedure is based on documentation checked on November 20, 2026, not original hands-on product testing. The exact Details fields and omissions, view availability across plans and self-hosted deployments, missing-trace causes beyond the documented cases, and UI labels beyond the top-right toggle still need verification in your own LangSmith environment. Those limits change how confidently you should describe the interface, but not the core decision: use the simplified view for the simplified question, and require execution evidence when the execution is what you are debugging.

Frequently Asked Questions

How do I set up tracing for a LangGraph agent that uses LangChain modules?

According to the LangGraph tracing guide, you only need to set a few environment variables. When runnables are invoked normally, LangSmith infers the appropriate tracing configuration. Use that guide for the current variable names and values rather than assuming that tracing is enabled by default.

What should I check if I am using a non-US LangSmith account?

For accounts outside the default US region, set LANGSMITH_ENDPOINT to the API URL for the account’s region. LangChain’s guide says that without this setting, the API key is not recognized and requests fail to authenticate.

References

Follow the links in the article for context. The supporting material is collected here for further reading.

  1. LangChain tracing documentationdocs.langchain.comAccessed
  2. LangChain observability documentationlangchain.comAccessed
  3. Omniscient debugging paperarxiv.orgAccessed
  4. LangChain vs LangGraphgeeksforgeeks.orgAccessed
  5. LangGraph repositorygithub.comAccessed
  6. LangGraph overviewdocs.langchain.comAccessed
  7. IBM LangSmith explaineribm.comAccessed

Join the discussion

Share a useful perspective or ask a question about this article.

Discussion guidelinesComments privacy