Agent Tracing
An agent run is a long sequence of decisions that nobody watched happen. Agent tracing records that sequence as it unfolds — every model call, tool invocation, argument, result and timing — so the run can be reconstructed afterwards and read like a transcript.
What a trace is made of
A trace is a tree of spans, each span one unit of work with a start time, a duration and a parent. An agent trace nests naturally: the run is the root span, each pass of the plan–act–observe loop is a child, and inside a pass sit the model call (with its full prompt and completion) and the tool call (with its arguments and return value). Because the structure is hierarchical rather than a flat log, a retried call or a delegated sub-agent appears as nested spans — which is what lets you see at a glance that one step was attempted four times before it succeeded.
Why printed logs are not enough
Agent failures rarely arrive as a stack trace. The run completes, and the result is subtly wrong:
- A tool argument was filled in plausibly but pointed at the wrong record.
- An instruction given early fell out of the context window, and the plan drifted from there.
- Two passes undid each other's work and the loop never noticed.
Only a replayable record of the real inputs at each step separates those causes. Re-running will not do it, because the same prompt does not reproduce the same path. LangSmith, LangGraph's built-in instrumentation and OpenTelemetry-based tooling all exist for this; nondeterminism is what makes tracing mandatory rather than merely tidy.
Agent tracing records each step of a run — prompts, model responses, tool calls, and their results — as a structured, nested trace tied to a single execution. The trace reconstructs exactly what the agent saw and did, in order. Because agent behaviour is nondeterministic and spans many steps, tracing is the primary debugging instrument: without it, a failure three steps into a loop is unexplainable after the fact.
Think of the flight recorder on an aeroplane. Flights land safely almost every time, but when something odd happens investigators need the full minute-by-minute record — not just the fact that it landed late.
Agent tracing is the flight recorder for software that works towards a goal on its own. It saves every step: what the software was reasoning about, which tool it reached for, what it typed in, and what came back. Because these systems do not behave identically twice, you usually cannot just run the job again to watch the mistake happen. The recording is the only way to find where a sensible plan quietly went off course.