{"id":53,"library":"openai-agents","title":"OpenAI Agents SDK","description":"Lightweight multi-agent orchestration framework by OpenAI. Production successor to Swarm. Provider-agnostic.","status":"active","version":"0.10.1","language":"python","source_language":"en","source_url":"https://openai.github.io/openai-agents-python/","tags":["agents","multi-agent","orchestration","openai","handoffs","guardrails","tracing","mcp","realtime"],"install":[{"cmd":"pip install openai-agents","lang":"bash","label":"pip"},{"cmd":"uv add openai-agents","lang":"bash","label":"uv"},{"cmd":"pip install 'openai-agents[voice]'","lang":"bash","label":"pip (voice)"},{"cmd":"pip install 'openai-agents[redis]'","lang":"bash","label":"pip (redis sessions)"}],"dependencies":[{"reason":"openai v1.x no longer supported as of recent SDK versions","package":"openai>=2.0.0","optional":false},{"reason":"Required for RealtimeAgent / voice pipeline support","package":"openai-agents[voice]","optional":true},{"reason":"Required for Redis-backed session persistence","package":"openai-agents[redis]","optional":true}],"imports":[{"note":"Core agent primitive","symbol":"Agent","correct":"from agents import Agent"},{"note":"Synchronous and async run entrypoint","symbol":"Runner","correct":"from agents import Runner"},{"note":"Pass agent instances directly, not strings","symbol":"handoffs","correct":"Agent(handoffs=[other_agent])"},{"note":"Voice agent — beta, expect breaking changes","symbol":"RealtimeAgent","correct":"from agents.realtime import RealtimeAgent"},{"note":"MCPServer.list_tools() and similar now take AgentBase not Agent — typing change, objects are still Agent instances","wrong":"Agent","symbol":"AgentBase","correct":"from agents import AgentBase"}],"quickstart":{"code":"from agents import Agent, Runner\n\nagent = Agent(name=\"Assistant\", instructions=\"You are a helpful assistant\")\nresult = Runner.run_sync(agent, \"Write a haiku about recursion in programming.\")\nprint(result.final_output)","lang":"python","description":"Minimal single-agent run"},"warnings":[{"fix":"pip install 'openai>=2.0.0' before installing openai-agents","message":"openai v1.x is no longer supported. Must use openai>=2.0.0.","severity":"breaking","affected_versions":"<0.9.0 compatible with openai v1"},{"fix":"Upgrade to Python 3.10+","message":"Python 3.9 support dropped. Minimum runtime is Python 3.10.","severity":"breaking","affected_versions":"recent major"},{"fix":"Migrate to openai-agents. Primitives are similar but not identical.","message":"Swarm is the deprecated predecessor. Do not use openai/swarm — openai-agents is the production replacement.","severity":"deprecated","affected_versions":"all"},{"fix":"Update type annotations: replace Agent with AgentBase where type errors appear","message":"MCP server methods (list_tools(), etc.) now take AgentBase, not Agent as type hint. Runtime behavior unchanged — objects are still Agent instances.","severity":"gotcha","affected_versions":"recent"},{"fix":"Update type annotations to FunctionTool where needed","message":"Agent.as_tool() return type narrowed from Tool to FunctionTool. May cause type errors if you relied on the broader union.","severity":"gotcha","affected_versions":"recent"},{"fix":"Pin version if using RealtimeAgent in production. Use GA URL format for Azure.","message":"RealtimeAgent is beta. Breaking changes expected. Azure realtime: use GA URL path (wss://.../openai/v1/realtime), not legacy beta path (/openai/realtime?api-version=...).","severity":"gotcha","affected_versions":"all realtime"},{"fix":"No action needed unless you want WebSocket mode explicitly","message":"WebSocket transport for Responses API is opt-in. Default remains HTTP. Must call set_default_openai_responses_transport('websocket') to enable globally.","severity":"gotcha","affected_versions":"0.10.x+"},{"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.","message":"OpenAI client requires an API key. Ensure OPENAI_API_KEY is set in your environment or passed directly to the client.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T06:03:52.373Z","next_check":"2026-03-28T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'agents'"},{"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(...)`.","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`).","error":"AttributeError: module 'openai' has no attribute 'ChatCompletion'"},{"fix":"Upgrade your `openai` package to version 1.0.0 or newer using `pip install --upgrade 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.","error":"AttributeError: module 'openai' has no attribute 'OpenAI'"},{"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.","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.","error":"The model did not produce a final response!"}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":70,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.29,"mem_mb":42.2,"disk_size":"82.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.24,"mem_mb":42.2,"disk_size":"151.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.26,"mem_mb":42.2,"disk_size":"79.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.19,"mem_mb":42.2,"disk_size":"82M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.35,"mem_mb":42.2,"disk_size":"146M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.21,"mem_mb":42.2,"disk_size":"78M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.49,"mem_mb":44.8,"disk_size":"90.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.59,"mem_mb":44.8,"disk_size":"164.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.46,"mem_mb":44.8,"disk_size":"86.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.62,"mem_mb":44.8,"disk_size":"89M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.67,"mem_mb":44.8,"disk_size":"159M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.66,"mem_mb":44.8,"disk_size":"85M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.66,"mem_mb":44.3,"disk_size":"81.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.65,"mem_mb":44.3,"disk_size":"151.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.82,"mem_mb":44.3,"disk_size":"76.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.75,"mem_mb":44.3,"disk_size":"80M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.88,"mem_mb":44.3,"disk_size":"146M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.8,"mem_mb":44.3,"disk_size":"75M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.45,"mem_mb":46,"disk_size":"80.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.65,"mem_mb":46,"disk_size":"151.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.48,"mem_mb":46,"disk_size":"76.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"redis","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.48,"mem_mb":46,"disk_size":"79M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"voice","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.43,"mem_mb":46,"disk_size":"145M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.49,"mem_mb":46,"disk_size":"75M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"redis","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"voice","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"redis","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"voice","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}