Skip to content

OpenAI Agents SDK: using the VIDAI Control Plane as the backend

The OpenAI Agents SDK reads the same environment variables the underlying OpenAI SDK does. Set them to the control plane's values and every Runner.run(...) call — including tool calls and multi-agent handoffs — routes through the control plane.

TL;DR

export OPENAI_BASE_URL=https://your-vidai-server.example.com/v1
export OPENAI_API_KEY=your-vidai-key

from agents import Agent, Runner

agent = Agent(name="probe", instructions="Reply briefly.")
result = Runner.run_sync(agent, "reply with: ok")
print(result.final_output)

Prerequisites

  • pip install openai-agents.
  • Control plane base URL and an API key from API Keys.
  • A model registered on the Models page.

Passing config explicitly

If env vars aren't a fit (multiple agents on different endpoints in one process), pass a client on the agent's model:

from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel

client = AsyncOpenAI(
    base_url="https://your-vidai-server.example.com/v1",
    api_key="your-vidai-key",
)

agent = Agent(
    name="probe",
    instructions="Reply briefly.",
    model=OpenAIChatCompletionsModel(model="gpt-4o-mini", openai_client=client),
)

Handoffs

The Agents SDK routes control across agents via handoffs. Each handoff and every downstream turn is a control-plane request:

triage = Agent(
    name="triage",
    instructions="Route the question to the right specialist.",
    handoffs=[billing_agent, tech_agent],
)

result = Runner.run_sync(triage, "my card was double-charged")

The routing rules on your Routing page apply to every agent in the graph.

Tools

Function tools are called through the same client:

from agents import Agent, function_tool

@function_tool
def get_balance(user_id: str) -> float:
    return 42.00

agent = Agent(name="finance", instructions="Answer balance questions.", tools=[get_balance])

The tool-call round trips arrive in Request Logs attributed to the same key.

Structured output

Set output_type on the agent and the SDK requests structured output from the model. The control plane forwards it unchanged:

from pydantic import BaseModel

class Answer(BaseModel):
    intent: str
    action: str

agent = Agent(name="router", instructions="Classify.", output_type=Answer)

Streaming

Runner.run_streamed(...) streams events; the control plane forwards the stream:

result = Runner.run_streamed(agent, "count to five")
async for event in result.stream_events():
    if event.type == "raw_response_event":
        print(event.data, end="", flush=True)

Verify it works

import os
from agents import Agent, Runner

os.environ["OPENAI_BASE_URL"] = "https://your-vidai-server.example.com/v1"
os.environ["OPENAI_API_KEY"] = "your-vidai-key"

agent = Agent(name="probe", instructions="Reply briefly.")
print(Runner.run_sync(agent, "reply with exactly: ok").final_output)

If something's off

Raise an issue at github.com/vidaiUK/vidai-quickstart/issues with your agent definition and the run that reproduces the issue. We'll get it sorted.

Where to go next