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

# OpenAI Agents SDK

> Add HoneyHive observability to your OpenAI Agents SDK applications

[OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) is a lightweight framework for building multi-agent workflows. It provides agents, handoffs, tools, guardrails, and session management out of the box.

HoneyHive integrates with the Agents SDK via the `OpenAIAgentsInstrumentor`, automatically capturing agent runs, tool calls, handoffs, and LLM interactions.

## Quick Start

<Tip>
  **Add HoneyHive tracing in just 3 lines of code.** Initialize the tracer and instrumentor, and all agent runs, tool calls, handoffs, and model calls are automatically traced.
</Tip>

<Tip>
  To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see [Tracer Initialization](/v2/tracing/tracer-initialization).
</Tip>

<Note>
  Last tested with `openai-agents 0.14.6` (April 2026).
</Note>

```bash theme={null}
pip install honeyhive openai-agents openinference-instrumentation-openai-agents
```

```python theme={null}
import os
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)

# Your existing Agents SDK code works unchanged
# Call tracer.force_flush() before your process exits
```

## What Gets Traced

This setup captures:

* **Agent runs** - Every agent invocation with inputs and outputs
* **LLM calls** - Model requests, responses, and token usage
* **Tool calls** - Each tool execution with arguments and results
* **Handoffs** - Agent-to-agent delegation with routing context
* **Agents-as-tools** - Nested agent delegation via `agent.as_tool()`

No manual `@trace` decorators are required for the standard Agents SDK path.

***

<Note>
  The `openai-agents` pip package exposes `agents` as its top-level module, so imports use `from agents import ...`.

  All examples below assume the [Quick Start](#quick-start) setup above. The setup block is repeated in each snippet so they are individually copy-pasteable.
</Note>

## Example: Single Agent with Tools

```python theme={null}
import asyncio
import os

from agents import Agent, Runner, function_tool
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)


@function_tool
def lookup_order_status(order_id: str) -> str:
    """Look up the current status and ETA for a customer order."""
    statuses = {
        "ORD-1001": {"state": "shipped", "eta_days": 2},
        "ORD-1002": {"state": "processing", "eta_days": 5},
        "ORD-1003": {"state": "delayed", "eta_days": 8},
    }
    status = statuses.get(order_id.upper())
    if status:
        return (
            f"Order {order_id.upper()}: {status['state']}, "
            f"estimated delivery in {status['eta_days']} days."
        )
    return f"Order {order_id.upper()}: not found in the system."


@function_tool
def lookup_policy(topic: str) -> str:
    """Look up support policy by topic: refund, cancellation, or shipping."""
    policies = {
        "refund": "Refunds are available within 30 days for undelivered or damaged items.",
        "cancellation": "Cancellation is allowed before shipment. Delayed orders can request assisted cancellation.",
        "shipping": "Delays beyond 7 days trigger proactive support outreach.",
    }
    return policies.get(topic.strip().lower(), "No policy found.")


agent = Agent(
    name="Support Generalist",
    instructions=(
        "You are a customer support generalist. Use tools for order status and "
        "policy questions, then reply with short, customer-friendly answers."
    ),
    tools=[lookup_order_status, lookup_policy],
)


async def main():
    await Runner.run(
        agent,
        "For delayed order ORD-1003, explain the cancellation policy and "
        "recommended next steps.",
    )
    tracer.force_flush()


asyncio.run(main())
```

***

## Example: Multi-Agent Handoffs

The Agents SDK supports handoffs where a triage agent delegates to specialists:

```python theme={null}
import asyncio
import os

from agents import Agent, Runner, function_tool
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)


@function_tool
def lookup_order_status(order_id: str) -> str:
    """Look up order status."""
    return f"Order {order_id}: shipped, ETA 2 days"


@function_tool
def lookup_policy(topic: str) -> str:
    """Look up support policy."""
    return f"Policy ({topic}): Refunds within 30 days for undelivered items."


order_specialist = Agent(
    name="Order Specialist",
    handoff_description="Handles shipment and delivery questions.",
    instructions="Use lookup_order_status for order questions. Be concise.",
    tools=[lookup_order_status],
)

policy_specialist = Agent(
    name="Policy Specialist",
    handoff_description="Handles refund, cancellation, and shipping policy questions.",
    instructions="Use lookup_policy for policy questions. Be concise.",
    tools=[lookup_policy],
)

triage_agent = Agent(
    name="Triage Agent",
    instructions=(
        "Route order questions to Order Specialist "
        "and policy questions to Policy Specialist."
    ),
    handoffs=[order_specialist, policy_specialist],
)


async def main():
    await Runner.run(triage_agent, "Where is my order ORD-1001?")
    tracer.force_flush()


asyncio.run(main())
```

In HoneyHive, you'll see the full trace hierarchy: triage agent routing to the specialist, which then calls the tool and responds.

***

## Example: Agents-as-Tools

For parallel execution, wrap specialist agents as tools using `agent.as_tool()`:

```python theme={null}
import asyncio
import os

from agents import Agent, Runner, function_tool
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)


@function_tool
def lookup_order_status(order_id: str) -> str:
    """Look up order status."""
    return f"Order {order_id}: delayed, ETA 8 days"


@function_tool
def lookup_policy(topic: str) -> str:
    """Look up support policy."""
    return f"Policy ({topic}): Cancellation allowed before shipment."


order_tool_agent = Agent(
    name="Order Lookup Agent",
    instructions="Use lookup_order_status to check orders.",
    tools=[lookup_order_status],
)

policy_tool_agent = Agent(
    name="Policy Lookup Agent",
    instructions="Use lookup_policy for policy questions.",
    tools=[lookup_policy],
)

coordinator = Agent(
    name="Support Coordinator",
    instructions=(
        "Use order_lookup and policy_lookup to gather information, "
        "then combine into a concise customer response."
    ),
    tools=[
        order_tool_agent.as_tool(
            tool_name="order_lookup",  # coordinator sees this agent as "order_lookup"
            tool_description="Look up order status information.",
        ),
        policy_tool_agent.as_tool(
            tool_name="policy_lookup",  # coordinator sees this agent as "policy_lookup"
            tool_description="Look up support policy information.",
        ),
    ],
)


async def main():
    await Runner.run(
        coordinator,
        "Order ORD-1003 is delayed. Can I cancel and get a refund?",
    )
    tracer.force_flush()


asyncio.run(main())
```

In HoneyHive, you'll see the coordinator agent calling specialist sub-agents as tools, with nested LLM and tool spans.

***

## Troubleshooting

### Traces not appearing

1. **Check environment variables** - Ensure `HH_API_KEY` and `HH_PROJECT` are set
2. **Pass the tracer provider** - The instrumentor must receive `tracer_provider=tracer.provider`:

```python theme={null}
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

tracer = HoneyHiveTracer.init(project="your-project")

# Correct - pass tracer_provider
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)

# Wrong - missing tracer_provider
OpenAIAgentsInstrumentor().instrument()
```

3. **Call `force_flush()` before exit** - Ensure traces are exported before the process ends:

```python theme={null}
try:
    await Runner.run(agent, "Hello")
finally:
    tracer.force_flush()
```

4. **Check your model provider** - Ensure `OPENAI_API_KEY` is set

***

## Related

<CardGroup cols={2}>
  <Card title="Enrich Your Traces" icon="sparkles" href="/v2/tutorials/enriching-traces">
    Add user IDs and custom metadata to agent traces
  </Card>

  <Card title="Custom Spans" icon="code" href="/v2/tracing/custom-spans">
    Create spans for business logic around agent calls
  </Card>

  <Card title="Distributed Tracing" icon="share-nodes" href="/v2/tutorials/distributed-tracing">
    Trace agents across service boundaries
  </Card>
</CardGroup>

***

## Resources

* [OpenAI Agents SDK Documentation](https://openai.github.io/openai-agents-python/)
* [OpenAI Agents SDK GitHub](https://github.com/openai/openai-agents-python)