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

# OpenAI Agents SDK

> Use the OpenAI Agents SDK with Auriko's routing and cost optimization

Use Auriko as your LLM provider in the OpenAI Agents SDK.

This integration is Python-only. For TypeScript, use the [Vercel AI SDK](/frameworks/vercel-ai-sdk) integration.

<Note>
  Requires `openai-agents` >=0.13.
</Note>

## Prerequisites

* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)

## Install

```bash theme={null}
pip install "auriko[openai-compat]" openai-agents
```

## Use `AurikoAsyncOpenAI` (experimental)

`AurikoAsyncOpenAI` (experimental) is an `AsyncOpenAI` subclass that captures routing metadata from every successful response. Pass it to `OpenAIChatCompletionsModel` via the `openai_client=` parameter:

```python theme={null}
import asyncio
from agents import Agent, Runner, set_tracing_disabled
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
from auriko import AurikoAsyncOpenAI

set_tracing_disabled(True)

client = AurikoAsyncOpenAI()
model = OpenAIChatCompletionsModel(model="gpt-4o-mini", openai_client=client)
agent = Agent(name="assistant", instructions="Be brief.", model=model)

async def main():
    result = await Runner.run(agent, input="What is the capital of France?")
    print(result.final_output)
    print(client.last_routing_metadata.provider)

asyncio.run(main())
```

`Runner.run_sync()` works the same way.

### Configure routing

Pass routing options through `ModelSettings.extra_body`, not through the `client.chat.completions.create()` call:

```python theme={null}
from agents import Agent
from agents.model_settings import ModelSettings
from auriko.route_types import RoutingOptions

model_settings = ModelSettings(
    extra_body=RoutingOptions(optimize="cost").to_extra_body(),
)
agent = Agent(name="assistant", instructions="Be brief.", model=model, model_settings=model_settings)
```

The Agents SDK forwards `ModelSettings.extra_body` to the API call. `RoutingOptions.to_extra_body()` returns a dict the Auriko API accepts.

### Access routing metadata

Read `client.last_routing_metadata` after a run completes:

```python theme={null}
result = Runner.run_sync(agent, "Hello!")
print(client.last_routing_metadata.provider)
print(client.last_routing_metadata.routing_strategy)
```

The property uses last-write-wins semantics on a shared client. For per-request capture across concurrent runs, pass an `on_response` callback:

```python theme={null}
captured = []
client = AurikoAsyncOpenAI(on_response=lambda m: captured.append(m))
```

The callback must be synchronous. Passing an async callable raises `TypeError`.

### Handle errors

`AurikoAsyncOpenAI` raises errors catchable as both Auriko and OpenAI error types:

```python theme={null}
import asyncio
import auriko
from agents import Agent, Runner, set_tracing_disabled
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
from auriko import AurikoAsyncOpenAI

set_tracing_disabled(True)

async def main():
    client = AurikoAsyncOpenAI()
    model = OpenAIChatCompletionsModel(model="gpt-4o-mini", openai_client=client)
    agent = Agent(name="assistant", instructions="Be brief.", model=model)
    try:
        result = await Runner.run(agent, input="Hello!")
        print(result.final_output)
    except auriko.RateLimitError as e:  # also catchable as openai.RateLimitError
        print(f"Rate limited: {e.message}")

asyncio.run(main())
```

The same error is also catchable as `openai.RateLimitError`.

Network-layer exceptions (`openai.APITimeoutError`, `openai.APIConnectionError`) propagate unchanged.

<Note>
  Mid-stream SSE errors (raised after the HTTP 200 during `stream=True`) remain unmapped `openai.APIError`. `AurikoAsyncOpenAI` maps HTTP-level status errors only.
</Note>

For the full class reference, see [`AurikoAsyncOpenAI`](/sdk/python-reference#aurikoasyncopenai-experimental).

## Configure manually

<Accordion title="Alternative: configure OpenAI Agents SDK manually">
  If you prefer to configure the SDK's client directly, without the Auriko integration:

  ```python theme={null}
  import asyncio
  import os
  from openai import AsyncOpenAI
  from agents import Agent, Runner, set_default_openai_client, set_default_openai_api, set_tracing_disabled

  set_default_openai_api("chat_completions")
  set_tracing_disabled(True)

  client = AsyncOpenAI(
      base_url="https://api.auriko.ai/v1",
      api_key=os.environ["AURIKO_API_KEY"],
  )
  set_default_openai_client(client, use_for_tracing=False)

  agent = Agent(name="assistant", instructions="Be helpful.", model="gpt-5.4")

  async def main():
      result = await Runner.run(agent, input="Hello!")
      print(result.final_output)

  asyncio.run(main())
  ```

  `set_default_openai_api("chat_completions")` is the default for the Agents SDK. Both Chat Completions and Response API streaming include `routing_metadata`.
</Accordion>