OpenAI Agents SDK Integration

SDK

Traccia automatically instruments the OpenAI Agents SDK for full observability of agent runs.

Traccia automatically detects and instruments the OpenAI Agents SDK when it's installed. No extra code or configuration is required—just call init() and your agent runs, tool calls, handoffs, and LLM generations are traced automatically.

Zero configuration

Unlike LangChain, the OpenAI Agents SDK integration requires no callback handlers or manual wiring. Traccia registers itself as a tracing processor during init().

1Install Traccia and OpenAI Agents SDK

Install both packages:

bash
pip install traccia openai-agents

2Initialize Traccia

Initialize Traccia at the start of your application. Agents SDK tracing is auto-enabled when openai-agents (Python) or @openai/agents (TypeScript) is installed:

main.py
python
from traccia import init


# That's it! Agents SDK tracing is auto-enabled
init()

3Use Your Agent

Create and run your agent as usual. Traccia captures everything automatically:

agent.py
python
from traccia import init
from agents import Agent, Runner


init()  # Automatically enables Agents SDK tracing


agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)


# Run your agent—all spans are traced automatically
result = Runner.run_sync(agent, "Write a haiku about recursion")
print(result)

Traccia implements the Agents SDK's TracingProcessor interface and registers itself via add_trace_processor() during init().

Configuration

The integration is enabled by default when openai-agents is installed. To disable it:

Option 1: Explicit parameter

python
init(openai_agents=False)

Option 2: Environment variable

bash
export TRACCIA_OPENAI_AGENTS=false
python main.py

Option 3: Config file (traccia.toml)

traccia.toml
toml
[instrumentation]
openai_agents = false

Trace Hierarchy

The integration produces a unified trace showing the relationship between your app code, the Agents SDK framework, and underlying LLM calls:

your_app_span
  └─ agent.YourAgent (from Agents SDK)
      └─ agent.response (from Agents SDK)
          └─ llm.openai.responses (from Traccia OpenAI instrumentation)
              • Prompt, completion, tokens, cost

Span types captured by the integration:

agent.{name}

High-level agent execution with metadata

agent.response

Response operations with IDs

agent.tool.{name}

Function tool calls with input/output

agent.handoff

Agent-to-agent transfers

agent.guardrail.{name}

Safety checks

llm.openai.responses

LLM calls with prompt, completion, tokens, cost

Compatibility

Installed but unused

If you have openai-agents installed but never use it (e.g., you use LangChain or pure OpenAI for your actual logic), the Traccia processor is registered but never invoked. No overhead.

Mixed frameworks

If your app uses both LangChain and Agents SDK for different flows, each integration handles its own code path independently. No conflicts.

Non-Agents apps

If openai-agents is not installed, Traccia works normally without any agent-specific features.

Complete Example

movie_agent.py
python
from traccia import init, span, stop_tracing
from agents import Agent, Runner


init()


# Define your agent with tools
agent = Agent(
    name="MovieRecommenderAgent",
    instructions="You recommend movies based on user preferences.",
    model="gpt-4o-mini"
)


# Run with full tracing
with span("recommendation_session") as session_span:
    session_span.set_attribute("user.preference.genre", "sci-fi")
    
    result = Runner.run_sync(
        agent,
        "Recommend 5 sci-fi movies for someone who liked Blade Runner"
    )
    
    session_span.set_attribute("recommendations.count", len(result))


# Flush traces before exit
stop_tracing(flush_timeout=1.0)

Next Steps

Configuration

Learn about traccia.toml and openai_agents option

Auto-Instrumentation

See all automatically traced libraries

LangChain Integration

Integrate Traccia with LangChain

© 2026 Traccia.