OpenAI Agents SDK

raw JSON →
0.10.1 verified Tue May 12 auth: no python install: verified quickstart: verified

Lightweight multi-agent orchestration framework by OpenAI. Production successor to Swarm. Provider-agnostic.

pip install openai-agents

Common errors

error ModuleNotFoundError: No module named 'agents' ↓
cause Developers often try to import 'agents' directly, but the correct Python package name for OpenAI Agents is 'openai-agents'. Alternatively, a local file or directory named 'agents.py' or 'agents' might be shadowing the installed package.
fix
Ensure the package is installed with pip install openai-agents and then import using from openai_agents import Agent, Runner (or other specific modules) in your code. Also, check that no local file or directory is named 'agents.py' or 'agents' in your project path.
error AttributeError: module 'openai' has no attribute 'ChatCompletion' ↓
cause This error occurs when code written for the older OpenAI Python client library (pre-1.0, which used `openai.ChatCompletion.create`) is run with the newer OpenAI Python client library (v1.0+, which uses `client.chat.completions.create`).
fix
Upgrade the openai package to version 1.0.0 or newer (pip install --upgrade openai) and update your code to use the new client syntax, e.g., from openai import OpenAI; client = OpenAI(); client.chat.completions.create(...).
error AttributeError: module 'openai' has no attribute 'OpenAI' ↓
cause This error typically arises when attempting to initialize the OpenAI client using `client = openai.OpenAI()` but an older version of the `openai` Python package (pre-1.0) is installed, which did not expose the `OpenAI` class directly.
fix
Upgrade your openai package to version 1.0.0 or newer using pip install --upgrade openai.
error The model did not produce a final response! ↓
cause This specific error from the `openai-agents` SDK indicates that the agent, based on its instructions and internal processing, failed to generate an output that the framework recognized as a 'final response' within the given execution constraints, often due to unclear instructions, `max_turns` being exceeded, or unexpected model behavior.
fix
Review and refine the agent's instructions to clearly define what constitutes a 'final response' and ensure the model has sufficient turns (max_turns parameter in Runner.run) to complete the task. Enable debug logging (DEBUG=openai-agents:*) to understand the agent's internal reasoning and identify where it deviates from producing a final output.

Warnings

breaking openai v1.x is no longer supported. Must use openai>=2.0.0. ↓
fix pip install 'openai>=2.0.0' before installing openai-agents
breaking Python 3.9 support dropped. Minimum runtime is Python 3.10. ↓
fix Upgrade to Python 3.10+
deprecated Swarm is the deprecated predecessor. Do not use openai/swarm — openai-agents is the production replacement. ↓
fix Migrate to openai-agents. Primitives are similar but not identical.
gotcha MCP server methods (list_tools(), etc.) now take AgentBase, not Agent as type hint. Runtime behavior unchanged — objects are still Agent instances. ↓
fix Update type annotations: replace Agent with AgentBase where type errors appear
gotcha Agent.as_tool() return type narrowed from Tool to FunctionTool. May cause type errors if you relied on the broader union. ↓
fix Update type annotations to FunctionTool where needed
gotcha RealtimeAgent is beta. Breaking changes expected. Azure realtime: use GA URL path (wss://.../openai/v1/realtime), not legacy beta path (/openai/realtime?api-version=...). ↓
fix Pin version if using RealtimeAgent in production. Use GA URL format for Azure.
gotcha WebSocket transport for Responses API is opt-in. Default remains HTTP. Must call set_default_openai_responses_transport('websocket') to enable globally. ↓
fix No action needed unless you want WebSocket mode explicitly
breaking OpenAI client requires an API key. Ensure OPENAI_API_KEY is set in your environment or passed directly to the client. ↓
fix Set the OPENAI_API_KEY environment variable (e.g., export OPENAI_API_KEY='your_key_here') or pass api_key argument to the OpenAI client constructor.

Install

uv add openai-agents
pip install 'openai-agents[voice]'
pip install 'openai-agents[redis]'

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk
3.10 alpine (musl) redis - - 4.29s 82.9M
3.10 alpine (musl) voice - - 4.24s 151.9M
3.10 alpine (musl) openai-agents - - 4.26s 79.0M
3.10 slim (glibc) redis - - 3.19s 82M
3.10 slim (glibc) voice - - 3.35s 146M
3.10 slim (glibc) openai-agents - - 3.21s 78M
3.11 alpine (musl) redis - - 5.49s 90.6M
3.11 alpine (musl) voice - - 5.59s 164.9M
3.11 alpine (musl) openai-agents - - 5.46s 86.1M
3.11 slim (glibc) redis - - 4.62s 89M
3.11 slim (glibc) voice - - 4.67s 159M
3.11 slim (glibc) openai-agents - - 4.66s 85M
3.12 alpine (musl) redis - - 4.66s 81.0M
3.12 alpine (musl) voice - - 4.65s 151.9M
3.12 alpine (musl) openai-agents - - 4.82s 76.6M
3.12 slim (glibc) redis - - 4.75s 80M
3.12 slim (glibc) voice - - 4.88s 146M
3.12 slim (glibc) openai-agents - - 4.80s 75M
3.13 alpine (musl) redis - - 4.45s 80.7M
3.13 alpine (musl) voice - - 4.65s 151.4M
3.13 alpine (musl) openai-agents - - 4.48s 76.4M
3.13 slim (glibc) redis - - 4.48s 79M
3.13 slim (glibc) voice - - 4.43s 145M
3.13 slim (glibc) openai-agents - - 4.49s 75M
3.9 alpine (musl) redis - - - -
3.9 alpine (musl) voice - - - -
3.9 alpine (musl) openai-agents - - - -
3.9 slim (glibc) redis - - - -
3.9 slim (glibc) voice - - - -
3.9 slim (glibc) openai-agents - - - -

Imports

Quickstart verified last tested: 2026-05-12

Minimal single-agent run

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)
last verified Tue May 12
next check Sat Mar 28