OpenAI's Agents API explained: hosted Codex sessions versus the Responses API and Agents SDK

What the Agents API actually is

OpenAI's Agents API, in public beta since 10 September 2026, moves the agent loop server-side. According to a dev.to walkthrough, the service runs on OpenAI's open-source Codex harness, so a single HTTP request to POST /v1/agents/sessions (with the OpenAI-Beta: agents=v1 header) is enough to start a persistent agent. You supply an agent definition — model, instructions, tools and MCP servers, sent inline or saved and reused by ID — plus the task, and OpenAI runs the model, drives the tool loop, manages the session and can provision a sandbox on demand. At its DevDay event on 29 September, OpenAI added computer use to the API, with approval steps for those actions.

The walkthrough breaks the API into four concepts: the agent, the environment it executes in, the session that persists configuration, conversation and saved items, and the events and items that report progress. Messages sent to an idle session start a new turn, while messages sent mid-turn steer the harness. The harness also handles context compression, so developers do not configure it themselves.

Who runs the loop

A companion dev.to comparison frames the choice between OpenAI's agent surfaces with one question: who runs the loop?

• Responses API: a model endpoint at POST /v1/responses. Hosted tools such as web search can chain several actions inside one request, but your own function tools return control to your code — you run the function, send back a function_call_output with the same call_id, and repeat until the model produces a final answer. History, previous_response_id chaining and context compaction are yours to manage.
• Agents SDK: a TypeScript and Python library whose runner executes the loop and handoffs inside your application, while deployment, tool implementations, state storage, authorization and human approval remain your responsibility.
• Agents API: OpenAI runs sessions, orchestration, context compression and recovery, and calls remote MCP servers directly. Function tools are still your job — when a session reports required_actions, you return an agent.session.input.tool_result event with the turn_id and call_id.
• AgentKit: the October 2025 bundle of Agent Builder, ChatKit, Connector Registry and Evals. The comparison, citing OpenAI's deprecation page, says Agent Builder and Evals are scheduled to shut down on 30 November 2026, while ChatKit remains.

Environments, events and tools

The walkthrough details the environment.type setting. none gives you no compute: remote MCP servers and function tools still work, but built-in Bash, apply-patch and workspace files do not. openai_hosted is an OpenAI-managed Linux sandbox with Python and Node.js, container sizes of 1 GB, 4 GB or 16 GB, configurable network access, and files in /workspace/outputs surfacing as artifacts. self_hosted has you run codex exec-server on your own laptop, container or remote sandbox and connect outbound with separate environment keys. Named sandbox partners include Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel, with the self-hosted guide also mentioning AWS Lambda MicroVMs.

Progress arrives either through a streaming events endpoint or webhooks, and the two surfaces use slightly different names — the stream emits agent.session.turn.* events and requires_action, while webhooks use agent.session.action_required. Webhook payloads omit call details, so handlers must fetch the session and read required_actions themselves, and every request's signature should be verified. The walkthrough also warns that an idle event does not mean a turn succeeded, that completed turns can contain failed tool calls, that closing the stream does not stop the work, and that streams do not replay missed events.

MCP servers attach through agent.tools. By default OpenAI connects to them (connection_origin set to service), with an environment option or stdio for private-network servers, and credentials supplied per session or via vaults. MCP tools are discovered automatically where the model supports tool search, large function sets can defer loading, and subagents are enabled through a multi_agent block that caps concurrent subagents.

Pricing, limits and data controls

There is no separate Agents API fee. You pay model tokens at API rates, tools at their standard rates (the walkthrough cites web search at $10 per 1,000 calls) and hosted container time — $0.03, $0.12 or $0.48 per 20-minute session for small, medium and large containers. Required API key scopes are api.agents.read, api.agents.write and api.responses.write, and requests cap at 4 MiB. Data residency is US-only, Zero Data Retention is not supported, and session state is kept until deleted. Documentation examples use the gpt-6-astra model.

Why it matters

The comparison's table rates integration effort as low for the Agents API and high for the Responses API, and that is the real story: OpenAI is absorbing the orchestration, state management and sandbox plumbing that most agent projects rebuild. The trade-off is where things live. Session state sits with OpenAI under US-only, no-ZDR terms, which the comparison notes can rule it out for strict data regimes, while the Responses API can be ZDR-compatible and the SDK keeps state in your own storage. Token prices are identical across the options, so the deciding costs are hosted containers versus engineering time. Notably, the comparison still lists the Responses API as the recommendation for all new projects, positioning the beta Agents API as the convenience path rather than a replacement.