# OpenAI Agents SDK (Python): features, protocols, quickstart

## TL;DR

The OpenAI Agents SDK is OpenAI's MIT-licensed Python library for agent workflows built from a few primitives: agents with tools, handoffs, guardrails, sessions and tracing. It works with OpenAI's Responses and Chat Completions APIs and other providers. It suits Python developers who want a thin, code-first layer, especially on OpenAI models.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python |
| License | MIT |
| Pricing model | [Open source, free](https://developers.openai.com/api/docs/pricing) |
| Orchestration pattern | Handoff |
| GitHub stars | 29,790 (as of 2026-10-01) |
| GitHub forks | 4,841 |
| Last push | 2026-10-01 |
| Latest release | v0.22.3 |
| Repository | [openai/openai-agents-python](https://github.com/openai/openai-agents-python) |
| Website | [openai.github.io](https://openai.github.io/openai-agents-python/) |
| Documentation | [openai.github.io](https://openai.github.io/openai-agents-python/) |
| Last verified | 2026-09-30 |

## Key features

- `Agent`: a model plus instructions, tools, guardrails and handoffs, run by a `Runner` loop until it produces final output. ([source](https://openai.github.io/openai-agents-python/agents/))
- Handoffs: a triage agent passes the conversation to a specialist, which becomes the active agent; input filters control what history moves over. ([source](https://openai.github.io/openai-agents-python/handoffs/))
- Agents as tools: a manager agent calls specialists through `Agent.as_tool()` and keeps ownership of the answer. ([source](https://openai.github.io/openai-agents-python/multi_agent/))
- Input and output guardrails that run alongside the agent and can stop a run when a check trips. ([source](https://openai.github.io/openai-agents-python/guardrails/))
- Sessions that store conversation history across runs, with SQLite, Redis, SQLAlchemy and OpenAI Conversations backends. ([source](https://openai.github.io/openai-agents-python/sessions/))
- Built-in tracing of model calls, tools and handoffs, sent to the OpenAI traces dashboard or to custom processors. ([source](https://openai.github.io/openai-agents-python/tracing/))
- MCP support over stdio, SSE and Streamable HTTP, plus hosted MCP tools executed by the Responses API. ([source](https://openai.github.io/openai-agents-python/mcp/))
- Sandbox agents that work inside a container or local workspace for longer file and shell tasks. ([source](https://openai.github.io/openai-agents-python/sandbox_agents/))

## Architecture and orchestration pattern

Pattern: Handoff.

The basic unit is an `Agent`: a model with instructions, tools, guardrails and a list of agents it may hand off to. `Runner.run()` (or `run_sync` / `run_streamed`) drives the loop: call the model, execute tool calls, follow handoffs, and stop when an agent produces final output.

The docs describe two main multi-agent patterns. With handoffs, a triage agent routes the conversation to a specialist, and that specialist takes over for the rest of the turn. With agents as tools, a manager agent calls specialists via `Agent.as_tool()` and composes their results itself. The two can be combined, and flows can also be orchestrated in plain Python by chaining runs or running agents in parallel.

Runs hold no memory by default. Sessions persist conversation history client-side (SQLite, Redis, SQLAlchemy and others), or the app can use OpenAI's server-managed continuation (`previous_response_id`, `conversation_id`) instead. A paused run can be serialized as `RunState` and resumed later. Tracing records each model call, tool call and handoff as spans.

### Human in the loop

Tools declare `needs_approval=True`, or pass an async function that decides per call. This is available on function tools, `Agent.as_tool`, `ShellTool` and `ApplyPatchTool`; local MCP servers take `require_approval` and hosted MCP tools a `require_approval` tool config. When approval is needed, the run stops and the result lists pending approvals as interruptions. The application approves or rejects each item on the `RunState`, which can be serialized and stored, and then resumes the original run. Approvals raised inside handoffs or nested agent tools surface on the outer run. Some tool types also accept programmatic approval callbacks so the run continues without pausing.

### Harnesses it can drive

- Codex ([evidence](https://openai.github.io/openai-agents-python/tools/))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://openai.github.io/openai-agents-python/mcp/) | Client: `MCPServerStdio`, `MCPServerSse` and `MCPServerStreamableHttp` connect agents to MCP servers, and `HostedMCPTool` lets the Responses API call a public MCP server. |
| A2A | No (checked 2026-09-30) | [link](https://github.com/openai/openai-agents-python/issues/472#issuecomment-5192125355) | A maintainer comment on issue #472 (2026-08-05) states OpenAI does not plan to add an SDK-owned A2A abstraction and shows wiring the separate `a2a-sdk` by hand instead. |
| AG-UI | Unknown (checked 2026-09-30) | — | No AG-UI mention in the SDK docs or repo code search; the AG-UI README lists 'OpenAI Agent SDK' under community integrations with status 'In Progress'. |

## Best for

- Customer-facing assistants that route requests from a triage agent to specialist agents ([shortlist](https://multiagentguide.top/best/customer-support.md))
- Delegating bounded repository tasks to the Codex CLI from inside an agent run (experimental) ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Tool calls that need human approval with pause and resume across processes ([shortlist](https://multiagentguide.top/best/enterprise-governance.md))
- Python teams already on the OpenAI Responses API who want tracing without extra setup

## Not for

- Systems that need built-in A2A interoperability; maintainers have said an SDK-owned A2A layer is not planned
- Teams that need API stability guarantees; the SDK is still on 0.Y versions where minor releases can break interfaces
- Browser-based WebRTC voice sessions; the Python SDK's realtime transport covers server-side WebSocket and SIP only

## Quickstart

```sh
pip install openai-agents
```

Install verified 2026-09-30 (uv venv, Python 3.12.13, macOS arm64: `uv pip install openai-agents` ok, `from agents import Agent, Runner` ok, openai-agents 0.22.3. Packages came from the mirrors.aliyun.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```python
from agents import Agent, Runner

billing = Agent(name="Billing agent",
                instructions="Answer billing questions in two sentences.")
tech = Agent(name="Tech support agent",
             instructions="Answer technical questions step by step.")
triage = Agent(
    name="Triage agent",
    instructions="Decide who should answer and hand off to that agent.",
    handoffs=[billing, tech],
)

# needs OPENAI_API_KEY in the environment
result = Runner.run_sync(triage, "I was charged twice this month.")
print(result.last_agent.name)  # the specialist that answered
print(result.final_output)
```

### Common pitfalls

- Python 3.10 or newer is required.
- Set `OPENAI_API_KEY` before running; other providers need the model adapters described on the models page.
- Voice and Redis sessions are optional extras: `openai-agents[voice]`, `openai-agents[redis]`.
- Versions follow 0.Y.Z: a minor bump (for example 0.21 to 0.22) may contain breaking changes, so pin the minor version.
- Tracing is on by default; set `OPENAI_AGENTS_DISABLE_TRACING=1` to turn it off. It is not available to organizations under Zero Data Retention.
- A session cannot be combined with `previous_response_id` or `conversation_id` in the same run.

Official quickstart: https://openai.github.io/openai-agents-python/quickstart/

## Pros

- Few primitives to learn: agents, tools, handoffs, guardrails, sessions and tracing. ([source](https://github.com/openai/openai-agents-python/blob/main/README.md))
- Not tied to OpenAI models: the README states support for the Responses and Chat Completions APIs and 100+ other LLMs. ([source](https://github.com/openai/openai-agents-python/blob/main/README.md))
- Approvals work across handoffs and nested agent tools, and paused runs can be serialized and resumed. ([source](https://openai.github.io/openai-agents-python/human_in_the_loop/))
- Tracing is built in and can also feed third-party processors. ([source](https://openai.github.io/openai-agents-python/tracing/))
- Covers all common MCP transports plus hosted MCP tools. ([source](https://openai.github.io/openai-agents-python/mcp/))

## Cons

- Maintainers stated in 2026 that there are no plans for an SDK-owned A2A abstraction. ([source](https://github.com/openai/openai-agents-python/issues/472#issuecomment-5192125355))
- Still versioned 0.Y.Z; minor releases may break public interfaces, and the changelog lists such changes. ([source](https://openai.github.io/openai-agents-python/release/))
- Tracing is enabled by default and is unavailable to organizations under OpenAI's Zero Data Retention policy. ([source](https://openai.github.io/openai-agents-python/tracing/))
- The Codex tool that drives the Codex CLI is marked experimental and may change. ([source](https://openai.github.io/openai-agents-python/tools/))
- Pull requests are accepted only from repository collaborators. ([source](https://github.com/openai/openai-agents-python/blob/main/README.md))

## Alternatives

- [OpenAI Agents SDK (JavaScript/TypeScript)](https://multiagentguide.top/tools/openai-agents-js.md)
- [Pydantic AI](https://multiagentguide.top/tools/pydantic-ai.md) ([OpenAI Agents SDK (Python) vs Pydantic AI](https://multiagentguide.top/compare/pydantic-ai-vs-openai-agents-sdk.md))
- [Google ADK (Python)](https://multiagentguide.top/tools/google-adk.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md) ([OpenAI Agents SDK (Python) vs LangGraph](https://multiagentguide.top/compare/openai-agents-sdk-vs-langgraph.md))
- [Microsoft Agent Framework](https://multiagentguide.top/tools/microsoft-agent-framework.md)

## FAQ

### Does the OpenAI Agents SDK support MCP?

Yes, as a client. Agents connect to MCP servers over stdio, SSE or Streamable HTTP, and `HostedMCPTool` lets OpenAI's Responses API call a public MCP server directly.

### Does it support A2A?

No. A maintainer comment on issue #472 in August 2026 said OpenAI does not plan an SDK-owned A2A abstraction and showed how to wire the separate `a2a-sdk` manually.

### Is it free?

The SDK is MIT-licensed. Model calls and hosted tools on OpenAI's API are billed under OpenAI API pricing; other providers are billed by those providers.

### Can I use non-OpenAI models?

Yes. The README says the SDK is provider-agnostic, and the models page covers non-OpenAI providers through adapters such as any-llm and LiteLLM.

### What is the difference between handoffs and agents as tools?

A handoff makes the specialist the active agent for the rest of the turn. With agents as tools, a manager agent calls the specialist and keeps control of the final answer.

## Sources

- [OpenAI Agents SDK (Python) GitHub repository](https://github.com/openai/openai-agents-python)
- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-python/)
- [OpenAI Agents SDK README](https://github.com/openai/openai-agents-python/blob/main/README.md)
- [Quickstart (Agents SDK docs)](https://openai.github.io/openai-agents-python/quickstart/)
- [Agents (Agents SDK docs)](https://openai.github.io/openai-agents-python/agents/)
- [Handoffs (Agents SDK docs)](https://openai.github.io/openai-agents-python/handoffs/)
- [Agent orchestration (Agents SDK docs)](https://openai.github.io/openai-agents-python/multi_agent/)
- [Guardrails (Agents SDK docs)](https://openai.github.io/openai-agents-python/guardrails/)
- [Sessions (Agents SDK docs)](https://openai.github.io/openai-agents-python/sessions/)
- [Tracing (Agents SDK docs)](https://openai.github.io/openai-agents-python/tracing/)
- [Model context protocol (Agents SDK docs)](https://openai.github.io/openai-agents-python/mcp/)
- [Human-in-the-loop (Agents SDK docs)](https://openai.github.io/openai-agents-python/human_in_the_loop/)
- [Tools, including the experimental Codex tool (Agents SDK docs)](https://openai.github.io/openai-agents-python/tools/)
- [Models and providers (Agents SDK docs)](https://openai.github.io/openai-agents-python/models/)
- [Release process and breaking-change changelog (Agents SDK docs)](https://openai.github.io/openai-agents-python/release/)
- [Sandbox agents (Agents SDK docs)](https://openai.github.io/openai-agents-python/sandbox_agents/)
- [Maintainer comment on A2A support, issue #472](https://github.com/openai/openai-agents-python/issues/472#issuecomment-5192125355)
- [AG-UI README, supported integrations](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md)
- [OpenAI API pricing](https://developers.openai.com/api/docs/pricing)
- [OpenAI Agents SDK for JavaScript/TypeScript](https://github.com/openai/openai-agents-js)
- [Realtime transport (Agents SDK docs)](https://openai.github.io/openai-agents-python/realtime/transport/)

## Unknown fields

protocols.agui: searched the SDK docs (llms.txt index and pages) and GitHub code search for 'ag-ui' / 'ag_ui' with no results; the only reference is the AG-UI README, which lists the OpenAI Agent SDK as a community integration marked 'In Progress'.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/openai-agents-sdk