An **agent trace** is a recording of everything that happened during one agent run, captured step by step so you can replay it later. Because an agent loops, calling the model and tools many times, a single failure can hide deep inside a long run. The trace is how you find it.
For each step, a good trace captures four things. First, the input context the model saw at the start of that step. Second, the model's response, including its reasoning and the tool call it chose. Third, the tool inputs plus whatever the tool returned, including any error. Fourth, the latency and token cost of that step.
With those four things per step, you can answer the real debugging question. Which step went wrong, and why? Maybe the model called the right tool with the wrong arguments. Maybe the tool returned an error the model ignored. The trace shows you exactly where.
Some things are not worth tracing. The user's operating system or browser version is irrelevant to agent logic. The sampling seed is usually not even returned by the API. The rule of thumb is to capture what you would need to replay and explain the run, and nothing more.
An **agent trace** must capture enough per step to replay and explain the entire run. A run is a loop of model calls and tool calls, so the trace is structured as one span per step, mirroring a distributed trace.
Each step span needs four things. First, the input context snapshot the model received. Second, the model's full response, meaning its reasoning trace plus the structured tool call it emitted. Third, the tool inputs and the tool output or error. Fourth, the step latency and token cost.
Those four cover the debugging question that matters. When step seven of a twenty-step run fails, you need to see what the model saw, what it decided, what the tool actually did, and what that step cost. Aggregate run-level metadata, like total tokens and final status, sits above the spans.
Some fields are noise. The user's operating system and browser version do not affect agent logic. The sampling seed is rarely exposed by the model API and is not a standard span field. The discipline is to capture a replayable, cost-attributable record of each step, and skip data that never helps root-cause a failure.
Quick reference
TL;DR
A useful agent trace records per step: input context, the model output with its tool call, the tool inputs and result or error, plus latency and token cost.
Imagine you hire an assistant to plan a trip, and they make twenty phone calls to book flights and hotels. Later the trip falls apart. To find out what went wrong, you need a recording of each call: who they called, exactly what they asked, what answer they got, and how long each call took. If all you have is the final ruined itinerary, you cannot tell which call caused the mess. An agent trace is that recording. For every step the agent takes, it saves what the agent saw, what it decided to do, which tool it called and with what inputs, what the tool returned, and the time and money that step burned. With that recording you can replay the whole run and find the exact step where things broke.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
A throwaway prototype run locally for a few minutes during a quick experiment. Full span capture adds setup overhead that a short manual run does not need.
A single deterministic prompt with no tool calls and no loop iterations. There is no multi step trajectory to replay, so a per step trace adds no debugging value.
Hard real time paths where the persistence write would blow the latency budget. Synchronous span writes add latency, so you must batch or sample instead of tracing inline.
Storing raw sensitive payloads under strict data residency or retention rules. Full input and output capture can violate privacy policy unless redacted or access controlled first.
Quick scan · 2–4 min
Everything important, quickly.
List the six canonical per-step fields, frame the run as a distributed trace with one span per loop iteration, explain why tool errors and per step cost matter, dismiss the seed and browser distractors, and close by naming a 2026 tool such as LangSmith, Langfuse, Arize Phoenix, or OpenTelemetry GenAI.
Side-by-side
Field
Capture?
Why
Input context snapshot
Yes
Shows what the model saw that turn
Model response plus tool call
Yes
Shows what the model decided
Tool inputs and output or error
Yes
Shows what the tool actually did
Step latency and token cost
Yes
Enables performance and cost attribution
Operating system and browser
No
Irrelevant to agent reasoning
Sampling seed
No
Rarely exposed by the API, not a standard field
Real-world examples
Real products, models, and research that use this idea.
1LangSmith renders each agent run as a nested tree of spans, one per LLM call and tool call, with token cost and latency on every node, so you can click into the exact failing step.
2Langfuse models a run as a trace containing observations for each generation and tool call, capturing inputs, outputs, model, and cost for replay and evaluation.
3Arize Phoenix ingests OpenTelemetry GenAI spans and lets you inspect the prompt, tool call arguments, and tool result at each step of an agent trajectory.
4OpenTelemetry's GenAI semantic conventions standardise span attributes for model name, token usage, and tool calls, so traces from Claude Opus 4.7 or GPT-5.5 agents are portable across backends.
Interviewer follow-ups
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you keep traces useful when a single tool returns a 50 kilobyte response on every one of forty steps?
Sign in or go Pro to see the approach for this follow-up.
QYour agent occasionally leaks customer PII into tool inputs. How do you trace without storing the PII?
Sign in or go Pro to see the approach for this follow-up.
QHow does the trace schema change when you move from a single agent to a multi-agent team?
Sign in or go Pro to see the approach for this follow-up.
Don't say this
Red flags and common mistakes that signal junior thinking. Click to expand.
Most common mistake
Logging only the final answer. When a 20-step run fails, the final output tells you nothing about which step broke. You need a per-step span with inputs, outputs, and tool results.