OpenAI Agents SDK
Public API
The OpenAI Agents SDK runs agent loops: a model, instructions, tools, handoffs and guardrails. Two of its building blocks point at your tenant. OpenAIChatCompletionsModel sends the model's turns to your tenant's public API, and MCPServerStreamableHttp gives the agent your tenant's nineteen MCP tools. One key serves both, so the agent needs no OpenAI account of its own, and every model turn runs through your tenant's AI Gateway.
Who can use it: anyone holding an API key with the Chat scope for the model turns; each MCP tool needs the scope of the public API route it calls, listed on Tools. The Full access preset covers all of them. The tenant must be licensed for the public API.
Prerequisites
- Python 3.10 or later and
pip install openai-agents. Verified withopenai-agents0.22.2 onopenai3.13.0. The package needsopenai3, so give the agent its own virtual environment if another library in the project pins an olderopenai. - Both addresses from the top of Studio's Developer Hub:
https://<your tenant host>/public/v1for the model andhttps://<your tenant host>/mcpfor the tools. - A key from the Developer Hub's API keys tab, and a model id your tenant serves. The models route lists them; Use an OpenAI client library shows the call.
Connect
import asyncio
from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled
from agents.mcp import MCPServerStreamableHttp
from openai import AsyncOpenAI
HOST = "<your tenant host>"
KEY = "kapi_YOUR_KEY"
set_tracing_disabled(True)
client = AsyncOpenAI(base_url=f"https://{HOST}/public/v1", api_key=KEY)
model = OpenAIChatCompletionsModel(model="<a model id your tenant serves>", openai_client=client)
async def main():
async with MCPServerStreamableHttp(
name="katonic",
params={"url": f"https://{HOST}/mcp", "headers": {"Authorization": f"Bearer {KEY}"}},
cache_tools_list=True,
) as katonic:
tools = await katonic.list_tools()
print(len(tools), "tools")
agent = Agent(
name="Assistant",
instructions="Answer briefly. Use the Katonic tools for questions about this tenant.",
model=model,
mcp_servers=[katonic],
)
result = await Runner.run(agent, "How many agents does this tenant have, and what is the first one called?")
print([type(item).__name__ for item in result.new_items])
print(result.final_output)
asyncio.run(main())
Three choices in that program matter. OpenAIChatCompletionsModel rather than a bare model name: given a name string, the SDK uses its Responses model, and the public API does not serve the Responses route. set_tracing_disabled(True): the SDK's tracing exporter uploads traces to OpenAI's platform with the key the SDK holds, which with your tenant's key both fails and hands the key to another service; disable tracing, or give the exporter its own OpenAI key with set_tracing_export_api_key. cache_tools_list=True: the tool list is fetched once per connection rather than before every turn.
Verify
list_tools()returns nineteen tools. That proves the endpoint and the protocol, not the key: the MCP server accepts the handshake from any key that starts withkapi_and refuses only the first tool call.result.new_itemsholds aToolCallItem, itsToolCallOutputItemand aMessageOutputItem, in that order, andresult.final_outputanswers from the tool's output: the number of agents and the name of the first one.- The key's row on the Developer Hub's API keys tab shows a new last-used time, and each model turn appears in the Control Room's AI Gateway under Logs as a line naming the provider, model, tier, tokens, cost and latency. A question answered through a tool produces two lines, one per model call; the tool call itself is not a model call and leaves no line there.
What does not carry over
- Every first turn calls a tool. With MCP tools attached, the gateway upgrades the first model turn's tool choice from absent or
autotorequired, so even a greeting produces a tool call before the answer. Attach the MCP server only to agents that need the tools, or settool_choiceon the agent'sModelSettingstononefor a turn that must not call one. See Call tools from a completion. - Hosted tools. Web search, file search, code interpreter and the other tools OpenAI hosts run on OpenAI's Responses route and are not available here. Function tools, MCP tools, handoffs and guardrails are the SDK's own and run in your process.
- Tracing. Off, or exported with a separate OpenAI key, as above. Your tenant records the model turns in the AI Gateway's logs and analytics regardless.
- Conversation memory. The SDK keeps the run's history in your process. The platform's sessions are separate and are reached through the
katonic_chattool, which returns asession_idto pass back on the next call. - Agents created through the API. An agent created with
katonic_create_agentor the API's create route cannot yet hold a conversation on the current build; chat with agents published from Studio.
Troubleshooting
pipcannot resolveopenai-agentsnext to another package. The package needsopenai3 and the other package pins an older major. Give the agent its own virtual environment.- The first model turn fails with a not-found error. The agent was given a model name string, so the SDK called the Responses route. Pass an
OpenAIChatCompletionsModelas above. - Tracing errors appear in the log after each run. The exporter tried OpenAI's platform with your tenant's key. Call
set_tracing_disabled(True)before the first run. list_tools()succeeds and the first tool call fails with an internal error. The key is invalid, expired, revoked or lacks the tool's scope; the server reports all four the same way on the current build. Check the key's row and scopes on the API keys tab.AuthenticationErroron the model turn while the tools work. The key lacks the Chat scope; the gateway reports a missing scope as an invalid key.- A tool call times out. The SDK's default per-call timeout is a few seconds and
katonic_chatcan take longer. Raiseclient_session_timeout_secondsin theMCPServerStreamableHttpconstructor.