What Is an AI Agent Trace?

An AI agent can return a confident answer after taking a deeply unreliable path. Looking only at the answer hides the decisions that made the run safe, fragile, slow, or accidentally successful.

An agent trace is a structured record of that path. It connects the work performed during one execution so you can see what happened, in what order, and under which agent or service.

A trace is a tree of spans

A trace contains spans. Each span represents one unit of work with a start time, end time, status, attributes, and relationships to other spans.

For a support agent, a trace might look like this:

Handle replacement-card request
├── Planner: choose workflow
├── Policy model: check identity requirements
├── Tool: block old card
├── Tool: order replacement card
└── Verifier: confirm both actions succeeded

The top span represents the whole request. Child spans represent the steps taken inside it. More complex systems can also use links to connect work that does not fit into one strict parent-child tree, such as asynchronous jobs or messages passed between agents.

The public spanlink-handoff scenario uses exactly that shape: a verifier remains under the orchestrator but links to the browser evidence it consumed. Making the browser its parent would falsely describe ownership; omitting the link would hide the evidence handoff.

What a span can contain

A useful span normally records:

• its name and role;
• start and end timestamps;
• success, error, or unset status;
• the service, agent, model, or tool responsible;
• typed attributes such as model name or tool arguments;
• timestamped events;
• links to related spans;
• references to larger inputs and outputs.

Some values are too sensitive or too large to display automatically. A trace system should preserve them carefully and reveal them only through explicit, bounded actions.

Why the final answer is not enough

Suppose the support agent tells a customer:

Your old card has been blocked and a replacement is on its way.

The answer sounds correct. The trace reveals that block_card succeeded, order_replacement returned an error, and the verifier never ran.

That changes the diagnosis completely. The problem is not merely a bad sentence. It may be a missing status check, a broken handoff, or a verifier that was skipped after a partial tool failure.

Traces are evidence, not conclusions

A trace records observable facts. It does not automatically explain whether the behavior was acceptable.

For example, three retries might indicate:

• a sensible recovery from a transient failure;
• a wasteful loop;
• a rate-limit policy working as intended;
• missing retry safety around a non-idempotent tool.

The trace provides the evidence. A detector, evaluator, or human reviewer still has to interpret that evidence using the system’s intended behavior.

Trace identity matters

One trace identifier is not enough for serious debugging. You also need to know which project, environment, build, session, agent version, and revision produced it.

That context lets you ask useful questions:

• Did this failure appear only after a new build?
• Does it affect one agent role or the whole workflow?
• Did the same session recover later?
• Is a corrected span an update to the same run or a new run?

Without explicit identity, unrelated executions can be merged and meaningful changes can disappear.

The practical definition

An agent trace is the execution evidence behind an outcome. It tells you how the planner, models, tools, agents, and verifiers interacted during one run.

The next step is learning how a collection of traces becomes agent observability, rather than a folder of individual debugging artifacts.