OpenAI Agents SDK
Type: full-code · Vendor: OpenAI · Language: Python, TypeScript · License: MIT · Status: active · Status in practice: mature · First released: 2025-03-04
Provide a lightweight, production-ready Python and TypeScript framework for building multi-agent workflows around four primitives: Agents, handoffs, guardrails, and sessions, with built-in tracing for the entire run.
Description. The OpenAI Agents SDK is the MIT-licensed successor to Swarm, shipped in March 2025. Its agent loop is small and explicit: Runner.run(agent, input) calls the LLM, executes any tool calls, follows any handoffs, and re-runs until the agent emits a final_output or max_turns is exceeded (MaxTurnsExceeded). Agents are LLMs configured with instructions, tools, optional output_type, handoffs, and guardrails. Handoffs are exposed to the model as transfer_to_<agent> tools with optional input_filter to reshape the conversation history. MCP support ships with three transports (Stdio, SSE, Streamable HTTP). SQLiteSession is the default session-memory backing store and supports run resumption across pauses.
Agent loop shape. Runner.run loop: call LLM -> if final_output, return; if handoff, swap current agent and re-run; if tool calls, execute and append results then re-run. Loop is capped by max_turns (None disables). Sessions automatically prepend prior history before each run and store new items afterwards.
Primary use cases
- multi-agent workflows where specialised agents hand off control
- agents that call MCP servers alongside Python function tools
- agents with input/output guardrails and Pydantic-typed outputs
- production agents that need built-in tracing and session memory
- TypeScript agents sharing the same primitive set as the Python SDK
Key concepts
- Agent → tool-use (docs) — LLM configured with instructions, tools, optional output_type, handoffs, guardrails.
- Runner → step-budget (docs) — Runs the agent loop via Runner.run / run_sync / run_streamed; capped by max_turns, raises MaxTurnsExceeded.
- Handoffs → handoff (docs) — Sub-agent delegation exposed as transfer_to_<agent> tools; handoff() customises tool name, description, on_handoff callback, input_filter.
- Guardrails → input-output-guardrails (docs) — Input guardrails run on the first agent's input; output guardrails on the last agent's final output. Input guardrails can run in parallel or block.
- Sessions → agent-resumption (docs) — Built-in session memory (SQLiteSession default) that prepends history before each run and stores new items afterwards; supports resumption after approval pauses.
- MCP transports → mcp (docs) — MCPServerStdio (subprocess), MCPServerSse (HTTP+SSE), MCPServerStreamableHttp (self-managed connection); tools exposed identically to function tools.
- output_type → structured-output (docs) — Optional Pydantic / typed output declaration that switches the model into structured-outputs mode.
Patterns this full-code implements —
- ★★Tool Use
Agent.tools accepts function tools (auto-schemaed from Python signatures) and MCP-exposed tools; the runner's loop executes tool calls and appends results before re-running.
- ★Handoff
Handoffs are surfaced to the LLM as transfer_to_<agent> tools; handoff() exposes tool_name_override, on_handoff, input_type, input_filter, is_enabled. The runner swaps current_agent on handoff and co…
- ★★Model Context Protocol
Three transports ship in the box: MCPServerStdio for subprocess servers, MCPServerSse for HTTP+SSE, MCPServerStreamableHttp for self-managed connections. MCP tools appear identically to function tool…
- ★★Step Budget
max_turns argument on Runner.run / run_sync / run_streamed caps the loop; exceeding it raises MaxTurnsExceeded. Pass None to disable.
- ★★Structured Output
Agent.output_type accepts a Pydantic / typed return; when set the SDK switches the model into structured-outputs mode.
- ★★Agent Resumption
Sessions persist conversation history; the runner prepends prior items before each run and stores new items afterwards. Runs that pause for approval can resume on the same session instance.
- ★★Supervisor
Two supported supervisor shapes are documented: (a) a manager agent that keeps the conversation and calls specialists through Agent.as_tool, and (b) decentralised peer handoff via transfer_to_*.
- ★★Input/Output Guardrails
Input guardrails run only for the first agent in the chain; output guardrails run only for the agent producing the final output. Input guardrails can run in parallel with the agent (default) or block…
- ★★ReAct
The Runner loop has the reason-act-observe shape (LLM produces output, either final or tool calls, which are executed and fed back). Upstream docs do not use the term 'ReAct'; downgraded from first-c…
- ★Subagent Isolation
Handoffs transfer control rather than spawn an isolated subagent; the delegated agent receives the conversation history (optionally reshaped via input_filter). Nested handoffs are an opt-in beta that…
Neighbourhood
Click any neighbour to follow the lineage. Scroll to zoom, drag to pan.
Alternatives & relatives
- full-code · framework
OpenAI Swarm
Production-ready evolution of Swarm; same primitive set (agents + handoffs) plus guardrails, sessions, tracing, MCP.
- full-code · framework
Claude Agent SDK
Same agent-sdk category, different vendor; Anthropic's SDK is filesystem-tool-first, OpenAI's is handoff-first.
- full-code · framework
Agent Development Kit (ADK)
Google's competitor in the agent-sdk category.
- full-code · framework
Vercel AI SDK
TypeScript-first competitor in the same category.
Listed as alternative by (5)
Predecessor of (1)
References
Provenance
- Last analyzed:
- Last updated:
- Verification status: verified