The OpenAI Agents API is a public beta that gives your app the Codex harness through an OpenAI-managed API. OpenAI hosts and maintains the harness (sessions, orchestration, context compaction, recovery). You supply tools and pick where compute runs: an OpenAI-managed sandbox, your own infrastructure, or a sandbox partner. It is not the Agents SDK (you run the loop in your app), not the Responses API alone, not OpenAI Dots (always-on personal agents in ChatGPT and related surfaces), and not Cursor Self-Hosted Machines (Cursor plans, your workers execute).
Sources are OpenAI's Introducing the Agents API (September 10, 2026), the Agents API overview, MCP connections, OpenAI-hosted sandboxes, and self-hosted sandboxes. All checked on October 13, 2026. OpenAI also published customer quotes (for example Ciridae) on the launch page; this post does not repeat those metrics in our voice.
The short answer
Use the Agents API when you want OpenAI to run the Codex-class loop and you are fine calling that harness over the API, with native MCP, custom functions, built-in tools such as web search, programmatic tool calling, tool search, multi-agent fan-out (`max_concurrent_subagents`), and automatic context compaction. Pick `openai_hosted` when OpenAI's Linux sandbox is enough. Pick `self_hosted` (or a partner sandbox) when files, images, GPUs, or private network reachability must sit on infrastructure you trust, while the harness still stays at OpenAI.
Stay on OpenClaw, Hermes, or a Grok Bot-class stack when you want the agent process, model routing, tool policy, channels, and host trust on infrastructure you administer end to end. Calling the Agents API does not replace your Gateway unless you deliberately hand the loop to OpenAI. Start from OpenClaw vs Hermes Agent, trust boundaries for self-hosted agents, and the self-hosted deployment checklist.
What the managed harness provides
OpenAI manages sessions, orchestration, context compaction, and recovery. Your application provides tools and chooses the execution environment. Agents can run code, edit files, connect to MCP servers, and produce artifacts in a sandbox you configure.
Create a session with `client.beta.agents.sessions.create` or `POST /v1/agents/sessions` and the header `OpenAI-Beta: agents=v1`. Pricing has no extra Agents API fee: you pay model tokens, tools at their standard rates, and OpenAI-hosted sandbox container rates when you use that environment. The harness foundation is the open-source Codex harness; OpenAI operates it for the API. Public beta launched September 10, 2026 and is available to all developers. During beta, OpenAI says it will iterate quickly toward general availability.
MCP connections
MCP entries live in `agent.tools`. The Agents API discovers tools, calls the server, and returns results to the agent. Your app does not handle each call.
| Connection | Where it runs | Environment required? |
|---|---|---|
| HTTP with `connection_origin: "service"` (default) | From OpenAI | No |
| HTTP with `connection_origin: "environment"` | From the session environment | Yes (`openai_hosted` or `self_hosted`) |
| stdio | Process started in the session environment | Yes |
Service-origin HTTP must be reachable from OpenAI. Environment-origin HTTP fits private-network or in-sandbox servers; if you omit `connection_origin`, OpenAI makes the connection instead. Stdio needs `command` and an absolute `cwd`; omit `connection_origin`. For OpenAI-hosted stdio MCP, network access must be `enabled` (or omit the policy); `disabled` and `restricted` are not supported for those connections.
Auth notes from the MCP guide:
- Service-origin HTTP can use vault credentials via `vault_ids` (vault auth applies only to connections from OpenAI).
- One-session HTTP credentials can use `transport.authorization` or `transport.headers` (encrypted, omitted from the returned session resource).
- Environment-origin HTTP does not use vault credentials; use inline auth or a trusted proxy.
- Stdio lists credential env var names in `transport.env_vars`. Self-hosted sessions do not accept inline values in `transport.env`.
For what MCP is and how local vs remote transports differ outside this API, see what are MCP servers and local vs remote MCP servers.
Environment choices
OpenAI hosts the harness in every case. You choose compute.
OpenAI-hosted (`environment.type: "openai_hosted"`): same sandboxing infrastructure as Codex and ChatGPT. Linux with Python, Node, and CLI tools. Working directory `/workspace`. `container_size` is `small` (1 vCPU / 1 GB), `medium` (2 vCPU / 4 GB, default), or `large` (4 vCPU / 16 GB). `network.access` is `enabled`, `disabled`, or `restricted` (allowlisted hosts only).
Self-hosted (`environment.type: "self_hosted"`): you run `codex exec-server` inside your environment. The executor opens an outbound WebSocket, then runs shell, files, and local MCP at the harness's request. OpenAI never initiates inbound connections into your network for that link. Isolate environments by user or workload; agents that share an environment share files and credentials.
Sandbox partners: the launch post names Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel. Self-hosted docs also list AWS Lambda MicroVMs (and OCI) among provider guides. Those are places to run the executor; you still own image, secrets, and cleanup policy. For a different managed agent compute path on AWS (snapshot cold starts, not this API), see AgentCore Runtime V2.
Fitting beside OpenClaw, Hermes, and Grok Bot
OpenClaw is a Gateway you run. Hermes is a process you run from CLI, messaging Gateway, API server, or supported editor path. Grok Bot-class personal agents keep planning and tools on an operator host you attach. With the Agents API you call OpenAI's harness; you do not get an OpenClaw or Hermes Gateway substitute unless you choose to stop running that loop yourself.
Self-hosted Agents API sandboxes move shell and files next to your network, similar in spirit to other hybrid splits, but the planning harness remains OpenAI's. That is a different product decision from keeping model routing, tool policy, and channels on your Gateway. Write down who runs the loop before you migrate a production assistant.
Compare: Agents API, Cursor Self-Hosted, OpenClaw / Hermes
| Question | OpenAI Agents API | Cursor Self-Hosted Machines | OpenClaw or Hermes |
|---|---|---|---|
| Where does the agent loop run? | OpenAI-managed Codex harness | Cursor cloud (inference and planning) | Your Gateway or process |
| Where do shell and files run? | OpenAI-hosted sandbox, your executor, or a partner sandbox | Worker you register | Host and backends you configure |
| Native MCP | Yes, in `agent.tools` (service, environment, or stdio) | Local MCP on the worker as Cursor documents | MCP you wire into the Gateway or process |
| Who starts the session? | Your app via Agents API sessions | Cursor surfaces (app, web, Slack, GitHub, and so on) | Your channels, Control UI, or CLI |
| What the vendor still sees | Session traffic and tool results as OpenAI documents for the API | Tool outputs, diffs, screenshots, transcripts as Cursor documents | Whatever model and tool providers you wire |
Cursor's hybrid is covered in Cursor Self-Hosted Machines and computer use. Agents API is OpenAI harness plus optional OpenAI or your sandbox, not Cursor workers.
Limits and beta caveats
- Public beta: expect Preview iteration; confirm current docs before production cutover.
- Data residency is US only currently.
- Agents API does not support Zero Data Retention. A self-hosted sandbox does not make the Agents API ZDR-eligible.
- Hosted sandboxes can expire after about an hour without activity or keep-alives (not configurable per current hosted docs).
- Keep application API keys outside the sandbox; self-hosted docs use a restricted environment key for the executor.
How this fits implementation work
OrchestriAI does not resell or operate the OpenAI Agents API. AI agent systems define the job, which harness owns the loop, and where a person approves. MCP development builds narrow typed tools for service-origin or environment-origin MCP when a broad shell surface is the wrong default. Systems integration wires session create, vault or env credentials, and the sandbox or executor you chose.
Independence and limitations
OrchestriAI is an independent implementation provider. Product names are used for identification only. OrchestriAI is not affiliated with, endorsed by, or sponsored by OpenAI, Cursor, OpenClaw, or Nous Research / Hermes. This article summarizes OpenAI's Introducing the Agents API (September 10, 2026), the Agents API overview, MCP connections, OpenAI-hosted sandboxes, and self-hosted sandboxes, all checked on October 13, 2026. We have not run the Agents API ourselves for this post. Features, auth details, partner lists, residency, retention, and beta terms can change, so confirm current OpenAI documentation before you connect production tools. This is not a security certification or a compliance conclusion.
