What Should Go in an Agent Trace

A trace is only useful if it can answer the question people ask when trust breaks.

What did the agent see? Why did it act? What evidence came back? What changed after the evidence arrived? Which checks ran? Which boundary stopped the run, or should have stopped it?

For ordinary software, a trace often follows a request across services. That still matters for agents. But an agent trace has to preserve something more slippery: the decision path of a system that is choosing work while it performs the work.

If the trace only records tool names and timestamps, it may look complete while hiding the failure. The agent called a search tool, but searched the wrong directory. It ran a build, but ignored the warning that mattered. It read a file, but carried an old assumption into the next step. It produced a confident answer, but the evidence never supported the claim.

A good trace makes those gaps visible.

Start With the Request and the Contract

Every trace should begin with the user request and the operating contract around it.

The request is not just the text the user typed. It includes the constraints that shape what the agent is allowed to do: do not publish externally, do not overwrite unrelated work, verify before claiming success, use the current repository state instead of memory, ask for approval before irreversible actions.

Those constraints are part of the task. If they are missing from the trace, it becomes hard to tell whether the agent obeyed them or simply got lucky.

This is especially important when the final answer sounds successful. “Prepared the post” means one thing if the contract required a local draft, metadata, hero brief, build, route verification, and git status review. It means something much weaker if the trace only shows a Markdown file edit.

The trace should make the definition of done visible before the run begins.

Preserve the Context the Agent Actually Saw

Agents fail when they act on context they did not have, context they misread, or context that went stale.

That means the trace needs to show the relevant inputs available to the agent at decision time. Which files were read? Which docs were sampled? Which memories, messages, tickets, or records were visible? Which branch was checked? Which environment or package version was observed? Which prior outputs shaped the plan?

This does not mean storing every token forever. It means preserving the evidence needed to explain the next action.

If the agent edits a blog post, the trace should show that it inspected the frontmatter convention and recent posts. If it summarizes a repository, the trace should show the files it opened. If it claims a service is healthy, the trace should show the live check. If it says there were no matches, the trace should show where and how it searched.

Without that context, reviewers are forced to debug the agent's imagination instead of the system it actually saw.

Record Tool Calls as Evidence

Tool calls are not just events. They are evidence.

A useful trace records the tool name, arguments, result, exit code where relevant, and the agent's interpretation of the result. The interpretation matters because many failures live between the raw output and the conclusion the agent carries forward.

A command can succeed while emitting a warning. A search can return nothing because the pattern was wrong. A deployment probe can return 200 while serving a stale app shell. A file can exist while the route that depends on it is still missing from the generated output.

If the trace only says “build ran,” the reviewer has to trust the summary. If it shows the command, exit code, and relevant output, the claim becomes reviewable.

For production agents, the evidence should stay close to the claim it supports. When the agent says the route exists, the route check should be visible. When it says the final answer is source-grounded, the cited source should be in the trace. When it says a recovery worked, the post-recovery evidence should be there too.

Capture Decisions, Not Hidden Monologues

An agent trace does not need to expose private chain-of-thought to be useful.

It does need to capture decisions.

What did the agent decide to do next? What evidence caused that decision? What assumption changed? What risk or boundary did it notice? What alternative did it reject because the trace showed a different path?

Those are operational facts, not a transcript of internal reasoning. They let a reviewer understand whether the agent updated its plan when the world changed.

This is where many quiet failures become visible. The trace shows a tool error, but no decision to recover. It shows a dirty git tree, but no decision to avoid unrelated files. It shows a missing asset, but the final answer still says the post is ready. It shows a user constraint, but the next action crosses the boundary anyway.

A good trace makes the decision state inspectable enough to catch drift.

Include Validation and Acceptance Checks

The trace should show how the agent proved the work was done.

For code, that may be tests, type checks, builds, route probes, or generated artifacts. For content, it may be frontmatter shape, slug convention, image reference, rendered page, OpenGraph metadata, and git status. For research, it may be primary-source coverage and unsupported-claim checks. For support, it may be ticket state and customer-visible reply boundaries.

The exact checks depend on the task. The pattern is the same: completion claims need completion evidence.

This is why acceptance criteria belong in the trace. If the task required five artifacts, the trace should show all five or name the missing one. If the build could not run, the final response should say that directly. If the agent only prepared a local draft, it should not imply the work is published.

Verification is not a ceremonial last step. It is the difference between “the agent acted” and “the task is ready to trust.”

Track Boundaries and Approvals

Some of the most important trace events are not tool calls.

They are boundaries.

Did the agent stop before publishing? Did it avoid a destructive operation? Did it recognize legal, financial, privacy, or security risk? Did it preserve unrelated user work? Did it escalate when the consequence required human accountability?

A boundary that only lives in a prompt is easy to miss during review. A boundary that appears in the trace can be enforced, audited, and turned into an eval.

For agent reliability, approval events should be first-class trace entries. The system should know what action needed approval, whether approval was present, and what happened next. If the agent proceeds without approval, the failure should be loud.

End With the Final State

The trace should end by tying the final answer back to the final state of the world.

What changed? What did not change? Which files are dirty? Which artifacts were generated? Which checks passed? Which checks were skipped or blocked? What approval is still required before the work can leave the local environment?

This final state is where the trace becomes operational memory. A future run can pick up from it. A reviewer can reproduce it. An eval can compare the claim to the evidence. A human can decide whether the next side effect is safe.

Without final state, each agent run becomes a polished story about work that may or may not be complete.

Build Traces for the Failures You Expect

There is no universal trace schema that solves every agent system.

The practical approach is to start with the failures you already see: unsupported claims, partial completion, skipped verification, stale assumptions, swallowed tool errors, missed approval gates. Then make sure the trace preserves the fields needed to catch those failures.

Request. Contract. Context. Tool evidence. Decisions. Validation. Boundaries. Final state.

That is the core shape.

Not because it is exhaustive. Because it gives teams the minimum evidence they need to turn a bad run into a debuggable case, and a debuggable case into a regression test.

A trace should not merely prove that the agent was busy.

It should make the behavior reviewable enough that the next failure has somewhere to go.