Install
pip install "openai-agents==0.24.0"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.
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
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.
| Release | Changes |
|---|---|
| 0.24 | MCP tool annotations exposed on converted tools; run-wide tool exception formatting; session, sandbox and approval fixes. |
| 0.23 | Configurable MCP listing page limits; opt-in Docker removal protection for sandboxes; encrypted-history scan budget for sessions; Sandbox Agents no longer labelled beta. |
| 0.22 | Breaking: failed or incomplete non-streaming Responses raise ModelBehaviorError; OpenAIProvider(openai_client=...) rejects organization/project. Blocked terminal tool output is withheld from history. |
| 0.21 | Breaking: 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.20 | Breaking: 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.19 | ProgrammaticToolCallingTool; @tool alias for @function_tool; settings accept dicts or typed objects. |
| 0.18 | Default Realtime model gpt-realtime-2.1. |
| 0.17 | Breaking: sandbox LocalFile/LocalDir sources must sit under the working directory unless granted with Manifest(extra_path_grants=...). |
| 0.16 | Breaking: default model changed from gpt-4.1 to gpt-5.4-mini. max_turns=None disables the turn limit. |
| 0.15 | Breaking: model refusals raise ModelRefusalError instead of producing an empty final_output; handle with error_handlers={"model_refusal": ...}. |
| 0.14 | Sandbox Agents (SandboxAgent, Manifest, SandboxRunConfig) with Unix-local, Docker and hosted backends. |
| 0.13 | MCPServer.list_resources() / read_resource(); resumable Streamable HTTP MCP sessions. |
| 0.10 | WebSocket transport for Responses models (responses_websocket_session()), opt-in. |
| 0.9 | Breaking: Python 3.9 dropped (3.10+). Agent.as_tool() return type narrowed to FunctionTool. |
| 0.8 | Breaking: 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.7 | Breaking: nested handoff history is opt-in; set RunConfig(nest_handoff_history=True) to restore the 0.6 behaviour. |
| 0.4 | Breaking: 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 →
| Date | Version | Changes | Reviewer |
|---|---|---|---|
| 2026-10-24 | 0.24.0 | Deep-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-21 | 0.24.0 | Rewrote 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-21 | 0.24.0 | Re-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-27 | 0.14.5 – 0.17.4 | Routine version bumps with symbol checks against each installed release. | Claude routine |
| 2026-04-21 | 0.14.3 | Index redesigned with Zero → Hero + Jump-to-topic grid. | — |
| 2026-04-20 | 0.14.3 | Patch release; no breaking changes from 0.14.2. | — |
| 2026-04-16 | 0.14.0 | Sandbox agents and WebSocket transport sections added. | — |
| 2025-11 | 0.6.1 | Initial 2025 features; Swarm migration; MCP; guardrails; sessions. | — |
Note: TypeScript implementation lives at OpenAI Agents SDK (TypeScript).