OpenAI Agents SDK (Python)

The official production-ready replacement for Swarm. Lightweight primitives (Agent, Handoff, Guardrail, Session, Tool) with built-in tracing, MCP support, and provider-agnostic LLM access (OpenAI + 100+ via LiteLLM).

Install

pip install "openai>=2.0" openai-agents

Version

v0.17.4 · May 2026 · Python 3.10+

Best for

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

Where to start

New to the SDK? Follow Zero → Hero below in order. Migrating from Swarm? Start at Swarm migration.

Zero → Hero

1 · Install & setup Environment, API key, first agent · 10 min

2 · Design philosophy Why minimal primitives, where the seams are · 10 min

3 · Core primitives Agent, Handoff, Guardrail, Session, Tool, Runner · 20 min

4 · Your first agent Linear chat, context, async patterns · 20 min

5 · Multi-agent systems Handoffs, specialist routing · 25 min

6 · Tools integration Function tools, MCP, built-in tools · 20 min

7 · Structured outputs Pydantic validation, type-safe responses · 15 min

8 · Guardrails & safety Input/output validation, custom checks · 15 min

9 · Middleware Lifecycle hooks, custom processing · 20 min

10 · Tracing & observability Platform traces, Langfuse/AgentOps · 15 min

11 · Production Deployment, scaling, resilience · 30 min

Jump to a topic

Agent primitive

Handoffs

Function tools

MCP integration

Guardrails

Sessions (SQLite/Redis/SQLAlchemy)

Agentic patterns

Responses API

Realtime experiences

Model providers (LiteLLM)

Sandbox agents (v0.14)

Swarm migration

Reference

Comprehensive guide Single-page technical reference.

2025 features Sandbox agents, WebSocket transport, tracing, LiteLLM, MCP.

Swarm migration guide Side-by-side code comparisons + migration checklist.

Advanced multi-agent

Middleware (Python)

Recipes Customer service, research, code review, translation, moderation.

Diagrams

Production guide

Streaming server (FastAPI)

What’s new in v0.17.4 (May 2026)

• v0.17.4 (May 2026) — Patch release; stability and dependency improvements. All key symbols (Agent, Runner, Handoff, ShellTool, LocalShellTool, ToolSearchTool, ApplyPatchTool, RetryPolicy, Session, SessionABC, RunState, StopAtTools, RunErrorHandlers, HostedMCPTool, ImageGenerationTool, OpenAIResponsesCompactionSession, OpenAIConversationsSession, ResponsesWebSocketSession) confirmed present in installed openai-agents==0.17.4 (.routine-envs/openai-agents); no DeprecationWarning emissions.
• v0.17.3 (May 2026) — Patch release; stability and dependency improvements.
• v0.17.2 (May 12) — Patch release; stability and dependency improvements.
• v0.17.1 (May 11) — Patch release; stability and dependency improvements.
• v0.17.0 (May 9) — New tools and retry infrastructure. ShellTool and LocalShellTool for sandboxed shell command execution (from agents.tool); ToolSearchTool for dynamic tool discovery; ApplyPatchTool for code-patch application. RetryPolicy type alias (from agents.retry) for configurable per-agent retry strategies. Session / SessionABC abstractions (from agents.memory.session) for structured session management. All confirmed present in installed openai-agents==0.17.0 (.routine-envs/check-0509-py).
• v0.16.1 (May 7) — Patch; stability improvements.
• v0.16.0 (May 6) — Minor release; session management restructured into agents.memory.session.
• v0.15.3 (May 5) — Patch; dependency updates.
• v0.15.1 (May 2) — Patch release; stability and dependency updates.
• v0.15.0 (May 1) — Minor release; stability and dependency updates.
• v0.14.8 (April 29) — Patch release; stability improvements.
• v0.14.7 (April 28) — Patch release; stability improvements.
• Sandbox agents — persistent isolated workspaces with files, directories, Git repos, snapshots. Backends: local Unix, Docker, Blaxel, E2B, Modal, Runloop, Vercel.
• WebSocket transport for OpenAI Responses models — low-latency multi-turn conversations via responses_websocket_session().
• Sync function tools now run on worker threads via asyncio.to_thread().

Breaking changes from v0.6.x

• Requires openai>=2.0 — v1.x is no longer supported.
• Python 3.9 dropped; minimum is now 3.10.
• MCP tool failures propagate as exceptions by default — configure failure_error_function to restore previous behaviour.
• Agent#as_tool() return type narrowed from Tool to FunctionTool.

Install, minimal example

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 →

---

Revision history

Date	Version	Changes	Reviewer
2026-05-27	0.17.4	Version bumped 0.17.3 → 0.17.4; “What’s new” updated; comprehensive guide header updated; revision history entry added. All key symbols (Agent, Runner, Handoff, ShellTool, LocalShellTool, ToolSearchTool, ApplyPatchTool, RetryPolicy, Session, SessionABC, RunState, StopAtTools, RunErrorHandlers, HostedMCPTool, ImageGenerationTool, OpenAIResponsesCompactionSession, OpenAIConversationsSession, ResponsesWebSocketSession) verified with -W error::DeprecationWarning against installed openai-agents 0.17.4 (.routine-envs/openai-agents); no DeprecationWarning emissions.	Claude routine
2026-05-19	0.17.3	Version bumped 0.17.2 → 0.17.3; “What’s new” updated; comprehensive guide header updated; revision history entry added. All key symbols verified against installed openai-agents 0.17.3 (.routine-envs/check-0519-py); no DeprecationWarning emissions.	Claude routine
2026-05-12	0.17.2	Version bumped 0.17.1 → 0.17.2; “What’s new” section updated; comprehensive guide header updated; revision history entry added. All key symbols (Agent, Runner, Handoff, ShellTool, LocalShellTool, ToolSearchTool, ApplyPatchTool, RetryPolicy, Session, SessionABC, RunState, StopAtTools, RunErrorHandlers, HostedMCPTool, ImageGenerationTool, OpenAIResponsesCompactionSession, OpenAIConversationsSession, ResponsesWebSocketSession) verified with -W error::DeprecationWarning against installed openai-agents 0.17.2 (.routine-envs/check-0512-py).	Claude routine
2026-05-11	0.17.1	Version bumped 0.17.0 → 0.17.1; “What’s new” section updated; comprehensive guide header updated; revision history entry added. All key symbols verified with -W error::DeprecationWarning against installed openai-agents 0.17.1 (.routine-envs/check-0511-py).	Claude routine
2026-05-09	0.17.0	Version bumped 0.15.1 → 0.17.0 (four releases: 0.15.3, 0.16.0, 0.16.1, 0.17.0); “What’s new” section updated; comprehensive guide header updated; revision history entry added. New symbols ShellTool, LocalShellTool, ToolSearchTool, ApplyPatchTool, RetryPolicy, Session, SessionABC verified against installed openai-agents 0.17.0 (.routine-envs/check-0509-py).	Claude routine
2026-05-02	0.15.1	Version bumped 0.15.0 → 0.15.1; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. Agent, Runner, Handoff, guardrail imports verified against installed 0.15.1 (.routine-envs/check-openai-0502).	Claude routine
2026-05-01	0.15.0	Version bumped 0.14.8 → 0.15.0; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. Agent, Runner, Handoff, guardrail imports verified against installed 0.15.0 (.routine-envs/check-openai-0501).	Claude routine
2026-04-29	0.14.8	Version bumped 0.14.7 → 0.14.8; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. Snippets verified against installed 0.14.8 (.routine-envs/main-py-0429).	Claude routine
2026-04-28	0.14.7	Version bumped 0.14.6 → 0.14.7; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. Snippets verified against installed 0.14.7.	Claude routine
2026-04-25	0.14.6	Version bumped 0.14.5 → 0.14.6; “What’s new” heading updated; comprehensive guide header updated; revision history entry added. Snippets verified against installed 0.14.6.	Claude routine
2026-04-24	0.14.5	Version bumped 0.14.4 → 0.14.5; “What’s new” heading updated; comprehensive guide header updated; revision history entry added.	—
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.	—
April 16, 2026	0.14.0	Sandbox agents; WebSocket transport; openai v2 requirement; Python 3.9 dropped.	—
November 2025	0.6.1	Initial 2025 features; Swarm migration; MCP; guardrails; sessions.	—

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