Agent runs are non-deterministic, so the bug you are asked to fix may never happen again. That makes the trace the primary artefact rather than a debugging aid. If it does not capture enough to reconstruct the run, the incident is unrecoverable no matter how much you know about the system.
What changed with agents is not that systems became harder to debug. It is that the usual method stopped working: you can no longer reproduce a failure by rerunning the input.
Conventional software given the same input takes the same path. An agent given the same input may take a different path, succeed where it previously failed, and offer no explanation for either.
At a glance
- Traces are the primary artefact, not a supplementary log
- The assembled prompt is the field most often omitted and most often needed
- Replay turns “it did something strange” into a reproducible case
- Capture what the agent considered, not only what it did
- Sampling defeats the purpose; agent failures are rare by nature
- Redaction must happen at capture, never after
What must a trace capture?
| Field | Why it matters | Commonly omitted? |
|---|---|---|
| Assembled prompt, in full | The only record of what the model actually saw | Very often |
| Model name and version | Behaviour changes between versions | Often |
| Sampling parameters | Temperature and seed affect reproducibility | Often |
| Raw model output | Before any parsing that might discard nuance | Sometimes |
| Tool declarations offered | Selection cannot be judged without the options | Almost always |
| Tool call arguments | Where most failures actually originate | Rarely |
| Tool response, in full | Truncated responses hide the cause | Sometimes |
| Cumulative budget at each step | Makes exhaustion traceable | Often |
| Termination reason | Completed, capped, errored or abandoned | Often |
The two rows marked “almost always” and “very often” are the same failure in different forms: teams record what the agent did and not what it was working from. Reconstructing the prompt afterwards from its components is unreliable, because the assembly logic has usually changed since.
Why is replay the capability that matters?
Figure 1 — Two ways to investigate an incident
Logs only
You have the outcome, some timings, and a description of what went wrong from whoever noticed.
Rerunning the input produces a different path, which proves nothing. The investigation becomes inference from partial evidence and usually ends in a guess.
Archaeology
Replayable trace
You have the exact prompts, tool declarations, arguments and responses, with the model version pinned.
You can re-execute the run, change one variable, and observe the difference. The failure becomes a test case that stays fixed.
Engineering
Replay converts debugging from a narrative exercise into a controlled one. It is the single capability that most changes how agent incidents are handled, and it is only possible if the trace was complete at capture time.
How do you make runs replayable?
- Pin the model version explicitly in the trace, never relying on a floating alias that resolves differently later.
- Record sampling parameters, including temperature and any seed, so the run can be re-executed under the same conditions.
- Store tool responses so replay can serve them from the trace rather than hitting live systems, which may have changed or may not tolerate the writes.
- Version the assembly logic and record which version built the prompt, so you know whether replay is reproducing history or applying today’s code.
- Make replay a first-class command, not a script someone maintains privately.
Point 3 is what makes replay safe. Replaying a run that issued writes against live systems repeats those writes. Serving recorded tool responses is what turns replay from a risky operation into a routine one.
What should you capture beyond the happy path?
What the agent considered and rejected, which is invisible in most implementations.
When an agent picks the wrong tool, the useful question is what else was available and how they were described. When it abandons a plan, the question is what it had tried. Neither appears in a trace recording only successful actions.
Watch for this
Do not sample agent traces the way you would sample web requests. Agent failures are rare, expensive and precisely what you need captured, so a 1% sample will miss almost every incident worth investigating. Capture every run in full, and manage volume through retention policy rather than sampling rate.
How do you handle sensitive data?
Redact at capture, not afterwards.
Traces are unusually sensitive because they contain the full assembled prompt, which by design includes retrieved documents, user data and system instructions. A trace store is effectively a copy of everything your agent has ever seen.
- Redact at write time, since redacting later means the raw data already existed somewhere
- Store field-level references where possible, keeping a document ID rather than its contents
- Apply the same access controls to traces as to the underlying systems, because the trace inherits their sensitivity
- Set retention deliberately, long enough for investigation and no longer
Redaction does reduce replay fidelity, and that tension is real. The workable compromise most teams reach is full capture with short retention for the majority of runs, and redacted long-term retention for the cases used as test fixtures.
What does good instrumentation look like structurally?
One trace per run, with a nested span per step, and every model and tool call as a child of the step that produced it. That shape lets you view a run as a timeline or as a tree depending on what you are looking for.
Attach identifiers at the top: user, session, agent version, task type. Those are what make aggregate questions answerable later, and adding them retroactively is impossible.
The metrics discussed elsewhere all become queries over this data rather than separate instrumentation. That is the point of capturing properly: new measures can be applied to historical runs, which is exactly when you want them.
Where do teams go wrong?
Building tracing after the first incident
The incident is precisely when the data will be missing. Tracing is cheap to build before deployment and impossible to apply retroactively to a run that already happened.
Logging the user message instead of the prompt
The user message is a small fraction of what the model saw. System instructions, retrieved context, history and tool declarations make up most of it, and those are where the explanation usually lives.
Treating traces as debug output
Debug output gets disabled in production to reduce noise and cost. Traces are the production artefact, and disabling them removes the only mechanism for understanding what the system did.
What do experienced teams do differently?
They promote interesting traces into a permanent regression suite.
When a run reveals a bug, that trace becomes a fixture: replayed on every change, with an assertion about what should now happen. Over time the suite becomes a record of every failure mode the system has exhibited, which no synthetic test set would have anticipated.
They also make traces accessible to non-engineers. Support and operations staff who can open a run and see what happened resolve their own questions and file far better reports, which removes a large amount of engineering interruption.
A short glossary
- Trace
- A complete record of one agent run, sufficient to reconstruct and ideally re-execute what happened.
- Span
- A nested unit within a trace representing one step, containing the calls that step made.
- Replay
- Re-executing a recorded run with the same inputs, pinned model version and recorded tool responses.
- Assembled prompt
- The complete text sent to the model, including instructions, context, history and tool declarations.
- Trace fixture
- A stored trace promoted into a regression suite and replayed on every change.
Key takeaways
- Non-determinism makes the trace the primary artefact, since failures may never reproduce.
- Capture the assembled prompt in full; reconstructing it later is unreliable.
- Record tool declarations offered, not just the tool chosen, or selection cannot be judged.
- Replay requires a pinned model version, recorded sampling parameters and stored tool responses.
- Serving recorded tool responses is what makes replay safe against systems with side effects.
- Never sample agent traces; failures are rare and are exactly what sampling discards.
- Above all, do not build tracing after the first incident, because that is when the data will be missing.
Frequently asked questions
Why can’t I debug agents by rerunning the input?
Because generation is non-deterministic, so the same input can produce a different path, succeed where it previously failed, and give no explanation for either. The recorded trace, not the input, is what preserves the failure.
What is the most commonly missing trace field?
The fully assembled prompt. Teams log the user message, which is a small fraction of what the model actually saw. System instructions, retrieved context, history and tool declarations make up most of it and usually contain the explanation.
Why record tool declarations and not just tool calls?
Because selection cannot be assessed without knowing the options. When an agent picks the wrong tool, the useful question is what else was available and how each was described, and that information disappears if only the chosen call is stored.
What does replay require?
A pinned model version rather than a floating alias, recorded sampling parameters, stored tool responses so replay does not hit live systems, and a record of which prompt-assembly version built the original. Missing any of these makes replay approximate rather than faithful.
Is it safe to replay a run that made changes?
Only if replay serves recorded tool responses instead of calling live systems. Otherwise replaying repeats every write the original performed. Serving from the trace is what turns replay from a risky operation into a routine one.
Should I sample agent traces to control volume?
No. Agent failures are rare and expensive, so a small sample misses nearly every incident worth investigating. Capture every run in full and manage volume through retention policy, keeping most runs briefly and interesting ones indefinitely.
How do I handle sensitive data in traces?
Redact at capture rather than afterwards, since later redaction means the raw data already existed. Store references such as document IDs where contents are not needed, apply the same access controls as the underlying systems, and set retention deliberately.
What should happen to a trace that revealed a bug?
Promote it into a regression suite as a fixture, replayed on every change with an assertion about the corrected behaviour. Over time this produces a test set shaped by real failure modes rather than by what anyone anticipated in advance.
References
- Anthropic. Model Context Protocol documentation, covering the tool invocation structure traces record.
- OpenTelemetry. Traces and spans, the general model underlying nested run instrumentation.
- Liu, N. F., et al. Lost in the Middle: How Language Models Use Long Contexts. arXiv:2307.03172. Why the assembled prompt, not the user message, explains behaviour.
