OpenAI Agents API: the Codex Harness as a Managed Production Runtime
On 10 September 2026 OpenAI put the harness behind Codex into a public-beta API. Instead of a model endpoint, applications get a managed agent runtime — durable sessions, orchestration, context compaction, tool search, subagents and recovery — and choose where code runs: nowhere, an OpenAI sandbox, a partner sandbox or their own machines. This visual deep dive takes the product apart from its public documentation: the system boundary, the four runtime objects, the managed loop, compaction, tools and MCP, execution environments, and a full incident-investigation run.
01 What This Product Is
The Agents API gives applications access to an OpenAI-managed Codex harness as a service — the same harness that runs Codex and ChatGPT for Work. The key idea: not just a model endpoint, but a managed agent runtime with orchestration, durable sessions, tools and execution capabilities.
02 The System Boundary: OpenAI vs Developer
The product is best understood as a line through the agent stack. Click any responsibility to see which side of the line it sits on, and why:
03 High-Level Architecture
A user talks to the developer's application; the application sends API requests (streaming or asynchronous) to the Codex harness; the harness calls the model and orchestrates tools across three kinds of endpoint. Press play to follow one request:
04 Core Runtime Objects
Four objects make up the API. Click each to see its role and an illustrative shape:
05 The Managed Agent Loop
Inside a session, the harness repeats one loop until the task is done — and every step of it is now OpenAI's code, not yours:
06 Durable Sessions and Context Compaction
A session is a durable agent instance: it keeps configuration, conversation and saved work, so an application can send follow-ups, steer the agent mid-task, or resume days later. As a session nears its context limit, OpenAI automatically compacts earlier context so work spans multiple context windows — preserving key decisions and constraints, references to important artifacts and files, and unresolved tasks, while removing or compressing less relevant detail.
The same model as a runnable script, priced at GPT-6 Astra's list rates:
"""What automatic context compaction does to a long agent session's size and cost. Each model call in an agent session re-reads the whole context (instructions + history), then adds new tool results and output to it. Without compaction the context keeps growing until it hits the window; with compaction, when the context nears a threshold the harness replaces older history with a compact summary of decisions, artifacts and open tasks, and the session continues. Price: GPT-6 Astra list price, $10 per 1M input tokens and $50 per 1M output tokens (September 2026), without prompt-caching discounts. Session shape is an assumption. Standard library only. """ WINDOW = 1_050_000 # GPT-6 Astra context window (reported ~1.05M tokens) IN_PRICE, OUT_PRICE = 10 / 1e6, 50 / 1e6 BASE, GROWTH, OUT = 12_000, 6_000, 800 # instructions+tools, new tokens per step, output per step def run(steps, threshold=None, summary=40_000): ctx, in_tok, out_tok, peak, compactions = BASE, 0, 0, 0, 0 for _ in range(steps): if ctx + OUT > WINDOW: return None # the session cannot continue in_tok += ctx; out_tok += OUT; peak = max(peak, ctx) ctx += GROWTH + OUT if threshold and ctx > threshold: ctx = BASE + summary; compactions += 1 # older history -> compact summary return in_tok, out_tok, peak, compactions print("Long agent session: each step re-reads the context, adds ~6,800 tokens\n") print(f" {'steps':>6} {'strategy':<24}{'peak context':>14}{'input tokens':>15}{'cost':>10}{'compactions':>13}") for steps in (50, 150, 400): for name, thr in (("no compaction", None), ("compact at 200K", 200_000), ("compact at 100K", 100_000)): r = run(steps, thr) if r is None: print(f" {steps:>6} {name:<24}{'exceeds window - run fails':>52}") continue i, o, peak, c = r print(f" {steps:>6} {name:<24}{peak:>14,}{i / 1e6:>13.1f}M{'$' + format(i * IN_PRICE + o * OUT_PRICE, ',.0f'):>10}{c:>13}") print() print("Input tokens dominate: every step pays again for everything still in context.")
Output:
Long agent session: each step re-reads the context, adds ~6,800 tokens
steps strategy peak context input tokens cost compactions
50 no compaction 345,200 8.9M $91 0
50 compact at 200K 195,600 5.6M $58 2
50 compact at 100K 99,600 3.4M $36 5
150 no compaction 1,025,200 77.8M $784 0
150 compact at 200K 195,600 17.6M $182 6
150 compact at 100K 99,600 11.0M $116 18
400 no compaction exceeds window - run fails
400 compact at 200K 195,600 48.7M $503 17
400 compact at 100K 99,600 30.0M $316 49
Input tokens dominate: every step pays again for everything still in context.Because every step re-reads everything still in context, input tokens dominate a long session's cost, and compaction cuts them by several times — and keeps a 400-step session running at all. The trade-off is fidelity: whatever the summary drops is gone, which is why compaction keeps decisions, artifacts and open tasks explicitly. Prompt caching (not modelled) reduces the uncompacted cost further.
07 Tools and MCP Architecture
The harness can use the developer's function tools and remote MCP servers, with support for tool search and programmatic tool calling. The two paths run differently — pick one:
08 Execution Environment Choices
Environments are optional. An agent that only reasons and calls tools needs none; one that runs commands and edits files needs a workspace. Answer three questions:
| Option | Description | Best for | Key characteristics |
|---|---|---|---|
| None | No code execution environment | Q&A, remote tools, data retrieval | Harness runs with model + tools only |
| OpenAI-hosted sandbox | Isolated, managed Linux workspace run by OpenAI | Code execution, file operations, package install, analysis | File system, shell, packages, mounted data, controlled ports, snapshots; billed at container rates |
| Partner sandbox | Integrated providers such as Cloudflare, Daytona, DigitalOcean, E2B, Modal, Vercel and others | Teams already standardized on a sandbox vendor | Provider-managed isolation and billing |
| Self-hosted environment | An executor in your infrastructure runs commands at the harness's request | Sensitive data, custom infrastructure, on-premises resources | Your laptop, a Docker container or a serverless function; outbound-only connection; you manage security, network and access |
09 The Sandbox and the Self-Hosted Executor
The control plane / execution plane split is the architecture's core. With a self-hosted environment, OpenAI still runs the harness; you run an executor (codex exec-server) that registers with an environment ID and a restricted API key, then opens an outbound WebSocket to receive commands and return results. No inbound ports are opened, and the executor reconnects if the connection drops.
- File system (read/write)
- Shell (command execution)
- Packages (install as needed)
- Mounted data
- Network access (controlled/limited)
- Ports (controlled)
- Snapshots (save/restore)
- Artifacts (files, logs, results)
- Isolated Unix-like environment
- Narrow, controlled credentials
- Controlled external access
- Snapshot and resume
10 Subagents and Long-Running Work
The harness can decompose complex tasks into subagents and run them asynchronously, while the application streams progress, steers mid-run and resumes later in the same session:
11 Reliability, Observability and Recovery
The application watches a session through streamed events (tokens, tool calls, status, logs) or webhooks for state changes without holding a stream open — and can steer, pause or cancel. The harness handles retries and recovery. Watch an event stream with a failure in it:
- Streaming events and webhooks
- Run tracing and event history
- Tool calls and results
- Subagent progress, state and metadata
- Automatic retries (where possible)
- Resume from the last state
- Recover from transient failures
- Session integrity; clean-up of resources
- Add input during a run
- Change direction
- Approve or block actions (via app policies)
- Cancel, pause, continue later
12 Where It Fits vs Other OpenAI Agent Options
| Feature | Agents API (managed harness) | Agents SDK (self-hosted) | Responses API (model calls) |
|---|---|---|---|
| What it provides | OpenAI-managed Codex harness | A harness library in your infrastructure | Direct model calls with built-in tools |
| Agent loop | Managed by OpenAI | SDK runner in your process | You write it |
| Durable sessions | Yes | You build/manage (sessions, snapshots) | You build/manage |
| Context compaction | Automatic | You manage | You manage (compaction endpoint available) |
| Tools & MCP | Supported, incl. tool search | Supported | Supported (you manage the loop) |
| Execution environment | None, OpenAI, partner or self-hosted | Your infrastructure or sandbox providers | N/A (you manage) |
| Best for | New managed-runtime agent applications | Full control, custom deployment | Direct model usage and custom agent loops |
13 End-to-End Example: "Investigate a production incident and prepare a mitigation report"
Next: Product case study #2 — Claude Agent SDK and Managed Agents: the Claude Code harness in production.
⚠️ Notes
codex exec-server executor over an outbound WebSocket, registered with an environment ID and a restricted API key; (3) MCP egress — remote MCP calls leave from OpenAI's service, not from your executor, so executor egress rules don't cover them; (4) pricing and models — there is no separate API fee (tokens and tools, hosted sandboxes at container rates) and the default model is gpt-6-astra; the infographic states neither. The compaction chart and script use a stated session model; event names, object shapes and the incident run are illustrative.