> ## Documentation Index
> Fetch the complete documentation index at: https://next.gentrace.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents

> Trace OpenAI Agents with automatic instrumentation

<Info>
  For a complete example, see the [OpenAI Agents
  example](https://github.com/Gentrace/gentrace-python/blob/main/examples/openai_agents_instrumentation.py)
  on GitHub.
</Info>

Gentrace integrates with OpenAI Agents SDK using OpenInference instrumentation to automatically trace agent conversations, tool calls, and agent handoffs.

## Prerequisites

* Python 3.8+
* OpenAI API key
* [Gentrace API key](https://gentrace.ai/s/api-keys)
* OpenAI Agents SDK

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install gentrace openai openinference-instrumentation-openai-agents
  ```

  ```bash uv theme={null}
  uv pip install gentrace openai openinference-instrumentation-openai-agents
  ```
</CodeGroup>

## Configuration

Initialize Gentrace with OpenAI Agents instrumentation:

```python openai_agents_instrumentation.py theme={null}
import os
from openai import OpenAI
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from gentrace import init, interaction

# Initialize Gentrace with OpenAI Agents instrumentation
init(
    api_key=os.getenv("GENTRACE_API_KEY"),
    base_url=os.getenv("GENTRACE_BASE_URL", "https://gentrace.ai/api"),
    otel_setup={
        "service_name": "openai-agents-demo",
        "instrumentations": [OpenAIAgentsInstrumentor()],
    },
)

# Define tools for your agent
def check_weather(city: str) -> str:
    """Get current weather for a city (simulated)."""
    weather_data = {
        "san francisco": "☁️ 62°F, cloudy",
        "new york": "☀️ 75°F, sunny",
        "london": "🌧️ 55°F, rainy",
    }
    return weather_data.get(city.lower(), f"No weather data for {city}")

# Define agent configuration
travel_agent = {
    "name": "Travel Assistant",
    "instructions": "You are a helpful travel agent. You can check weather and book flights for customers.",
    "tools": [{"type": "function", "function": {"name": "check_weather", "description": "Get current weather for a city"}}],
}

# Initialize OpenAI client
from openai import OpenAI
client = OpenAI()

@interaction(name="travel_planning", pipeline_id=os.getenv("GENTRACE_PIPELINE_ID", ""))
def plan_trip(request: str) -> str:
    """Handle a travel planning request - automatically traced."""
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": travel_agent["instructions"]},
            {"role": "user", "content": request}
        ],
        tools=travel_agent["tools"],
    )
    return response.choices[0].message.content

# Usage
response = plan_trip("What's the weather like in San Francisco?")
print(f"Response: {response}")
```

## Environment Variables

```bash .env theme={null}
GENTRACE_API_KEY=your-gentrace-api-key
GENTRACE_PIPELINE_ID=your-pipeline-id
OPENAI_API_KEY=your-openai-api-key
```

## What Gets Traced

The OpenAI Agents instrumentation automatically captures:

* **Agent conversations** - All messages between users and agents
* **Tool calls** - Function invocations with parameters and results
* **Agent handoffs** - Transfers between specialized agents
* **Context variables** - Shared state between agents
* **Full message history** - Complete conversation flow

## Advanced Features

### Multiple Agents

```python theme={null}
# Define specialized agents
weather_agent = {
    "name": "Weather Expert",
    "instructions": "You provide weather information.",
    "tools": [{"type": "function", "function": {"name": "check_weather"}}],
}

booking_agent = {
    "name": "Booking Specialist",
    "instructions": "You handle flight and hotel bookings.",
    "tools": [
        {"type": "function", "function": {"name": "book_flight"}},
        {"type": "function", "function": {"name": "book_hotel"}}
    ],
}

# Agents can coordinate through tool calls
main_agent = {
    "name": "Travel Coordinator",
    "instructions": "Route weather questions to Weather Expert and bookings to Booking Specialist.",
    "tools": [
        {"type": "function", "function": {"name": "transfer_to_weather_agent"}},
        {"type": "function", "function": {"name": "transfer_to_booking_agent"}}
    ],
}
```

### Context Variables

```python theme={null}
# Pass context in the system message or as part of the conversation
context = {"user_preferences": "budget-friendly", "currency": "USD"}
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "system",
            "content": f"{travel_agent['instructions']}\nContext: {context}"
        },
        {"role": "user", "content": "Plan a trip to Paris"}
    ],
    tools=travel_agent["tools"],
)
```

## Related Resources

* [SDK Reference: init](/getting-started/initialization)
* [SDK Reference: interaction](/tracing/interactions)
* [Vercel AI SDK Integration](/integrations/ai-sdk)