Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://docs.respan.ai/mcp"
    }
  }
}
This integration is for the Respan gateway.

​
What is OpenAI Agents SDK?

The OpenAI Agents SDK is a lightweight framework for building multi-agent workflows. Route all agent LLM calls through the Respan gateway for centralized API key management, cost tracking, and load balancing.

​
Quickstart

​
Step 1: Install packages

pip install openai-agents python-dotenv

​
Step 2: Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
No OPENAI_API_KEY needed — the gateway handles authentication.

​
Step 3: Point the SDK to the Respan gateway

import os
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client

client = AsyncOpenAI(
    api_key=os.getenv("RESPAN_API_KEY"),
    base_url="https://api.respan.ai/api",
)
set_default_openai_client(client)

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant. Be concise.",
)

result = await Runner.run(agent, "What are the benefits of using an API gateway?")
print(result.final_output)

​
Step 4: Verify

Open the Logs page to see your gateway requests.

​
Examples

​
Switch models

Change the model parameter to use different providers through the same gateway. 
agent = Agent(
    name="Assistant",
    model="gpt-4o",  # or "claude-sonnet-4-5-20250929", "gemini-2.5-flash", etc.
    instructions="You are a helpful assistant.",
)
See the full model list.

​
Multi-agent handoff

Multiple agents with handoff routing, all proxied through the gateway. 
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client

client = AsyncOpenAI(
    api_key=os.getenv("RESPAN_API_KEY"),
    base_url="https://api.respan.ai/api",
)
set_default_openai_client(client)

billing_agent = Agent(
    name="Billing Agent",
    instructions="Handle billing and payment questions.",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="Handle technical support questions.",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route to the appropriate agent based on the question.",
    handoffs=[billing_agent, technical_agent],
)

result = await Runner.run(triage_agent, "I'm having trouble connecting to the API.")
print(f"Handled by: {result.last_agent.name}")
print(result.final_output)

​
Prompts

Use Respan prompt management to serve prompts from the platform. Pass prompt configuration via ModelSettings.extra_body. 
from agents import Agent, ModelSettings

agent = Agent(
    name="Prompt Agent",
    instructions="You are a helpful assistant.",
    model_settings=ModelSettings(
        extra_body={
            "prompt": {
                "prompt_id": "YOUR_PROMPT_ID",
                "schema_version": 2,
                "variables": {"task": "answer questions concisely"},
            }
        }
    ),
)
Use schema_version: 2 for all new integrations. Prompt messages are the base layer, request messages are appended after.
Three ways to pass prompts:
PatternMethodWhen to use
extra_body.promptDirectSimplest — prompt only
extra_body.respan_params.promptNestedNeed customer_identifier or other Respan params
X-Data-Respan-Params headerBase64When extra_body is unavailable
See the prompt gateway example for a working example.

​
Respan parameters

Pass Respan-specific parameters via extra_body. 
agent = Agent(
    name="Tracked Agent",
    model_settings=ModelSettings(
        extra_body={
            "respan_params": {
                "customer_identifier": "user_123",
                "metadata": {"env": "production"},
            }
        }
    ),
)
See Respan parameters for the full list.
Looking for tracing integration? See Tracing > OpenAI Agents SDK.