Agent trace
- Industry term
An agent trace records the steps an AI agent takes on a task. An agent is an AI app that can take actions such as searching or sending messages.
The model, the trained AI inside the app, chooses actions and writes replies. A tool is an action the app lets it take. The trace can record the requests, replies, and timings for those steps. To investigate an error, find where it first appeared: in a request, a tool's reply, or the model's next message.
Where you’ll meet it
A client receives an invitation for the wrong week from your scheduling agent. You check its final message and the calendar; both confirm that an invitation went out. Neither explains how it chose the date.
What to do
- Open the trace for that task and find the date the agent sent to the calendar.
- Work backward until you find where the date first differed from the client's request.
- Show whoever manages the agent where the date changed, then test the fix without sending another invitation.
Easy to mix up
| Agent trace | Audit log |
|---|---|
| How the steps of one task led to its result | Who performed which recorded actions, for accountability |
Check yourself
You ask an agent for orders placed after June 1. Its trace shows a request for orders after July 1, a reply listing July orders, and a report listing those same orders. Where should you start investigating?
Go deeperTimed spans show where delays occur, while recorded content needs deliberate handling
OpenAI's Agents SDK documentation organizes traces into spans, operations with start and end times. A trace covers a task from beginning to end, while its spans identify work within it. These timings help separate time spent generating model output from time spent waiting on tools.
The same documentation warns that spans can capture sensitive data and provides a setting controlling its inclusion. OpenTelemetry, a framework for recording software activity, also marks fields containing prompts and answers as potentially sensitive. Teams need to choose what to capture and who can read it, since traces can contain copies of prompts and tool results.
Sources
- Tracing, OpenAI Agents SDK docs
- Semantic conventions for generative AI systems, OpenTelemetry
- Demystifying evals for AI agents, Anthropic Engineering