Registry / llm-agents / openai-agents

openai-agents

JSON →

library0.22.0pypypi✓ verified 27d ago

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

llm-agents ai-ml workflow

pip install openai-agents

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENAI-AGENTS

openai-agents

llm-agentspythonv0.22.0

Install

9.5s avg

Import

7948ms

Disk

106MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.22.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 6.611s · 94.9MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 9.5s · import 6.105s · 99MB

106MB installed

● package 106MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Agent

✓ from agents import Agent

Core agent primitive

Runner

✓ from agents import Runner

Synchronous and async run entrypoint

handoffs

✓ Agent(handoffs=[other_agent])

Pass agent instances directly, not strings

RealtimeAgent

✓ from agents.realtime import RealtimeAgent

Voice agent — beta, expect breaking changes

AgentBase

✓ from agents import AgentBase

✗ Agent

MCPServer.list_tools() and similar now take AgentBase not Agent — typing change, objects are still Agent instances

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)

Debug

Known issues

breakingopenai v1.x is no longer supported. Must use openai>=2.0.0.

fix

pip install 'openai>=2.0.0' before installing openai-agents

affects: <0.9.0 compatible with openai v1

breakingPython 3.9 support dropped. Minimum runtime is Python 3.10.

fix

Upgrade to Python 3.10+

affects: recent major

deprecatedSwarm 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.

affects: all

gotchaMCP 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

affects: recent

gotchaAgent.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

affects: recent

gotchaRealtimeAgent 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.

affects: all realtime

gotchaWebSocket 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

affects: 0.10.x+

breakingOpenAI 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.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'agents'

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.

AttributeError: module 'openai' has no attribute 'ChatCompletion'

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(...)`.

AttributeError: module 'openai' has no attribute 'OpenAI'

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`.

The model did not produce a final response!

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.

Upgrade

Version history

0.22.0latest on PyPI · released Aug 19, 2026

Audit

Dependencies

openai>=2.0.0requiredopenai v1.x no longer supported as of recent SDK versions

openai-agents[voice]optionalRequired for RealtimeAgent / voice pipeline support

openai-agents[redis]optionalRequired for Redis-backed session persistence

Agent activity

63 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/openai/openai-agents-python ↗

packagehttps://pypi.org/project/openai-agents/ ↗

homepagehttps://openai.github.io/openai-agents-python/ ↗