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 withset_tracing_export_api_key(…); never use the Vidai key for it. - The SDK doesn't retry model calls unless you set
ModelSettings(retry=…), but theopenaiclient under it retries twice by default. A fallback chain may already have tried another model first; build the client withmax_retries=0if you don't want both. - The gateway's own 429 has no
Retry-Afterheader; back off on your side. OPENAI_API_BASEis not read by theopenaiclient from version 1.0 on: useOPENAI_BASE_URL.