OpenAI Agents SDK

Use Arbytra as your LLM provider in the OpenAI Agents SDK. This integration is Python-only. For TypeScript, use the Vercel AI SDK integration.

Requires openai-agents >=0.13.

Prerequisites

An Arbytra API key

Install

pip install "arbytra[openai-compat]" openai-agents

Use `ArbytraAsyncOpenAI` (experimental)

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

import asyncio
from agents import Agent, Runner, set_tracing_disabled
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
from arbytra import ArbytraAsyncOpenAI

set_tracing_disabled(True)

client = ArbytraAsyncOpenAI()
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:

from agents import Agent
from agents.model_settings import ModelSettings
from arbytra.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 Arbytra API accepts.

Access routing metadata

Read client.last_routing_metadata after a run completes:

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:

captured = []
client = ArbytraAsyncOpenAI(on_response=lambda m: captured.append(m))

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

Handle errors

ArbytraAsyncOpenAI raises errors catchable as both Arbytra and OpenAI error types:

import asyncio
import arbytra
from agents import Agent, Runner, set_tracing_disabled
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
from arbytra import ArbytraAsyncOpenAI

set_tracing_disabled(True)

async def main():
    client = ArbytraAsyncOpenAI()
    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 arbytra.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.

Mid-stream SSE errors (raised after the HTTP 200 during stream=True) remain unmapped openai.APIError. ArbytraAsyncOpenAI maps HTTP-level status errors only.

For the full class reference, see ArbytraAsyncOpenAI.

Configure manually

Alternative: configure OpenAI Agents SDK manually

If you prefer to configure the SDK’s client directly, without the Arbytra integration:

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.arbytra.com/v1",
    api_key=os.environ["ARBYTRA_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.

Get Started

Guides

Response API

Frameworks

Integrations

Specifications

Platform

Changelog

OpenAI Agents SDK

Prerequisites

Install

Use `ArbytraAsyncOpenAI` (experimental)

Configure routing

Access routing metadata

Handle errors

Configure manually

​Prerequisites

​Install

​Use ArbytraAsyncOpenAI (experimental)

​Configure routing

​Access routing metadata

​Handle errors

​Configure manually

Prerequisites

Install

Use `ArbytraAsyncOpenAI` (experimental)

Configure routing

Access routing metadata

Handle errors

Configure manually