OpenAI Agents SDK

OpenAI Agents SDK is a Python framework for building agent applications with agents, tools, handoffs, guardrails, sessions, and tracing. It uses the Responses API by default and can use a custom OpenAI-compatible endpoint by configuring a custom AsyncOpenAI client.

Use this setup when an Agents SDK application should route model requests through AISIX while keeping the agent workflow.

This guide uses the default Responses API model path in OpenAI Agents SDK. You will configure AsyncOpenAI with an AISIX proxy URL, caller API key, and model alias.

Prerequisites

Before starting, prepare the following:

• A Python environment supported by OpenAI Agents SDK.
• A running AISIX gateway with the proxy listener available.
• An AISIX caller API key.
• A model alias the caller API key can access through the Responses API.

Configure OpenAI Agents SDK

Install OpenAI Agents SDK if the application does not already include it:

pip install openai-agents

Set the values that the agent application will use:

# Replace with your values
export AISIX_BASE_URL="http://127.0.0.1:3000/v1"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

Create an AsyncOpenAI client for AISIX and make it the SDK default client:

import asyncio
import os

from agents import (
  Agent,
  AsyncOpenAI,
  Runner,
  set_default_openai_client,
  set_tracing_disabled,
)

set_tracing_disabled(True)

client = AsyncOpenAI(
  base_url=os.environ["AISIX_BASE_URL"],
  api_key=os.environ["AISIX_API_KEY"],
)

set_default_openai_client(client, use_for_tracing=False)

agent = Agent(
  name="GatewayAgent",
  instructions="You answer in one concise sentence.",
  model=os.environ["AISIX_MODEL"],
)


async def main():
  result = await Runner.run(agent, "Why do gateways help AI teams?")
  print(result.final_output)


asyncio.run(main())

The model value is the AISIX model alias, not the upstream provider model ID. AISIX governs the model request path, while OpenAI Agents SDK still owns agent instructions, tools, handoffs, guardrails, and run orchestration.

This example disables the Agents SDK default trace export. If you need tracing, configure the SDK trace exporter separately so trace data follows your organization's policy.

OpenAI Agents SDK also supports OpenAIChatCompletionsModel for the Chat Completions API. Use that model shape when the workflow needs broad OpenAI-compatible provider support or already depends on Chat Completions behavior.

Verify the Integration

Run the script from the shell where the AISIX environment variables are set.

When the request succeeds, verify the following results:

• The script prints an agent response.
• AISIX records a successful POST /v1/responses request for the selected model alias.

If you use AISIX Cloud or an on-premises managed control plane, verify the request in the managed gateway logs. For self-hosted gateways, use your configured logs, metrics, or upstream provider logs.

If the request fails, first confirm that the caller API key can access the selected model alias and that base_url points to the AISIX proxy API root with /v1.

Hosted OpenAI tools and provider-specific Responses features may not map to every upstream provider. Validate Responses workflows before relying on gateway policy or telemetry for hosted tools, streaming, or provider-specific response items.

Next Steps

• Responses API: review gateway-facing Responses behavior.
• OpenAI-Compatible API: use Chat Completions when a workflow needs broad OpenAI-compatible support.
• Tool Calling: confirm tool-call behavior before enabling agent tools.