Trace

What is a trace?

A trace is a structured execution record that links the operations occurring during an agent run. It can connect model calls, tool calls, state changes, retrieval steps, handoffs, errors, and timing under one task or request identifier.

Traces help teams reconstruct what happened across a distributed agent system.

What a trace can contain

A trace is commonly divided into spans, where each span represents one operation. A span may record:

• start and end time;
• parent and child relationships;
• operation name and status;
• model or tool identifier;
• input and output metadata;
• token use, latency, and cost;
• errors and retry information;
• relevant state or correlation IDs.

Sensitive prompts, tool arguments, and results should be redacted or access-controlled.

Trace versus logging

A log is an individual event or message, such as “tool call failed.” A trace connects related operations into an end-to-end structure and shows how they depend on one another.

Logs can be attached to trace spans. Metrics summarize numerical behavior across many runs. Traces explain one execution path in detail.

Trace versus agent trajectory

An agent trajectory is the conceptual sequence of decisions, actions, observations, and states. A trace is the instrumentation that records execution.

A trace may include system operations outside the trajectory, such as database latency or queue processing. Conversely, a poorly instrumented trace may miss an important agent decision.

Common problems

Capturing everything creates high storage cost and privacy risk. Capturing too little makes failures impossible to diagnose. Inconsistent identifiers break the connection between model calls and tool results.

Builders should define a stable event model, propagate correlation IDs, sample thoughtfully, and separate searchable metadata from protected content. Retention rules should match operational and legal needs.

Why it matters

Agents involve several components and repeated calls. A final error message rarely reveals whether the cause was routing, retrieval, model output, tool execution, or state handling.

A well-designed trace provides evidence for debugging, evaluation, cost analysis, and observability. It shows not only that a task failed, but where time and decisions moved through the system.