OpenAI ships Agents API with a managed Codex harness

OpenAI's developer documentation describes a new Agents API that gives an application managed access to the company's Codex agent harness. Instead of building session handling, sandboxing and context management from scratch, a caller creates a session, and OpenAI takes care of orchestration, context compaction and recovery while the application supplies the tools and picks the execution environment. Inside that environment, an agent can execute code, edit files, connect to MCP servers and produce artifacts.

The API is organized around four concepts. An Agent is the model, instructions, tools and MCP servers available to it. An Environment is the optional sandbox or computer where the agent reads files, loads skills and runs commands. A Session is a durable, running instance of an agent that works on tasks and responds to input over time. Events and items are the inputs sent to the agent and the output it produces during a session.

A session runs through four steps in the quickstart: create it by configuring the agent, which prompts OpenAI to provision its environment; give it a task, which starts a turn of work once the environment is ready; follow its progress by streaming output or listening for webhooks; then continue the same session with another task, or steer the agent while it works. With an OpenAI-hosted session, the calling application only sends input and receives events, since OpenAI runs the agent and provisions and manages the sandbox itself. Developers can choose a self-hosted environment instead, pointing the agent at a workspace directory and a folder of skills it can load.

The quickstart's own code sample, shown in six SDKs (Python, JavaScript, Go, Java, Ruby and curl), configures an agent with programmatic tool calling, an MCP connection to OpenAI's own documentation server, and web search, then turns on multi-agent delegation, setting the sample's concurrency cap to four subagents; it names the agent's model gpt-6-astra only as a placeholder in the example, not as an announced model. The documentation also names one packaged example, a document reviewer that reviews documents using policy skills and specialist agents.

Session state persists across turns, so work can continue without rebuilding the conversation context, and both sessions and any artifacts they publish can be deleted once they are no longer needed. Billing follows three separate meters: model usage at the selected model's own API rate, OpenAI's own tools at their standard rates, and OpenAI-hosted sandbox time at standard container rates. The documentation does not publish any of those rates as dollar figures.

The Agents API currently supports data residency only in the United States and does not support Zero Data Retention; choosing a self-hosted sandbox does not change that. The page never applies a formal availability label such as beta or general availability, but the SDK calls reach the feature through a beta namespace, client.beta.agents.sessions, and the curl example sends an OpenAI-Beta: agents=v1 header, the only signs that the interface may still be settling.

Key facts

The Agents API gives applications managed access to OpenAI's Codex harness: sessions run in a sandbox where an agent can execute code, edit files, call MCP servers and tools, and produce artifacts, while OpenAI handles orchestration, context compaction and recovery.
The API is built on four concepts: an Agent (model, instructions, tools and MCP servers), an Environment (the sandbox or computer), a Session (the durable running instance), and Events and items (a turn's inputs and outputs).
The quickstart's example configuration, shown in six SDKs, turns on multi-agent delegation with a concurrency cap of four subagents and connects the agent to an MCP server and web search.
Sessions persist state across turns, can be resumed or steered mid-turn, and can be deleted along with any published artifacts; usage is billed at the selected model's own API rate plus standard rates for OpenAI's tools and hosted sandbox time, with no dollar figures published.
Data residency is limited to the United States and the API does not support Zero Data Retention even with a self-hosted sandbox; the only sign the interface may still be beta is the SDK's beta namespace and an OpenAI-Beta: agents=v1 header.

Why it matters

The Agents API turns OpenAI's own Codex agent harness, the session handling, sandboxing, orchestration, context compaction and recovery it uses to run Codex, into a general building block that any application can call through an API. Previously, a team wanting a long-running, resumable agent had to build that session and sandbox layer itself; this API packages it as a managed service, with multi-agent delegation and MCP tool connections offered as configuration rather than custom infrastructure.

Who it affects

Developers building agentic products, such as research assistants, coding agents or document-review tools, that need sessions to persist across multiple turns rather than restarting from scratch on every call. The documentation's own named example, a document reviewer that uses policy skills and specialist agents, is aimed at that kind of workflow. Teams can pick an OpenAI-hosted sandbox and let OpenAI provision and manage it, or a self-hosted environment where they control the workspace directory and the skills the agent can load, so the choice also affects infrastructure and operations teams deciding where an agent's code actually runs.

How to use it

A session starts with a create call that configures the agent's model, instructions, tools and MCP servers, and its environment; OpenAI then provisions that environment. Sending the session a task starts a turn once the environment is ready, and the caller can stream output or register webhooks to learn when the agent finishes or needs input, then send further tasks to the same session or steer it while it works. The quickstart's sample configuration, given in Python, JavaScript, Go, Java, Ruby and curl, adds programmatic tool calling, an MCP connection to OpenAI's own documentation server, and web search, then sets multi_agent.enabled to true with the sample's concurrency cap at four subagents; it uses gpt-6-astra only as a placeholder model name in the example, not as an announced model. Model usage is billed at that model's own API rate, OpenAI's tools at their standard rates, and OpenAI-hosted sandbox time at standard container rates, though the documentation does not publish any of those rates in dollars. Sessions keep their state across turns, can be resumed later, and can be deleted along with any artifacts they published once they are no longer needed.

How solid is it

The source is OpenAI's own developer documentation for the product, not a blog post or a press release, so the description of what the API does is first-party and authoritative. It reads as reference documentation rather than a dated launch announcement: no date appears anywhere for when the Agents API was introduced or became available, and the text never formally labels its availability stage. The only hint that it may still be a beta product sits in the code samples themselves: the SDKs reach it through a client.beta.agents.sessions namespace, and the curl example sends an OpenAI-Beta: agents=v1 header. The page also gives no dollar pricing figures, named customers, usage numbers or comparison to other vendors' agent APIs, so none of that can be read from this page alone.

Risks and caveats

Data residency currently covers only the United States, and the API does not support Zero Data Retention; the documentation is explicit that picking a self-hosted sandbox does not change that, which rules the product out for workloads that need ZDR or non-US residency regardless of where the sandbox itself runs. Interfaces reached through a beta SDK namespace can still change before a stable release. Cost is also hard to predict ahead of time: usage is metered separately for model tokens, tool calls and sandbox container time, and the documentation states only that each follows its own standard rate without giving figures.

“The Agents API gives your application access to the Codex harness through an OpenAI-managed API.”

— OpenAI, Agents API documentation