An agent trace is a structured record of the events that occur during an AI agent run. Agent observability is the broader practice of collecting, inspecting, and analyzing those traces together with metrics and logs to understand system behavior.
A trace normally represents one end-to-end task and contains nested spans for operations such as model generations, tool calls, retrieval, agent handoffs, guardrails, and human approvals. Each span may record timing, status, model usage, inputs, outputs, and error details.
Tracing is essential because the final response alone rarely explains why an agentic workflow failed. A trace can reveal that the agent selected the wrong tool, retrieved irrelevant context, repeated an action, lost a constraint after context compaction, or exhausted its budget before reaching the correct result.
Useful observability metrics include task success rate, latency, token consumption, tool error rate, retry count, handoff frequency, guardrail activation, and human-intervention rate. These signals support both production monitoring and agent evaluation.
Trace collection creates its own security and privacy risks. Prompts, retrieved documents, tool arguments, and outputs may contain credentials, personal data, or proprietary information. Systems should support redaction, configurable payload capture, retention limits, access controls, and regional data requirements.
Tracing should also preserve stable identifiers that connect a run to its application version, prompt version, model, dataset case, and external side effects. Without this metadata, regressions are difficult to reproduce.
The OpenAI Agents SDK tracing documentation defines traces and spans and shows how model calls, tools, handoffs, and guardrails can be recorded in one execution hierarchy.
The LLM Knowledge Base is a collection of bite-sized explanations for commonly used terms and abbreviations related to Large Language Models and Generative AI.
It's an educational resource that helps you stay up-to-date with the latest developments in AI research and its applications.