Skip to content

OpenAI Agents SDK

Your agents, tools and hand-offs stay as they are. Give the SDK a client that points at the gateway and every model call the runner makes is governed: checked against your policies, charged to the agent's team and recorded in Request logs. Switch it to Chat Completions and the same agents run on Claude or Gemini as well as OpenAI's models.

What it is

The openai-agents package for Python: agents, tools, hand-offs, guardrails and a runner that loops until the task is done. It calls models through the official openai client, so it speaks the OpenAI request format that the gateway accepts at /v1.

The SDK can call two OpenAI APIs, and the choice decides which models you can reach:

SDK model class API it calls Models it reaches through the gateway
OpenAIResponsesModel (the SDK's default) Responses, /v1/responses OpenAI and Azure OpenAI only
OpenAIChatCompletionsModel Chat Completions, /v1/chat/completions OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI

To use Claude or Gemini models, switch the SDK to Chat Completions (below).

The two settings

Setting Environment variable In code Value
Base address OPENAI_BASE_URL AsyncOpenAI(base_url=…) https://<your-gateway>/v1
Key OPENAI_API_KEY AsyncOpenAI(api_key=…) The agent's Vidai key (starts vk_), never a provider's key

Issue the key to the agent under Applications & agents (the agent's Keys section, Issue a key); its secret is shown once. The gateway's address and the base URL for each kind of SDK are under Connect your app on the Keys page and in System › Settings › Gateway.

The environment variables alone send the SDK to the gateway, on the Responses API. For every provider, set a default client and Chat Completions once, at start-up:

from openai import AsyncOpenAI
from agents import set_default_openai_client, set_default_openai_api, set_tracing_disabled

client = AsyncOpenAI(base_url="https://<your-gateway>/v1", api_key="vk_…")
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)  # see "Good to know": traces go to OpenAI, not the gateway

A minimal call

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="Reply briefly.",
    model="claude-sonnet-4.5",  # or "gpt-4o-mini", "gemini-3.5-flash"
)
result = Runner.run_sync(agent, "Say hello in Dutch.")
print(result.final_output)

Always name the model. An agent without one uses the SDK's own default OpenAI model, which may not be one your organisation approved.

To give one agent its own client (another key, say), wrap the client in a model instead of setting a default:

from agents import Agent, OpenAIChatCompletionsModel

agent = Agent(
    name="Billing",
    instructions="Answer billing questions.",
    model=OpenAIChatCompletionsModel(model="gpt-4o-mini", openai_client=client),
)

Streaming

import asyncio
from agents import Agent, Runner
from openai.types.responses import ResponseTextDeltaEvent

async def main():
    agent = Agent(name="Counter", instructions="Count as asked.", model="gemini-3.5-flash")
    result = Runner.run_streamed(agent, "Count to five.")
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="")

asyncio.run(main())

A stream from Claude or Gemini reaches the SDK as OpenAI chunks, and the SDK turns them into its usual events. Vidai records the tokens and the cost whether or not the stream carries usage.

Tool calls

Function tools and hand-offs work on every provider the gateway translates to: the SDK sends them as Chat Completions tools, and the model's tool calls come back in the OpenAI shape.

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Weather for a city."""
    return f"Sunny in {city}"

weather = Agent(name="Weather", instructions="Use the tool.", model="claude-sonnet-4.5", tools=[get_weather])
triage = Agent(name="Triage", instructions="Hand weather questions over.", model="gpt-4o-mini", handoffs=[weather])
print(Runner.run_sync(triage, "Weather in Utrecht?").final_output)

Each turn of the loop is its own call, so one run shows as several calls in Request logs, each with the tools it offered or called (filter Tool). Structured output (output_type= a Pydantic model) is sent as a JSON schema and works the same way.

The SDK's hosted tools (WebSearchTool, FileSearchTool, CodeInterpreterTool, ComputerTool) run inside OpenAI's Responses API: they need the Responses model and an OpenAI or Azure OpenAI model.

Reading what the gateway did

The runner doesn't hand you the response headers. Two ways to find a run's calls:

  • Look them up in Request logs: filter Agent (or Key) and Model. Each call shows the model that answered, what translation or a guardrail changed, the routing rule or fallback that acted, and the cost.
  • Send your own id with every call, and keep it in your logs beside the run:
from agents import Agent, ModelSettings

agent = Agent(
    name="Assistant",
    model="gpt-4o-mini",
    model_settings=ModelSettings(extra_headers={"x-request-id": "run-2026-11-12-0001"}),
)

The gateway keeps x-request-id with the call as the client's request id (up to 128 letters, digits and . _ : -).

To read the headers themselves (x-vidai-request-id, x-vidai-model, x-vidai-adapted), make the same call once with the plain OpenAI client: see OpenAI SDK for Python.

Errors

The gateway writes its errors in the OpenAI format, so the run raises the OpenAI client's usual exceptions. Match on the x-vidai-error-code header rather than the message.

Status Exception Common gateway codes
400 BadRequestError bad_request, a Responses call to a model that isn't OpenAI's or Azure's
401 AuthenticationError missing_api_key, invalid_api_key, conflicting_auth_headers
403 PermissionDeniedError api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 NotFoundError model_not_found, endpoint_not_found
429 RateLimitError rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx InternalServerError ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable
import openai
from agents import Runner

try:
    Runner.run_sync(agent, "Hi")
except openai.APIStatusError as e:
    print(e.status_code, e.response.headers.get("x-vidai-error-code"))
    print(e.response.headers.get("x-vidai-request-id"))  # paste into Request logs › Request reference

When an agent is suspended, or its key is switched off, its calls get api_key_disabled with a short reason in the error body (for example agent_suspended); treat the list of reasons as open-ended.

Model names

Use the names your organisation approved under Models in the Control room, within the agent's own list of models. await client.models.list() returns exactly the models the agent's key may call. An alias set by an admin works like any other name.

What goes through the gateway

Feature Through the gateway
Agents, function tools, hand-offs, structured output, streaming on the Chat Completions model Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models
Agents on the Responses model (the default), hosted tools Yes, to OpenAI and Azure OpenAI only; another provider gets a clear 400
Realtime and voice agents No: see Realtime API
Tracing No: traces go to OpenAI's trace service, not to the gateway

Check it works in a minute

export OPENAI_BASE_URL="https://<your-gateway>/v1"
export OPENAI_API_KEY="vk_…"
python -c "from agents import Agent, Runner, set_tracing_disabled; set_tracing_disabled(True); print(Runner.run_sync(Agent(name='p', model='gpt-4o-mini', instructions='Reply with ok.'), 'ping').final_output)"

A short answer means the address and key are right. The call shows under the agent in Request logs within seconds.

Good to know

  • Tracing is on by default and uploads traces to OpenAI with an OpenAI key, outside the gateway. Without an OpenAI key it fails with a 401 in the log. Switch it off with set_tracing_disabled(True), or give it its own key with set_tracing_export_api_key(…); never use the Vidai key for it.
  • The SDK doesn't retry model calls unless you set ModelSettings(retry=…), but the openai client under it retries twice by default. A fallback chain may already have tried another model first; build the client with max_retries=0 if you don't want both.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • OPENAI_API_BASE is not read by the openai client from version 1.0 on: use OPENAI_BASE_URL.