Root container for the entire workflow
AI Models & Assistants / Knowledge library
Agent Tracing
Records runs as linked spans for model calls, tools, handoffs, guardrails, and custom events
Why learn Agent Tracing?
It makes multi-step behavior debuggable, measurable, and auditable across development and production.
The problem it solves
It reveals where an agent spent time, failed, changed control, or used a tool incorrectly.
Where it came from
Agent traces capture the ordered structure and timing of a workflow rather than only its final answer. Trace design must also control sensitive inputs, outputs, credentials, and retention.
Build your understanding
Work through these exercises in order. Try the task before opening a reference.
- Define Agent Tracing and identify its place in an agent architecture.
- Choose a task where Agent Tracing improves an agent system.
- Diagnose one failure caused by misusing Agent Tracing.
- Interpret a trace or state transition involving Agent Tracing.
- Explain one operational tradeoff of Agent Tracing.
Documentation and sources
- OpenAI Agents SDK: Tracing (openai.github.io)
Connect the ideas
Explore next
Real World Example
Supply Chain Logistics Agent Observability
Logistics companies managing automated warehouse inventory and shipping coordination.
The business problem
Complex, multi-step agent workflows involving tool calls to inventory databases and external shipping APIs often fail silently, making it impossible to determine if a breakdown occurred during a database query, a guardrail check, or a model generation.
How this topic solves it
Implementing Agent Tracing allows developers to capture a hierarchical record of every event—including tool calls, guardrails, and model turns—linked together in a single trace, providing a clear audit trail for debugging asynchronous failures.
- Initialize the agent workflow within a trace context manager to group multiple runner calls into a single logical unit.
- Configure RunConfig to include or exclude specific span types like task or turn spans to balance detail with performance.
- Use custom_span() to wrap proprietary business logic or external API interactions that fall outside standard SDK instrumentation.
- Call flush_traces() after critical background tasks or long-running worker processes to ensure all buffered spans are exported to the dashboard.
- Set trace_include_sensitive_data to False in production environments to redact PII from stored span data.
Shows how a parent Trace contains nested Spans representing different stages of an agent execution.
Represents the overall agent execution
Captures inventory database query
Validates shipping constraints
- Trace → contains → Agent Span
- Agent Span → invokes → Tool Span
- Agent Span → triggers → Guardrail Span
Implementation example
This code demonstrates wrapping a multi-step agent process in a trace and ensuring immediate export using flush_traces, which is critical for background logistics tasks.
from agents import Runner, trace, flush_traces
# Wrap the entire logistics workflow in a single trace
with trace("Logistics_Workflow"):
try:
# Execute agent run; spans are automatically linked
result = Runner.run_sync(agent, "Ship order #123")
finally:
# Ensure traces are sent immediately after the task completes
flush_traces()Expected business outcome
Developers gain the ability to visualize the entire lifecycle of a logistics request, enabling rapid identification of which specific tool or guardrail caused a workflow interruption.
Limitations and checks
The default batch processing of traces may introduce a delay in visibility for long-running background workers; developers must manually invoke flush_traces() to force immediate export if real-time monitoring is required.