How to trace the OpenAI Agents SDK with Phoenix

Trace the OpenAI Agents SDK with Phoenix: install the instrumentor and run a multi-agent example to see every agent and tool call in one trace.

To trace the OpenAI Agents SDK, install the OpenInference instrumentor, register a Phoenix tracer provider, and run your agents as usual. Every run then produces a trace with a span for each agent, LLM call, tool call, and handoff. The SDK already records traces by default and sends them to OpenAI’s dashboard. The instrumentor sends the same data to Phoenix, so you can inspect it, evaluate it, and keep it in your own project.

This tutorial sets up tracing, runs a 2-agent example with a tool and a handoff, and walks through the resulting trace. It also covers how to keep or drop the default OpenAI export, group several runs into one trace, name your workflows, and keep sensitive data out of spans.

How OpenAI Agents SDK tracing works

The SDK wraps each Runner.run() call in a trace named “Agent workflow” and records spans inside it for agents, LLM calls, function tools, guardrails, and handoffs. Trace processors receive those traces and spans and export them. The default processor sends them to OpenAI’s backend.

The OpenInference instrumentor adds a trace processor of its own. It converts each SDK span into an OpenTelemetry span that follows the OpenInference conventions, so Phoenix and any other OpenTelemetry backend can read it. You don’t change your agent code.

Prerequisites

  • Python 3.11 or later: arize-phoenix-otel requires it. Version 2.0 and above of the instrumentor also needs openai-agents 0.11.0 or later.
  • An OpenAI API key: The example agents call OpenAI models.
  • A Phoenix instance: Run Phoenix locally: install it with pip install arize-phoenix and start it with phoenix serve, which listens on port 6006. Install the local server in its own virtual environment, not the one your agents run in (see Keep the Phoenix server in its own environment).
Try Arize AX

Build better agents with Arize

Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.

Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.

Step 1: Install the packages

pip install openai-agents openinference-instrumentation-openai-agents arize-phoenix-otel

Step 2: Set your environment variables

Set your OpenAI key and point Phoenix at your local server:

export OPENAI_API_KEY="your-openai-key"
export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

Step 3: Register Phoenix and instrument the SDK

Register the tracer provider before your first agent run. With auto_instrument=True, Phoenix finds the installed instrumentor and turns it on.

from phoenix.otel import register

tracer_provider = register(
    project_name="openai-agents-demo",
    auto_instrument=True,
)

If you prefer to be explicit, leave out auto_instrument and call the instrumentor yourself. This form only turns on the Agents SDK instrumentor, whatever else is installed:

from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer_provider)

Step 4: Build a multi-agent example and run it

This example has a triage agent that hands billing questions to a billing agent, which calls a tool. That gives the trace an agent, a handoff, a tool call, and several LLM calls to look at.

from agents import Agent, Runner, function_tool

@function_tool
def lookup_invoice(invoice_id: str) -> str:
    """Look up an invoice by ID."""
    return f"{invoice_id}: $240.00, paid March 3"

billing_agent = Agent(
    name="Billing agent",
    instructions="Answer billing questions. Use lookup_invoice.",
    tools=[lookup_invoice],
    model="gpt-4o-mini",
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Route billing questions to the billing agent.",
    handoffs=[billing_agent],
    model="gpt-4o-mini",
)

result = Runner.run_sync(triage_agent, "What is the status of invoice INV-1042?")
print(result.final_output)

# Send any buffered spans before a short script exits
tracer_provider.force_flush(timeout_millis=10000)

Open Phoenix and select the openai-agents-demo project. The run appears as a single trace.

What an OpenAI Agents SDK trace shows in Phoenix

In the versions tested (openai-agents 0.24.0 and openinference-instrumentation-openai-agents 2.8.1), the example above produces this structure:

Agent workflow (AGENT)
└── Agent workflow (CHAIN)
    ├── Triage agent (AGENT)
    │   └── turn (CHAIN)
    │       ├── response (LLM)
    │       └── handoff to Billing agent (TOOL)
    └── Billing agent (AGENT)
        ├── turn (CHAIN)
        │   ├── response (LLM)
        │   └── lookup_invoice (TOOL)
        └── turn (CHAIN)
            └── response (LLM)

Span names and nesting can change between SDK and instrumentor versions, so treat this as a guide to what to look for rather than a fixed schema. When an agent picks the wrong tool or a handoff goes to the wrong place, this is the view that shows the exact messages behind each decision. Here’s how to read it:

  • Agent spans show which agent was active. The handoff appears as a tool span on the triage agent’s turn, and the billing agent then runs as its own agent span.
  • Turn spans group one round of model reasoning and the tool calls that came out of it. The billing agent has 2 turns: one that calls the tool and one that writes the answer.
  • Response spans are the LLM calls. They carry the model name, input and output messages, and token counts. The SDK calls OpenAI’s Responses API by default, which is why they’re named response. If you switch the SDK to the Chat Completions API with set_default_openai_api("chat_completions"), they’re named generation instead.
  • Tool spans cover function tools and handoffs. A function tool span carries the arguments and the return value. A handoff span records the agent it came from and the agent it went to.

Name your workflows

The root span takes the trace name. By default that name is “Agent workflow”. Set workflow_name on the run config to give each logical workflow a name you can search for:

from agents import RunConfig

result = Runner.run_sync(
    triage_agent,
    "What is the status of invoice INV-1042?",
    run_config=RunConfig(workflow_name="Billing support"),
)

Group several runs into one trace

Wrap the calls in a trace() context manager. Every run inside it lands under one root span carrying the name you give it:

from agents import trace

with trace("Support session"):
    first = Runner.run_sync(triage_agent, "What is the status of invoice INV-1042?")
    second = Runner.run_sync(triage_agent, "Can you resend it?")

Each run appears as its own “Agent workflow” branch under the “Support session” root.

To link traces from the same conversation, pass a group_id. Since instrumentor 2.8.1, it becomes the root span’s session.id, so Phoenix groups those traces into one session:

with trace("Support session", group_id="conversation-123"):
    result = Runner.run_sync(triage_agent, "What is the status of invoice INV-1042?")

trace() also accepts metadata, but the instrumentor doesn’t map it to a span attribute, so don’t rely on it for filters in Phoenix.

Add custom spans

The SDK provides custom_span for work that isn’t an agent, a model call, or a tool, such as a retrieval step or post-processing. Spans you create inside a trace are handed to the same processors as the built-in ones:

from agents import custom_span, trace

with trace("Support session"):
    with custom_span("load_customer_profile"):
        profile = {"tier": "pro"}
    result = Runner.run_sync(triage_agent, "What is the status of invoice INV-1042?")

The SDK also exposes function_span, guardrail_span, handoff_span, generation_span, and agent_span if you need to record those by hand. In the versions tested, custom_span appeared in Phoenix as a CHAIN span under the trace’s root span. How the other span types map to a span kind depends on the instrumentor version, so check the output after you add one.

Keep the default OpenAI traces

By default the instrumentor replaces the SDK’s trace processors, so traces go to Phoenix and stop going to OpenAI’s dashboard. This is the exclusive_processor setting, and it defaults to True. To send traces to both, set it to False:

from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

OpenAIAgentsInstrumentor().instrument(
    tracer_provider=tracer_provider,
    exclusive_processor=False,
)

In testing, the exclusive setting left only the OpenInference processor registered. With exclusive_processor=False, the SDK’s default processor stayed in place next to it.

How do you disable tracing?

To turn off all SDK tracing, set an environment variable or call a function:

export OPENAI_AGENTS_DISABLE_TRACING=1

from agents import set_tracing_disabled

set_tracing_disabled(True)

To skip tracing for a single run, set tracing_disabled on its run config:

result = Runner.run_sync(
    triage_agent,
    "Hello",
    run_config=RunConfig(tracing_disabled=True),
)

These settings only stop the SDK’s own spans. If another instrumentor is active, such as the OpenAI client instrumentor, it still traces each model call (see Keep the Phoenix server in its own environment).

How do you keep sensitive data out of traces?

Spans include LLM inputs and outputs and tool arguments and results by default. trace_include_sensitive_data controls that, and it defaults to True. Set it to False on the run config to leave that content out:

result = Runner.run_sync(
    triage_agent,
    "What is the status of invoice INV-1042?",
    run_config=RunConfig(trace_include_sensitive_data=False),
)

In testing, a run with this setting still produced its spans, but the LLM and function tool spans had no input or output values. Handoff spans still showed the 2 agent names. The LLM spans also lost their model name and token counts, so cost tracking in Phoenix stops working for those runs. You can also set the default for every run with the OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA environment variable.

Like the disable settings, this only covers the SDK’s own spans.

Keep the Phoenix server in its own environment

pip install arize-phoenix also installs openinference-instrumentation-openai, the instrumentor for the OpenAI client library. If it’s in the same environment as your agents, register(auto_instrument=True) turns it on too. In testing, that had 3 effects:

  • Every LLM call got a duplicate span, a Response (LLM) span nested under the SDK’s response (LLM) span.
  • The duplicate spans ignored trace_include_sensitive_data=False and still carried the full prompts and outputs.
  • They ignored set_tracing_disabled(True) too. With SDK tracing off, each LLM call still sent a Response span with full content to Phoenix.

To avoid this, run the Phoenix server in its own virtual environment, or use Phoenix Cloud. If both have to share an environment, skip auto_instrument=True and call OpenAIAgentsInstrumentor().instrument() yourself, as in Step 3.

Send OpenAI Agents SDK traces to Arize AX

The same instrumentor works with Arize AX. Swap the Phoenix registration for the AX one and keep the rest of your code:

pip install arize-otel

from arize.otel import register

tracer_provider = register(
    space_id="your-space-id",
    api_key="your-api-key",
    project_name="openai-agents-demo",
    auto_instrument=True,
)

Once traces arrive in AX, you can set up monitors and alerts, run online evals on live traffic, and track cost per project.

Getting started

Phoenix is open source. Run it locally, run the example above, and open the trace. Once you can see how your agents behave, the next step is to write evals for the failures you find. The Phoenix OpenAI Agents SDK guide has the short version of this setup.

FAQs: OpenAI Agents SDK tracing

Does the OpenAI Agents SDK have tracing built in?

Yes. Tracing is on by default and exports to OpenAI’s dashboard. Trace processors let you send the same data to other backends, and the OpenInference instrumentor is one of them.

What is a trace processor in the OpenAI Agents SDK?

A trace processor receives the traces and spans the SDK creates and exports them somewhere. add_trace_processor adds one next to the default. set_trace_processors replaces the defaults. The instrumentor uses the replace behavior unless you set exclusive_processor=False.

Why are my traces not showing up in Phoenix?

Check that register() runs before your first agent run, that PHOENIX_COLLECTOR_ENDPOINT points at the right place, and that PHOENIX_API_KEY is set for Phoenix Cloud. In a short script, call tracer_provider.force_flush() before the process exits. Also confirm tracing isn’t disabled by OPENAI_AGENTS_DISABLE_TRACING or tracing_disabled.

Can I trace the OpenAI Agents SDK without sending data to OpenAI?

Yes. The default instrumentor setting replaces the SDK’s default processors, so traces go only to your Phoenix project. To turn SDK tracing off entirely, use set_tracing_disabled(True). That doesn’t stop other instrumentors, such as the OpenAI client instrumentor that comes with arize-phoenix, from tracing model calls.

Get the latest on AI & Observability

Sign up for our newsletter, The Evaluator—and stay in the know with updates and new resources:

Don’t ship vibes.

Arize gives AI teams observability and evals to understand and improve agent performance.