# OpenAI Agents API: features, protocols, quickstart

## TL;DR

The OpenAI Agents API is a beta, OpenAI-managed API, under the beta.agents namespace, that runs the Codex harness for your application. OpenAI keeps sessions, context compaction and recovery; you supply tools and choose a sandbox. A session can delegate to parallel subagents. It suits developers building long-running coding or research agents without hosting the agent loop.

## Key facts

| Field | Value |
| --- | --- |
| Type | Platform |
| Languages / SDKs | Python, JavaScript, Go, Java, Ruby |
| License | Proprietary |
| Pricing model | [Usage-based](https://developers.openai.com/api/docs/pricing) |
| Orchestration pattern | Supervisor |
| Repository | No public repository (closed source) |
| Website | [developers.openai.com](https://developers.openai.com/api/docs/guides/agents-api/overview) |
| Documentation | [developers.openai.com](https://developers.openai.com/api/docs/guides/agents-api/overview) |
| Last verified | 2026-09-30 |

## Key features

- OpenAI runs a managed Codex harness and manages sessions, orchestration, context compaction and recovery, while the application provides tools and picks the execution environment. ([source](https://developers.openai.com/api/docs/guides/agents-api/overview))
- Multi-agent mode lets the main agent create, message, wait for and interrupt subagents that each have their own context and run in parallel; `max_concurrent_subagents` defaults to 6. ([source](https://developers.openai.com/api/docs/guides/agents-api/multi-agent))
- Environments are OpenAI-hosted sandboxes, self-hosted sandboxes (laptop, Docker, AWS Lambda and several sandbox providers) or none; a coordinator and its subagents share one environment's filesystem. ([source](https://developers.openai.com/api/docs/guides/agents-api/architecture))
- Sessions are durable: you can stream events or use webhooks, send another task to the same session, or send a message during a turn to steer it. ([source](https://developers.openai.com/api/docs/guides/agents-api/sessions))
- MCP servers can be connected from OpenAI (HTTP) or from the session's environment (HTTP or stdio), and subagents inherit the configured MCP tools. ([source](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp))
- The session event stream reports subagent creation and coordination items, and saved turns record which subagent ran each command. ([source](https://developers.openai.com/api/docs/guides/agents-api/multi-agent))
- The docs position it against the Agents SDK and Responses API: the Agents API is for long-running tasks where OpenAI manages the agent and its saved progress. ([source](https://developers.openai.com/api/docs/guides/agents))

## Architecture and orchestration pattern

Pattern: Supervisor.

The Agents API splits work into a harness, an environment and an application server. The harness is a hosted Codex instance that runs the model and tool loop and holds the session. The environment is where commands run and files live: an OpenAI-hosted sandbox, your own compute, or none. Your application server creates sessions, sends tasks, receives events and answers any function-tool calls.

For multiple agents, a session created with `multi_agent.enabled` gets tools to create, message, wait for and interrupt subagents. The main agent acts as coordinator: it hands independent tasks to subagents, waits, and combines the results. Subagents have their own context, run in parallel up to a configurable limit, and inherit the configured MCP tools and web search. They share the coordinator's environment rather than getting their own, and they do not support function tools. The docs advise keeping short or dependent steps in the main agent and note that subagents editing the same files must coordinate.

OpenAI stores session configuration, turns and items, so work can be resumed across turns and after disconnects; sessions and published artifacts can be deleted. Events, tracing (exportable as OTLP JSON) and usage records are available for observation. The API is in beta and requires the `OpenAI-Beta: agents=v1` header, which the official SDKs add.

### Human in the loop

A person or application can steer a running turn by sending another message to the session, and a session can enter a `requires_action` state where your application must run a function call or connect an environment before work continues. For computer use, the browser asks for approval before accessing each new website origin, and your application submits approve, deny or cancel; the docs say this does not enforce confirmation before individual actions. The overview lists an incident-response cookbook app that requests approval for recovery actions. A generic approval gate for every tool call is not described in the pages read.

### Harnesses it can drive

- Codex ([evidence](https://developers.openai.com/api/docs/guides/agents-api/overview))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp) | Client: the Agents API discovers tools from MCP servers reached over HTTP (from OpenAI or from the environment) or stdio (in the environment) and calls them; no MCP server of its own is described. |
| A2A | Unknown (checked 2026-09-30) | — | No mention of A2A or Agent2Agent in the OpenAI API docs export (developers.openai.com/api/docs/llms-full.txt, about 5 MB) or the Agents API pages read. |
| AG-UI | Unknown (checked 2026-09-30) | — | No mention of AG-UI in the same docs export, and the Agents API is not listed in the AG-UI protocol README. |

## Best for

- Applications that need a long-running coding or research agent with durable sessions and a sandbox, without hosting the agent loop themselves. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Fan-out tasks that split naturally into independent subtasks, such as comparing documents or investigating separate failure causes, with results combined by a coordinator. ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Products that want to bring their own compute for the agent's commands (self-hosted sandbox) while OpenAI manages the session and model loop.

## Not for

- Zero Data Retention needs: the docs say the Agents API does not support ZDR, and data residency is United States only for now.
- Teams that want to control the agent loop, storage and approvals in their own code; the docs point them to the Agents SDK instead.
- Stable, non-beta interfaces: the API sits under the `beta` namespace and needs a beta header.

## Quickstart

```sh
pip install --upgrade openai
```

Install verified 2026-09-30 (uv venv, Python 3.12.13, macOS arm64: `uv pip install --upgrade openai` ok, `from openai import OpenAI; assert hasattr(OpenAI(api_key='not-a-key').beta, 'agents'), 'client.beta.agents missing'` ok, openai 3.22.0. The check confirms the installed SDK exposes `client.beta.agents`; no API request was made. 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 openai import OpenAI

# OPENAI_API_KEY needs api.agents.read, api.agents.write and api.responses.write
client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Give each release to its own subagent, then combine the findings.",
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 2},
    },
    environment={"type": "none"},
    input="Release A: search supports date filters. Release B: export returns a URL.",
    stream=True,
) as events:
    for event in events:
        print(event.to_json(indent=None))
```

### Common pitfalls

- Requests need the `OpenAI-Beta: agents=v1` header; the OpenAI SDKs add it, cURL calls must include it. SDK calls live under `client.beta.agents`.
- The API key needs `api.agents.read` and `api.agents.write` for sessions plus `api.responses.write` for model inference, and must stay outside the agent's sandbox.
- With `environment.type: "none"`, there are no built-in Bash or apply-patch tools or workspace files, and the first input goes in the create request.
- Subagents do not support function tools, and coordinator and subagents share one filesystem, so parallel edits to the same files must be coordinated.
- Data residency is United States only, and Zero Data Retention is not supported, even with a self-hosted sandbox.
- Model names change; the docs' examples use `gpt-6-astra`, so check the current models page before copying.

Official quickstart: https://developers.openai.com/api/docs/guides/agents-api/quickstart

## Pros

- OpenAI manages session state, context compaction and recovery, so the application only sends input and handles events. ([source](https://developers.openai.com/api/docs/guides/agents-api/overview))
- Built-in delegation with a configurable concurrency limit, and delegation activity is visible in the event stream and saved turns. ([source](https://developers.openai.com/api/docs/guides/agents-api/multi-agent))
- Flexible execution: OpenAI-hosted sandbox, your own compute, or no environment at all. ([source](https://developers.openai.com/api/docs/guides/agents-api/architecture))
- Official SDK examples in Python, JavaScript, Go, Java, Ruby and cURL. ([source](https://developers.openai.com/api/docs/guides/agents-api/overview))
- Usage is billed at the selected model's API rates plus standard rates for OpenAI tools and hosted containers, with no separate platform fee stated. ([source](https://developers.openai.com/api/docs/guides/agents-api/overview))

## Cons

- The API is under the `beta` namespace and requires the `OpenAI-Beta: agents=v1` header, so its shapes may still change. ([source](https://developers.openai.com/api/docs/guides/agents-api/quickstart))
- Does not support Zero Data Retention and supports data residency only in the United States; OpenAI retains session state. ([source](https://developers.openai.com/api/docs/guides/agents-api/overview))
- Subagents share the coordinator's environment, cannot use function tools, and the stream does not give a full conversation transcript of their coordination. ([source](https://developers.openai.com/api/docs/guides/agents-api/multi-agent))
- Locked to the managed Codex harness and OpenAI models; the docs send teams who want to own the agent loop to the Agents SDK. ([source](https://developers.openai.com/api/docs/guides/agents))
- Computer-use approvals are per website origin only and do not enforce confirmation before individual actions. ([source](https://developers.openai.com/api/docs/guides/agents-api/tools/computer-use))

## Alternatives

- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [Codex CLI](https://multiagentguide.top/tools/codex.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md) ([OpenAI Agents API vs LangGraph](https://multiagentguide.top/compare/openai-agents-api-vs-langgraph.md))
- [Google ADK (Python)](https://multiagentguide.top/tools/google-adk.md)
- [Strands Agents](https://multiagentguide.top/tools/strands-agents.md)

## FAQ

### Does the OpenAI Agents API support MCP?

Yes, as a client. Agents can connect to MCP servers over HTTP from OpenAI or from the session's environment, or start stdio servers in the environment. Subagents inherit the configured MCP tools.

### How does it differ from the OpenAI Agents SDK?

The Agents API runs a managed Codex harness on OpenAI's side and saves session state for you. The Agents SDK runs inside your application, where you control storage, approvals and the agent loop with handoffs.

### Can it run several agents at once?

Yes. With multi_agent enabled, the main agent delegates to subagents that run in parallel, up to max_concurrent_subagents (default 6). They share one environment.

### What does it cost?

The overview says model usage is billed at the model's API rates and OpenAI-hosted sandboxes at standard container rates. See the API pricing page for current numbers; none are copied here.

## Sources

- [OpenAI Agents API overview](https://developers.openai.com/api/docs/guides/agents-api/overview)
- [Agents API quickstart](https://developers.openai.com/api/docs/guides/agents-api/quickstart)
- [Agents API: Multi-agent](https://developers.openai.com/api/docs/guides/agents-api/multi-agent)
- [Agents API: Architecture](https://developers.openai.com/api/docs/guides/agents-api/architecture)
- [Agents API: Run and continue sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions)
- [Agents API: MCP connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp)
- [Agents API: Computer use](https://developers.openai.com/api/docs/guides/agents-api/tools/computer-use)
- [OpenAI agents: compare runtimes](https://developers.openai.com/api/docs/guides/agents)
- [OpenAI API pricing](https://developers.openai.com/api/docs/pricing)
- [OpenAI API docs index (llms.txt)](https://developers.openai.com/api/docs/llms.txt)

## Unknown fields

A2A and AG-UI: searched developers.openai.com/api/docs/llms-full.txt (about 5 MB) for A2A, Agent2Agent, agent-to-agent and AG-UI and found nothing; the Agents API is not listed in the AG-UI README. Closed-source, so no repository search. Pricing: the overview points to the general API pricing page; no Agents-specific prices were copied, so pricing_model usage-based rests on the overview's billing paragraph. The model name gpt-6-astra comes from the docs' examples and was not checked against a models page. HITL: a general approval gate for every tool call was not found in the pages read.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/openai-agents-api