Skip to main content

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 with openai-agents 0.22.2 on openai 3.13.0. The package needs openai 3, so give the agent its own virtual environment if another library in the project pins an older openai.
  • Both addresses from the top of Studio's Developer Hub: https://<your tenant host>/public/v1 for the model and https://<your tenant host>/mcp for 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​

  1. 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 with kapi_ and refuses only the first tool call.
  2. result.new_items holds a ToolCallItem, its ToolCallOutputItem and a MessageOutputItem, in that order, and result.final_output answers from the tool's output: the number of agents and the name of the first one.
  3. 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 auto to required, so even a greeting produces a tool call before the answer. Attach the MCP server only to agents that need the tools, or set tool_choice on the agent's ModelSettings to none for 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_chat tool, which returns a session_id to pass back on the next call.
  • Agents created through the API. An agent created with katonic_create_agent or the API's create route cannot yet hold a conversation on the current build; chat with agents published from Studio.

Troubleshooting​

  • pip cannot resolve openai-agents next to another package. The package needs openai 3 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 OpenAIChatCompletionsModel as 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.
  • AuthenticationError on 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_chat can take longer. Raise client_session_timeout_seconds in the MCPServerStreamableHttp constructor.

Describes the platform as of .

Was this page helpful?