Skip to content

OpenAI Agents SDK (Python)

OpenAI's Python SDK for agent apps: agents, tools, handoffs, guardrails, sessions, tracing, realtime voice and sandbox agents, with install, a first example and release notes.

GroupMulti-Agent
Current versionv0.24.0
Bonds withPy

OpenAI’s Python library for agent applications, and the successor to the experimental Swarm. A few primitives (Agent, tool, handoff, guardrail, session, runner) with built-in tracing, MCP support, human approvals, realtime voice, sandbox agents and test doubles. It works with OpenAI models and, through LiteLLM or any-llm, with other providers.

Install

Terminal window
pip install "openai-agents==0.24.0"

Version

v0.24.0 · checked 2026-11-19 · Python 3.10+ · openai v3

Best for

Multi-agent handoffs, customer-service bots, tracing-first apps.

This guide targets openai-agents 0.24.0. The SDK is versioned 0.Y.Z and a minor (Y) release may break public interfaces, so pin a minor range and check this table before upgrading. Taken from the upstream release notes; Breaking marks changes that can affect existing code.

ReleaseChanges
0.24MCP tool annotations exposed on converted tools; run-wide tool exception formatting; session, sandbox and approval fixes.
0.23Configurable MCP listing page limits; opt-in Docker removal protection for sandboxes; encrypted-history scan budget for sessions; Sandbox Agents no longer labelled beta.
0.22Breaking: failed or incomplete non-streaming Responses raise ModelBehaviorError; OpenAIProvider(openai_client=...) rejects organization/project. Blocked terminal tool output is withheld from history.
0.21Breaking: requires openai>=3.0.0,<4; OpenAI HTTP integrations move to HTTPX2, so custom http_client= objects must migrate from httpx to httpx2. Provider-neutral testing utilities (agents.testing).
0.20Breaking: default model is now gpt-5.6-luna. MCP Python SDK v2 supported (mcp>=1.19,<3); custom httpx auth/client factories move to httpx2 under MCP v2. RunState.add_input(); retry policies can approve unsafe replays explicitly.
0.19ProgrammaticToolCallingTool; @tool alias for @function_tool; settings accept dicts or typed objects.
0.18Default Realtime model gpt-realtime-2.1.
0.17Breaking: sandbox LocalFile/LocalDir sources must sit under the working directory unless granted with Manifest(extra_path_grants=...).
0.16Breaking: default model changed from gpt-4.1 to gpt-5.4-mini. max_turns=None disables the turn limit.
0.15Breaking: model refusals raise ModelRefusalError instead of producing an empty final_output; handle with error_handlers={"model_refusal": ...}.
0.14Sandbox Agents (SandboxAgent, Manifest, SandboxRunConfig) with Unix-local, Docker and hosted backends.
0.13MCPServer.list_resources() / read_resource(); resumable Streamable HTTP MCP sessions.
0.10WebSocket transport for Responses models (responses_websocket_session()), opt-in.
0.9Breaking: Python 3.9 dropped (3.10+). Agent.as_tool() return type narrowed to FunctionTool.
0.8Breaking: synchronous function tools run on worker threads; local MCP tool failures are returned to the model as error output by default (mcp_config={"failure_error_function": None} restores fail-fast).
0.7Breaking: nested handoff history is opt-in; set RunConfig(nest_handoff_history=True) to restore the 0.6 behaviour.
0.4Breaking: openai v1.x no longer supported.

Always set model= explicitly if you depend on a particular model: the default has changed twice.

from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant.",
)
result = Runner.run_sync(agent, "What is 2 + 2?")
print(result.final_output)

Ready? Start Zero → Hero Step 1 →


DateVersionChangesReviewer
2026-10-240.24.0Deep-dive audit: ran every example against a scripted model; fixed recipes whose handoff chains could not return their declared output type, concurrent runs sharing one session, and an invented confidence score; documented approval versus tool-guardrail ordering (ToolExecutionConfig); expanded the multi-agent page (handoff() options, as_tool() options); FastAPI streaming now handles errors and disconnects.—
2026-10-210.24.0Rewrote the production guide around the SDK’s own controls and the middleware stub as a hooks, tool-guardrails and approvals page; added realtime/voice, hosted MCP and testing sections; folded the “2025 features” page into the comprehensive guide and this page (one release table).—
2026-10-210.24.0Re-verified all code against the current release; replaced non-existent APIs; corrected the breaking-changes summary (MCP failure default was stated backwards); “What’s new” rewritten from the upstream changelog.—
2026-04-24 – 2026-05-270.14.5 – 0.17.4Routine version bumps with symbol checks against each installed release.Claude routine
2026-04-210.14.3Index redesigned with Zero → Hero + Jump-to-topic grid.—
2026-04-200.14.3Patch release; no breaking changes from 0.14.2.—
2026-04-160.14.0Sandbox agents and WebSocket transport sections added.—
2025-110.6.1Initial 2025 features; Swarm migration; MCP; guardrails; sessions.—

Note: TypeScript implementation lives at OpenAI Agents SDK (TypeScript).