OpenAI Agents API

OpenAI Agents API is a developer service for running long-running AI agents with the Codex agent harness managed by OpenAI. OpenAI released it in public beta on September 10, 2026. A caller supplies the model, instructions, tools, task, and execution-environment choice; OpenAI runs the model and tool loop and manages sessions, orchestration, context compaction, and recovery.^[1][3][20]

The product exposes the harness used by OpenAI Codex without requiring an application to operate that harness itself. Its current SDK namespace is client.beta.agents, and raw session creation uses POST /v1/agents/sessions with the beta header OpenAI-Beta: agents=v1.^[1][6] The service is not the same product as the OpenAI Agents SDK, OpenAI Responses API, the former OpenAI Assistants API, ChatGPT Workspace Agents, or Agent Builder.^{[4][22][23][24]}

Key facts

Scroll sideways for more →

Place in OpenAI's agent stack

OpenAI documents three current starting points for developers. The Agents API is for long-running work where OpenAI should run the harness and save progress. The Agents SDK is for applications that want their own process to run the agent loop. The Responses API is the lower-level route for direct model calls or a custom loop.^[4]

Scroll sideways for more →

These resources are not interchangeable. OpenAI specifically notes that an Agents API session, an Agents SDK session, a Responses conversation, and a sandbox have separate lifecycles.^[4]

The Assistants API is also a different interface. OpenAI sunset it on August 26, 2026 and directs existing integrations to the Responses API. The migration guide does not identify the Agents API as an automatic drop-in replacement.^[22]

Workspace Agents are published agents inside ChatGPT workspaces that an organization's external systems can trigger through the Workspace Agents API.^[24] They are governed by ChatGPT workspace access and permissions, rather than being sessions of the managed Codex harness described here.^[24]

Agent Builder is AgentKit's visual canvas for constructing and versioning multi-agent workflows. OpenAI announced on June 3, 2026 that it was winding down Agent Builder and that the product would no longer be available from November 30, 2026 onward. OpenAI recommends the Agents SDK for workflows that should continue as code, or Workspace Agents in ChatGPT for use cases better suited to natural-language prompting.^[23] Agent Builder and the Agents API therefore share agent terminology but are separate products with different runtimes and release paths.

Architecture and responsibility boundary

The system has three main parts.^[5]

Scroll sideways for more →

The separation between harness and environment is central to the product. Choosing a self-hosted environment moves file access, command execution, network policy, and compute lifecycle into infrastructure chosen by the developer. It does not move the harness or session service out of OpenAI.^[5][11]

An agent configuration consists of a model, instructions, tools, and related controls. It can be included directly in a session-creation request or saved as a reusable agent resource and referenced by agent_id. The saved agent holds reusable settings, while each session has its own conversation and work. A session can override selected settings without changing the stored agent, but a supplied object or array replaces the corresponding saved field rather than merging with it. Supplying a new tools array, for example, replaces the saved tool list for that session.^[7]

Sessions, turns, events, and items

A session retains an agent's configuration, conversation, and saved work. A turn is one cycle of work inside that session. Input sent while the session is idle starts a new turn; input sent while a turn is active steers the work already in progress. Turns are asynchronous, so applications follow them through a stream or receive state changes through webhooks.^[3][8]

The event model separates live progress from retained history:

• Events report activity as it happens, including text deltas, tool work, environment state, required actions, and terminal turn outcomes.
• Items are saved messages and tool calls that can be listed later.
• Turns can be listed or retrieved to inspect status, timestamps, usage, errors, and root-agent or subagent attribution.^[9]

Applications should subscribe before sending work if they need the first events. Streams do not replay events missed during a disconnection. OpenAI's recovery procedure is to open a new stream, buffer incoming events, retrieve the saved session and items, reconcile them by item ID, and then continue with live events. Saved items can restore completed work, but not every intermediate event that was missed.^[9]

An idle session is not proof that the last turn succeeded. A client must inspect agent.session.turn.completed, agent.session.turn.failed, or agent.session.turn.cancelled, and then inspect the output. Even turn.completed does not guarantee that every tool call succeeded.^[8] When the session needs an application function result or a self-hosted executor connection, it enters a required-action state until the application supplies that dependency.^[8][13]

Cancellation stops the active turn but preserves the session and its earlier work. A later message can start another turn in the same session.^[8]

Environment options

No environment

environment.type: "none" is sufficient when an agent only needs the model, OpenAI service tools, remote MCP servers, or application functions. This option has no workspace. The built-in Bash and apply-patch tools, local files, and environment-origin MCP servers are unavailable.^[5]

OpenAI-hosted sandbox

environment.type: "openai_hosted" gives the session a Linux workspace at /workspace, with Python, Node.js, and command-line tools. The developer can add packages, setup commands, input files, environment variables, skills, plugins, capability directories, or a reusable environment template. OpenAI provisions and connects the sandbox.^[10]

Network access deserves explicit configuration. Outbound access is enabled by default unless a template supplies another policy. It can be disabled or restricted to an allowlist of 1 through 100 exact host names. Wildcards, protocols, paths, and ports are not valid allowlist entries, and a subdomain or redirect destination requires its own entry.^[10]

Each hosted session has a separate workspace. Files persist across turns while its sandbox exists. Files written under /workspace/outputs are copied into immutable artifacts at turn completion and remain downloadable after the sandbox expires. If activity and keep-alives both stop for an hour, the sandbox can be deleted; the timeout is not configurable. Deleting the session requests sandbox cleanup, while closing an event stream does not cancel the work.^[10]

Self-hosted sandbox

environment.type: "self_hosted" connects the managed harness to compute operated by the developer or a sandbox provider. The developer runs codex exec-server inside that environment. The executor registers with an environment ID and a restricted key, then uses outbound WebSocket connections to receive commands and return results. It can reconnect after a dropped connection.^[11]

The application owns provisioning, reconnection, shutdown, isolation, persistent files, and cleanup. Each session has its own environment ID and needs its own executor. OpenAI publishes provider guides for Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle Cloud Infrastructure, Runloop, and Vercel. These providers host or provision execution compute; they do not replace OpenAI's managed harness.^[1][11]

Tools and context management

The Agents API can combine service tools, application tools, and tools that execute inside a sandbox.^[1][3]

Application functions use the same general function-calling pattern as other OpenAI APIs, but the session flow is asynchronous. The harness emits agent.session.requires_action with pending call arguments. The application runs the function and sends an agent.session.input.tool_result event containing the original turn and call IDs. Attaching a sandbox does not automatically run these functions there. For functions with side effects, OpenAI recommends storing outcomes durably by session, turn, and call ID so recovery does not repeat an action whose first execution may already have succeeded.^[13]

MCP tools can connect in three ways. A service-origin HTTP connection runs from OpenAI and does not require a sandbox. An environment-origin HTTP connection runs from the session environment. A stdio connection launches a process inside that environment. Service-origin credentials can be supplied for one session or drawn from an OpenAI vault; environment-origin credentials remain within the environment and may be readable by its code. allowed_tools limits what an MCP server exposes to the agent, and required: true makes server initialization failure fail the turn.^[14]

Web search must be listed in the agent's tools. Asking for a search in the prompt does not enable it by itself. The documented modes are live (the default), cached, and disabled. Optional settings control the amount of search context, restrict results to as many as 100 domains, and provide a location hint.^[15]

Skills and plugins package reusable instructions and integrations. A hosted environment can receive them in its configuration, while a self-hosted environment can expose capability directories. The same sandbox can then use command-line tools and edit working files.^[3][10]

Two harness features are intended to reduce context overhead. Tool search loads relevant tool definitions only when needed instead of keeping every schema in the active prompt. Programmatic tool calling lets the harness call tools in parallel or in sequence and filter or combine results in code before returning selected data to the model.^[1]

The harness also performs automatic compaction. As a session approaches the selected model's context limit, it summarizes earlier work so the agent can continue across more than one context window. OpenAI does not document a fixed trigger threshold in the reviewed Agents API guides. The documentation treats compaction and saved item history as separate mechanisms.^[1][3][9]

Multi-agent orchestration

Multi-agent support is optional. When agent.multi_agent.enabled is true, the harness gives the coordinator tools to create, message, wait for, and interrupt subagents. Each subagent has its own model context and can work concurrently on an independent assignment; the coordinator is responsible for combining results.^[1][16]

max_concurrent_subagents defaults to 6 and excludes the coordinator. All agents in a session share the same environment and filesystem, so creating a subagent does not create another sandbox or another isolation boundary. Subagents inherit MCP tools, credentials and tool allowlists, web-search settings, files, and command-line tools. They do not support application function tools.^[16]

The event stream reports subagent creation and coordination actions. A completed create or wait action does not necessarily mean the delegated task is complete, and the stream does not expose a full inter-agent conversation transcript. Saved per-subagent turns and items provide the retained history that the API makes available.^[9][16]

Observability

Developers can inspect a session through live events, webhooks, saved turns and items, and the Agents tab in the OpenAI Platform logs. Dashboard traces are enabled by default for new sessions. A trace represents one turn and groups model-generation and tool spans under either the root agent or the subagent that performed them. Traces are constructed after a turn ends, so an answer can arrive before its trace or token counts are ready.^[17][18]

The public beta does not expose tracing configuration or external trace exporters. The usage values on sessions and turns are best-effort records: they can be null, can change when later accounting arrives, and are not a final bill. A null value means unknown usage, not zero usage.^[17][18]

One task can make several model calls, including tool-follow-up generations, retries, and work by subagents. Cost investigation therefore has to include root and subagent turns rather than treating one session as one model request.^[17]

Pricing and availability

OpenAI made the Agents API available to all developers in public beta on September 10, 2026. The company said it would iterate during the beta while working toward general availability, but did not announce a GA date.^[1][20]

OpenAI charges no separate fee for the Agents API itself. Model calls are billed at the selected model's token rates. OpenAI tools use their standard rates, and OpenAI-hosted sandboxes use the current container rates. Third-party MCP servers, sandbox providers, or other services can add their own charges.^[1][3][19]

Reasoning tokens are billed as output tokens. Total task cost can also include multiple model calls, cached input, cache writes for models that charge for them, retries, subagent calls, web searches, and sandbox compute. Recorded Agents API usage is useful for investigation but cannot always reproduce an exact bill, particularly when cache-write pricing applies.^[17]

Security and data controls

The main security boundary is the execution environment. Agent-generated code can access the files, credentials, and network destinations made available inside it. OpenAI recommends isolating compute by user or workload, restricting outbound traffic to approved endpoints, and using a dedicated OpenAI project when appropriate.^[12]

Application and executor credentials have different roles. OpenAI instructs developers to keep the broader application API key outside the sandbox. A self-hosted executor receives a restricted CODEX_API_KEY that must belong to the same organization, project, and user or service account as the session. Code inside the environment can read this executor key, although it authorizes environment connection rather than general API actions.^[11][12]

Long-lived third-party credentials are safer outside the environment. OpenAI recommends a credential broker that adds scoped secrets only to approved outbound requests. A service-origin MCP vault can keep its stored secret from agent-generated sandbox code, while a secret injected directly into an environment is exposed to code running there.^[12][14]

As of the public-beta release, the Agents API supports data residency only in the United States and does not support Zero Data Retention. Connecting a self-hosted sandbox does not make the API ZDR-eligible, because OpenAI still operates the harness and session service. Sessions and published artifacts can be deleted when they are no longer needed, subject to the platform's documented data controls.^[3]

Launch demonstration

OpenAI's launch video walks through a hypothetical incident-investigation agent rather than presenting a benchmark. The example connects observability data and recent code changes through MCP, gives the agent an outage runbook as a skill, filters a large log set through programmatic tool calling, delegates recent-change review and telemetry checks to separate subagents, compacts earlier context, and describes a report containing a likely root cause, supporting evidence, and suggested next steps.^[2]

The sequence illustrates how the product's components can fit together. It does not establish accuracy, latency, uptime, or success rates for production incident response.

Public-beta caveats

• The service was in public beta, not general availability, on September 10, 2026.^[1][20]
• The beta namespace, event schema, supported models, provider integrations, defaults, and prices can change. Current documentation should be checked before an implementation is deployed.
• A terminal turn.completed event does not guarantee that every tool call succeeded.^[8]
• Streams do not replay missed intermediate events after disconnection.^[9]
• Dashboard traces can lag behind answers, and API usage values can be missing or revised.^[17][18]
• A self-hosted environment does not self-host the harness or provide ZDR eligibility.^[3][5]
• OpenAI's release material gives no Agents API uptime, latency, or task-success guarantee.

See also

• OpenAI
• OpenAI API
• OpenAI Codex
• OpenAI Agents SDK
• OpenAI Responses API
• OpenAI Assistants API
• AI Agents
• Model Context Protocol
• Function calling
• Tool use

References

1. ^OpenAI. "Introducing the Agents API." September 10, 2026. openai.com/...introducing-the-agents-api
2. ^OpenAI. "Introducing the Agents API." YouTube, September 10, 2026. youtube.com/watch
3. ^OpenAI Developers. "Agents API." Accessed September 10, 2026. developers.openai.com/...overview
4. ^OpenAI Developers. "Agents." Accessed September 10, 2026. developers.openai.com/...agents
5. ^OpenAI Developers. "Architecture." Accessed September 10, 2026. developers.openai.com/...architecture
6. ^OpenAI API Reference. "Create an agent session." Accessed September 10, 2026. developers.openai.com/...create
7. ^OpenAI Developers. "Configuring Agents." Accessed September 10, 2026. developers.openai.com/...configuration
8. ^OpenAI Developers. "Run and continue sessions." Accessed September 10, 2026. developers.openai.com/...sessions
9. ^OpenAI Developers. "Events and items." Accessed September 10, 2026. developers.openai.com/...events
10. ^OpenAI Developers. "OpenAI-hosted sandboxes." Accessed September 10, 2026. developers.openai.com/...openai-hosted
11. ^OpenAI Developers. "Self-hosted sandboxes." Accessed September 10, 2026. developers.openai.com/...self-hosted
12. ^OpenAI Developers. "Sandbox security." Accessed September 10, 2026. developers.openai.com/...security
13. ^OpenAI Developers. "Functions." Accessed September 10, 2026. developers.openai.com/...functions
14. ^OpenAI Developers. "MCP connections." Accessed September 10, 2026. developers.openai.com/...mcp
15. ^OpenAI Developers. "Web search." Accessed September 10, 2026. developers.openai.com/...web-search
16. ^OpenAI Developers. "Multi-agent." Accessed September 10, 2026. developers.openai.com/...multi-agent
17. ^OpenAI Developers. "Observability and usage." Accessed September 10, 2026. developers.openai.com/...observability
18. ^OpenAI Developers. "Tracing." Accessed September 10, 2026. developers.openai.com/...tracing
19. ^OpenAI Developers. "Pricing." Accessed September 10, 2026. developers.openai.com/...pricing
20. ^OpenAI Developers. "API changelog." September 10, 2026. developers.openai.com/...changelog
21. ^OpenAI. "openai/codex." GitHub repository. Accessed September 10, 2026. github.com/...codex
22. ^OpenAI Developers. "Assistants migration guide." Accessed September 10, 2026. developers.openai.com/...migration
23. ^OpenAI. "Introducing AgentKit." October 6, 2025, updated June 3, 2026. openai.com/...introducing-agentkit
24. ^OpenAI Developers. "Workspace Agents." Accessed September 10, 2026. developers.openai.com/workspace-agents