OpenAI Agents API: managed Codex harness (public beta)

Note: body below is original English text from OpenAI developer docs / changelog. Do not treat this file as a translation.

Published 2026-09-10 (public beta) · docs: https://developers.openai.com/api/docs/guides/agents-api/overview

Changelog (Sep 10, 2026)

Released the Agents API in public beta. Build agents with a managed Codex harness while OpenAI handles session orchestration, context compaction, and recovery.

Use durable sessions to continue work across turns, stream progress, and connect your own tools and MCP servers. Run agents in OpenAI-hosted sandboxes or connect a sandbox from your own infrastructure or a supported provider.

Start with the Agents API quickstart.

Overview

Build durable cloud agents with a managed Codex harness.

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

OpenAI manages sessions, orchestration, context compaction, and recovery while your application provides tools and chooses its execution environment.

Agents can operate in a sandbox where they can execute code, edit files, connect to MCP servers, and produce artifacts.

Pricing

Model usage is billed at the selected model’s API rates. OpenAI tools use their standard rates, and OpenAI-hosted sandboxes use standard container rates.

Core concepts

The Agents API is built around four main concepts:

• 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 produced during a session.

A session from start to finish

1. Create a session. Configure the agent; OpenAI provisions its environment.
2. Give it a task. User input starts a turn of work once the environment is ready.
3. Follow progress. Stream output or use webhooks to learn when the agent finishes or needs input.
4. Continue or steer. Send another task to the same session, or guide the agent during its current turn.

What the managed harness provides

The managed Codex harness supports:

• Running commands and code in a sandbox.
• Applying relevant skills and instructions.
• Connecting to external data through tools or MCP.
• Steering the agent while it works.
• Summarizing previous work to manage its context window.
• Breaking work into subtasks and delegating to subagents.
• Resuming a session where it left off.

Capability directories (example /workspace/capabilities/skills) load skills and instructions from the environment. Multi-agent config can enable concurrent subagents.

The Agents API retains session state so you can continue work across turns without rebuilding the conversation context. You can delete sessions and published artifacts when you no longer need them. The Agents API currently supports data residency only in the United States and does not support Zero Data Retention (ZDR). Choosing a self-hosted sandbox does not make the Agents API ZDR-eligible.

Requests require the OpenAI-Beta: agents=v1 header (SDKs add it automatically).

Architecture

OpenAI runs the agent harness. Your application sends it work and receives results. Add an environment when the agent needs compute or files.

The pieces

• Harness: The OpenAI-hosted Codex instance that runs the model and tool loop and maintains the agent’s session.
• Environment: Where the agent runs commands, executes code, and works with files. An environment can be a remote sandbox, your laptop, a Docker container, or an AWS Lambda function.
• Application server: Your code that connects the agent to your product. It submits tasks, receives events, and handles function tools. When you provide the environment, your code also manages its lifecycle.

Environment options

• environment.type: "none" — no compute/files; remote MCP and function tools still available; built-in Bash / apply-patch / workspace files unavailable.
• environment.type: "openai_hosted" — OpenAI creates and manages a sandbox; configure packages, files, and network access.
• environment.type: "self_hosted" — your infrastructure; your code starts the environment and connects an executor; you own provisioning, reconnection, shutdown, and files.

Progress and results

• Streaming: Receive detailed events as the agent works.
• Webhooks: Receive session state changes without keeping a stream open.

Function tools need a handler that receives calls and returns results. If that handler is unavailable, the agent can remain waiting for a result.

Remainder

Full docs: overview / architecture / quickstart URLs in frontmatter. Do not invent missing SDK fields beyond what is quoted above.