---
title: "OpenAI Agents SDK Tracing"
description: "Automatically trace OpenAI Agents SDK executions, handoffs, and agent interactions."
sidebar:
  label: "OpenAI Agents SDK"
seo:
  title: "OpenAI Agents SDK Tracing with Judgment | Agent Framework Integration Docs"
  description: "Trace OpenAI Agents SDK agent executions with Judgment, including tool calls, handoffs, spans, and behavior for production agent monitoring."
---

**OpenAI Agents SDK integration** captures traces from your OpenAI Agents applications, including agent execution flow, handoffs between agents, and individual agent calls.

{/* @test-flow
  id: integration-openai-agents
  lang: python
  env: JUDGMENT_API_KEY, JUDGMENT_ORG_ID, OPENAI_API_KEY
*/}

## Quickstart

1. ### Install Dependencies

    **uv**

    ```bash
    uv add openai-agents-sdk judgeval openinference-instrumentation-openai-agents python-dotenv
    ```

    **pip**

    ```bash
    pip install openai-agents-sdk judgeval openinference-instrumentation-openai-agents python-dotenv
    ```

2. ### Initialize Integration

    ```python title="setup.py"
    from judgeval import Tracer
    from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

    Tracer.init(project_name="openai_agents_project")
    Tracer.registerOTELInstrumentation(OpenAIAgentsInstrumentor())
    ```

    > **Info**
    >
    > This integration uses [**OpenInference**](https://github.com/Arize-ai/openinference) instrumentation to provide a robust, production-ready solution for porting telemetry data from OpenAI Agents into Judgment's platform. OpenInference handles the complex task of capturing and formatting trace data, ensuring reliable observability for your agent workflows.

3. ### Add to Existing Code

    Add these lines to your existing OpenAI Agents application:

    ```python
    import dotenv
    import os

    dotenv.load_dotenv()

    from judgeval import Tracer  # [!code ++]
    from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor  # [!code ++]

    Tracer.init(project_name="openai_agents_project")  # [!code highlight]
    Tracer.registerOTELInstrumentation(OpenAIAgentsInstrumentor())  # [!code highlight]

    from agents import Agent, Runner
    import asyncio

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

    async def main():
        result = await Runner.run(agent, input="Hello, how are you?")
        print(result.final_output)

    if __name__ == "__main__":
        asyncio.run(main())
    ```

    All agent executions and handoffs are automatically traced.

## Example: Multi-Agent Triage System

```python title="multi_agent_example.py"

dotenv.load_dotenv()

from judgeval import Tracer
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

Tracer.init(project_name="openai_agents_project")
Tracer.registerOTELInstrumentation(OpenAIAgentsInstrumentor())

from agents import Agent, Runner

# Define specialized agents
spanish_agent = Agent(
    name="Spanish Agent",
    instructions="You only speak Spanish. Answer all questions in Spanish.",
)

english_agent = Agent(
    name="English Agent",
    instructions="You only speak English. Answer all questions in English.",
)

french_agent = Agent(
    name="French Agent",
    instructions="You only speak French. Answer all questions in French.",
)

# Define triage agent with handoffs
triage_agent = Agent(
    name="Triage Agent",
    instructions="Determine the language of the user's request and handoff to the appropriate language-specific agent.",
    handoffs=[spanish_agent, english_agent, french_agent],
)

@Tracer.observe(span_type="function")  # [!code highlight]
async def main():
    requests = [
        "Hola, ¿cómo estás?",
        "What is the weather like today?",
        "Bonjour, comment allez-vous?",
    ]

    for request in requests:
        result = await Runner.run(triage_agent, input=request)
        print(f"Request: {request}")
        print(f"Response: {result.final_output}\n")

if __name__ == "__main__":
    asyncio.run(main())
```

    > **Info**
    >
    > **Tracking Non-Agent Operations**: Use `@Tracer.observe()` to track any function or method that's not part of your OpenAI Agents workflow. This is especially useful for monitoring utility functions, API calls, or other operations that happen outside the agent execution but are part of your overall application flow.
    >
    > ```python title="complete_example.py"
    > from agents import Agent, Runner
    > from judgeval import Tracer
    > import asyncio
    >
    > Tracer.init(project_name="openai_agents_project")
    >
    > @Tracer.observe(span_type="function")
    > def preprocess_input(data: str) -> str:
    >     return f"Preprocessed: {data}"
    >
    > async def run_agent(user_input: str):
    >     # Preprocess input (traced with @Tracer.observe)
    >     processed_input = preprocess_input(user_input)
    >
    >     # Agent execution (automatically traced)
    >     agent = Agent(
    >         name="Assistant",
    >         instructions="You are a helpful assistant.",
    >     )
    >
    >     result = await Runner.run(agent, input=processed_input)
    >     return result.final_output
    >
    > # Execute - both helper functions and agents are traced
    > result = asyncio.run(run_agent("Hello World"))
    > print(result)
    > ```

## Next Steps

- [OpenInference Integration](/documentation/integrations/tracing-providers/openinference) - Export OpenInference traces to Judgment for unified observability.
- [Monitor a behavior](/documentation/monitoring) - Monitor your OpenAI Agents in production with behavioral scoring.
- [Instrument your agent](/documentation/tracing/instrumentation) - Configure and verify Judgment tracing beyond this integration.