OpenAI Agents API explained
OpenAI describes the Agents API as a way to build durable cloud agents on a managed Codex harness. This guide summarises OpenAI's overview, its beta FAQ and the 10 September 2026 announcement, which puts it in public beta. It is a developer product, not a ready-made assistant. We have not used it, and the FAQ says features are rolling out gradually, so your account may not have everything described.
The four concepts
| Concept | What OpenAI says it is |
|---|---|
| Agent | The model, instructions, tools and MCP servers available to the agent. |
| Environment | An optional sandbox or computer where the agent accesses files, loads skills and runs commands. |
| Session | A durable instance of an agent that works on tasks and responds to input. |
| Events and items | The inputs sent to an agent and the output it produces. |
OpenAI says it manages sessions, orchestration, context compaction and recovery, while your application supplies the tools and chooses the execution environment. The documented harness can run commands and code, apply skills, connect to data through tools or MCP, be steered mid-task, summarise earlier work, delegate to subagents and resume a session.
Environment options
- No environment: the agent answers questions or calls external tools, with no shell or workspace files.
- OpenAI-hosted sandbox: OpenAI provisions and manages the sandbox for scripts and files.
- Self-hosted sandbox: for your own infrastructure or private network. Your application manages its lifecycle.
Billing, as documented
Model requests are billed at the selected model's API rates. OpenAI tools use their standard rates and OpenAI-hosted sandboxes use standard container rates. The pages do not give a separate Agents API fee or any dollar figures, so we list none; see OpenAI's API pricing page. Costs depend on how many turns, tools and subagents a session uses, which the documentation does not estimate.
Data and access limits OpenAI states
- Sessions keep state so work can continue. You can delete sessions and published artifacts, and OpenAI advises saving needed files first.
- Data residency is supported in the United States only.
- Zero Data Retention is not supported, including with a self-hosted sandbox.
- Access needs an application API key with
api.agents.readandapi.agents.write, plusapi.responses.writefor model requests, and theOpenAI-Beta: agents=v1header (OpenAI SDKs add it). - OpenAI advises keeping the API key outside the sandbox.
- If an event stream disconnects, retrieve the saved session before resubmitting. A finished turn does not prove every tool call succeeded, and an idle session alone does not show the task finished.
Who this fits
Teams that want to embed a coding or workflow agent in their own product and are comfortable with API keys, webhooks and review of logs. People who want a finished assistant should look at the agent directory instead. For build-versus-buy thinking see build or buy an AI agent, and for access questions to ask any vendor see the ChatGPT workspace agents guide and the privacy checklist.
Sources: Agents API overview, Agents API (beta) FAQ, Introducing the Agents API. Spot a change? Tell us.