Technology
OpenAI Agents SDK
Trace agents built with the OpenAI Agents SDK, including their model calls, tool calls, handoffs, and token usage.
Overview
OpenAI Agents SDK
The OpenAI Agents SDK is a Python framework for building agents that call tools, hand off work to other agents, and enforce guardrails. An agent run can involve many model calls and tool calls, so monitoring it shows where time and tokens go, which tools fail, and how a request moved between agents.
The SDK has its own tracing API. The OpenTelemetry instrumentation for the SDK, part of OpenLLMetry, converts its traces into OpenTelemetry spans with the GenAI semantic conventions and sends them to Dash0 next to the rest of your application's telemetry.
Use Cases
- Follow agent runs end to end with a span for each agent, model call, tool call, and handoff
- Track token usage and cost per model and per agent
- Find failing or slow tools by looking at the tool spans and their arguments and results
- Debug conversations with the prompts and responses recorded on the model spans
- Evaluate agent output with Dash0 evals, which judge the recorded messages
Setup
Overview
The opentelemetry-instrumentation-openai-agents package, part of OpenLLMetry, implements the OpenAI Agents SDK's TracingProcessor interface.
When you call OpenAIAgentsInstrumentor().instrument(), it registers the processor with the SDK's add_trace_processor().
The processor turns each agent run into OpenTelemetry spans that follow the GenAI semantic conventions, and the OpenTelemetry SDK exports them to Dash0 over OTLP.
This guide shows two ways to set it up: zero-code with opentelemetry-instrument, or in code.
If you already use the Traceloop SDK, Traceloop.init() turns on this instrumentation for you; see OpenLLMetry.
Prerequisites
- Python 3.10 or higher
openai-agents0.2.0 or higher, the minimum the instrumentation declares. This guide describesopenai-agents0.24.0 withopentelemetry-instrumentation-openai-agents0.63.0.- A Dash0 auth token with ingest permission, and your organization's OTLP via HTTP endpoint
To route telemetry through an OpenTelemetry Collector instead of sending it to Dash0 directly, see:
Approach 1: Zero-Code Instrumentation
Install Dependencies
pip install openai-agents \
opentelemetry-distro \
opentelemetry-exporter-otlp-proto-http \
opentelemetry-instrumentation-openai-agentsConfigure Environment Variables
export OTEL_SERVICE_NAME="my-agents-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="{{endpoint_otlp_http}}"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {{token}},Dash0-Dataset={{dataset}}"These settings apply to traces, metrics, and logs. The OpenAI Agents instrumentation only produces traces, but metrics and logs from other instrumentations or from your own code reach Dash0 through the same exporter settings.
Run Your Application
opentelemetry-instrument python your_app.pyThe opentelemetry-instrument wrapper finds the OpenAI Agents instrumentation through its entry point and turns it on before your code runs.
Approach 2: Instrument in Code
Install Dependencies
pip install openai-agents \
opentelemetry-sdk \
opentelemetry-exporter-otlp-proto-http \
opentelemetry-instrumentation-openai-agentsMinimal Example
Set up OpenTelemetry and the instrumentation once at startup, before you create or run any agents:
from agents import Agent, Runner, function_tool
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider(resource=Resource.create({"service.name": "my-agents-app"}))
provider.add_span_processor(
BatchSpanProcessor(
OTLPSpanExporter(
endpoint="{{endpoint_otlp_http}}/v1/traces",
headers={
"Authorization": "Bearer {{token}}",
"Dash0-Dataset": "{{dataset}}",
},
)
)
)
trace.set_tracer_provider(provider)
OpenAIAgentsInstrumentor().instrument()
@function_tool
def get_weather(city: str) -> str:
return f"The weather in {city} is sunny."
agent = Agent(
name="Weather agent",
instructions="Answer questions about the weather.",
tools=[get_weather],
)
result = Runner.run_sync(agent, "What is the weather in Berlin?")
print(result.final_output)The export destination is the OTLP exporter you configure: {{endpoint_otlp_http}}/v1/traces with your auth token.
The Dash0-Dataset header is optional; without it, Dash0 writes to the token's default dataset.
Flush and Shutdown
The SDK hands each finished span to the processor, which ends the matching OpenTelemetry span.
The BatchSpanProcessor then exports spans in batches in the background, so the last spans of a run can still be in memory when the run returns.
- Normal process exit: the OpenTelemetry
TracerProvidershuts down on interpreter exit and exports what is left. Scripts and the zero-code setup need no extra step. - Serverless functions, task workers, and processes that exit with
os._exit(): callforce_flush()after the run finishes, before the runtime freezes or kills the process:
from opentelemetry import trace
result = await Runner.run(agent, "What is the weather in Berlin?")
trace.get_tracer_provider().force_flush()- Explicit shutdown:
provider.shutdown()exports the remaining spans and stops the exporter. Call it once, when your application stops.
The processor's own force_flush() does nothing, and its shutdown() ends any spans that are still open. Flushing always happens in the OpenTelemetry TracerProvider.
Export Failures
Export problems never fail an agent run:
- The OTLP exporter retries connection errors and HTTP 429, 502, 503, and 504 with backoff, and honors
Retry-After. If the export still fails, it drops the batch and logs an error. - Other errors, such as HTTP 401 for a wrong or expired auth token, are not retried. The exporter drops the batch and logs an error right away.
- The SDK catches and logs exceptions raised by trace processors, and the instrumentation's hooks swallow their own errors.
To find failed exports, look for Failed to export errors from the OpenTelemetry exporter in your application logs.
What Gets Captured
The instrumentation creates these spans for each agent run:
| Span name | Created for | Main attributes |
|---|---|---|
Agent Workflow | Each SDK trace, as the root span | gen_ai.provider.name |
<agent name>.agent | Each agent that takes part | gen_ai.agent.name, the agent's handoffs |
openai.response | Each model call | gen_ai.request.model, request parameters, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, finish reasons, messages |
<tool name>.tool | Each function tool call | gen_ai.tool.name, gen_ai.tool.type, call arguments and result |
<from agent> → <to agent>.handoff | Each handoff between agents | gen_ai.handoff.from_agent, gen_ai.handoff.to_agent |
openai.realtime.* | Speech and transcription in voice pipelines | gen_ai.operation.name |
Spans nest the same way as in the SDK: model calls, tool calls, and handoffs are children of the agent that made them, and agents are children of Agent Workflow.
The root span is named Agent Workflow whatever workflow_name you set in RunConfig.
Guardrail spans and custom spans created with custom_span() are not converted.
The instrumentation records no metrics. Dash0 derives token usage and cost metrics from the span attributes.
Prompts and Responses
Two switches control whether message content reaches Dash0, and both are on by default:
| Setting | Default | Effect when turned off |
|---|---|---|
SDK: RunConfig(trace_include_sensitive_data=...) or OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA | true | The SDK leaves model inputs and outputs and tool arguments and results out of its trace data, so no processor receives them. |
Instrumentation: TRACELOOP_TRACE_CONTENT | true | The instrumentation does not write messages, tool arguments, or tool results to the spans. |
With both on, model spans carry gen_ai.input.messages and gen_ai.output.messages, and tool spans carry gen_ai.tool.call.arguments and gen_ai.tool.call.result.
Span names, models, token usage, and timing are recorded either way.
Dash0 evals judge the recorded messages, so keep content on if you want to evaluate agent output. To evaluate content without storing it, keep recording on and turn on GenAI attribute redaction for the dataset in Dash0 instead.
To keep content out of the spans:
export TRACELOOP_TRACE_CONTENT=falseOpenAI Traces Dashboard
By default, the instrumentation is added next to the SDK's built-in processor, which sends traces to the OpenAI Traces dashboard. Each run then goes to both OpenAI and Dash0.
To send traces only to Dash0, replace the SDK's processors when you instrument:
OpenAIAgentsInstrumentor(replace_existing_processors=True).instrument()This calls the SDK's set_trace_processors() with the Dash0 processor only.
With zero-code instrumentation, the instrumentor is created with the default, so traces still go to OpenAI as well. Instrument in code to replace the default processor.
Turning SDK tracing off with RunConfig(tracing_disabled=True), set_tracing_disabled(True), or OPENAI_AGENTS_DISABLE_TRACING=1 also stops the export to Dash0, because the instrumentation receives its data from SDK tracing.
Verification
After running your instrumented application:
- Navigate to Traces in Dash0
- Filter by your service name (e.g.,
my-agents-app) - Open a trace that starts with an
Agent Workflowspan - Check that the agent, model, and tool spans are nested under it
- Select an
openai.responsespan and open the Gen AI tab to see the model, token usage, and messages
Support
- For problems with sending data to Dash0 or with this guide, contact Dash0 support from the Dash0 app.
- For problems with the instrumentation itself, open an issue in the OpenLLMetry repository, which maintains and releases the package.