OpenAI Agents API Public Beta in September 2026: A Practical Guide to the Managed Codex Harness

OpenAI’s Agents API public beta is aimed at teams that have moved beyond a single model call but do not want to maintain every part of an agent runtime themselves. The managed Codex harness provides durable sessions, sandbox execution, MCP tool access, delegated subagents, context compaction, and streamed events behind an API surface. The important distinction is architectural: you still define the agent’s instructions, tools, permissions, and business logic, but OpenAI manages much of the loop that decides when to call a tool, continue reasoning, compact history, or hand work to another agent.

What the managed harness actually provides

A conventional agent is often a loop around a model:

Send the conversation and tool definitions to a model.
Inspect the response for a tool call.
Run the tool in your application.
Append the result to the conversation.
Repeat until the model returns a final answer.

That pattern is flexible, but production systems quickly accumulate additional responsibilities. You need to persist conversation state, retry interrupted tools, enforce deadlines, stream partial output, prevent duplicate side effects, trim oversized context, record traces, and coordinate parallel work. The Agents API packages many of those runtime concerns into a managed session.

The Codex harness is particularly useful when an agent needs an execution environment rather than only JSON-returning tools. An agent can inspect files, run commands, produce artifacts, call approved MCP tools, and delegate specialized work. Your service remains responsible for application authorization and sensitive business operations, but the harness can own the mechanics of the working session.

Sessions are the durable unit of work

A session represents a continuing interaction between a user, an application, and an agent. Instead of resending the entire transcript on every request, your application creates or resumes a session and submits new input to it.

A representative session-creation request looks like this:

POST /v1/agents/sessions
Authorization: Bearer $OPENAI_API_KEY
Content-Type: application/json

{
  "agent": {
    "model": "your-approved-model",
    "instructions": "You are an internal support engineer. Inspect evidence before proposing changes."
  },
  "environment": {
    "type": "openai_hosted"
  },
  "metadata": {
    "tenant_id": "tenant_123",
    "application": "support-console"
  }
}

Exact field names and beta headers can change during a public preview, so keep the API client isolated behind your own service module. Do not spread raw Agents API calls through browser components or business-domain code.

Store the provider session identifier alongside your own user, tenant, and conversation identifiers. Never treat the provider session ID as an authorization boundary. Every resume request should first verify that the authenticated user is allowed to access the corresponding application record.

OpenAI-hosted versus self-hosted sandboxes

The hosted sandbox is the easiest starting point. OpenAI provisions the execution environment and the agent can use it according to the permissions and tools you configure. This is convenient for code analysis, document transformation, test execution, and other tasks where the workspace can be treated as disposable or isolated.

A self-hosted sandbox gives your organization more control over network access, installed dependencies, data residency, filesystem layout, and internal services. It also gives you more operational work. You must handle image maintenance, capacity, patching, process isolation, outbound restrictions, secrets injection, log collection, and cleanup.

Choose a hosted sandbox when the task can operate on copied or non-sensitive data and speed of implementation matters. Choose a self-hosted environment when the agent must reach private systems, use organization-specific runtimes, satisfy strict residency controls, or execute inside an existing security perimeter.

In either model, use least privilege. A coding agent should not receive unrestricted production credentials simply because it can run a command. Prefer short-lived credentials, allowlisted network destinations, read-only mounts, resource limits, and explicit approval for destructive actions.

MCP tools connect the agent to real systems

Model Context Protocol servers provide a standard way to expose tools and resources. In an internal agent, MCP might provide access to a ticketing system, source control, a documentation platform, an analytics warehouse, or an incident-management service.

A conceptual agent configuration might look like this:

{
  "agent": {
    "model": "your-approved-model",
    "instructions": "Use the ticketing tools for facts. Ask for approval before changing status.",
    "tools": [
      {
        "type": "mcp",
        "server": "support-tools",
        "allowed_tools": [
          "search_tickets",
          "get_ticket",
          "add_internal_note"
        ]
      }
    ]
  }
}

Do not expose every MCP method by default. Tool descriptions are part of the agent’s operating surface, and broad tool access increases the impact of prompt injection or mistaken reasoning. Separate read and write servers where possible. Require confirmation for refunds, account deletion, permission changes, deployments, and other irreversible operations.

MCP results should also be treated as untrusted input. A ticket comment, web page, repository file, or document can contain instructions intended to redirect the agent. Tell the agent to distinguish data from instructions, and enforce authorization in the tool server rather than relying only on the system prompt.

Subagent delegation for bounded parallel work

Subagents are useful when a primary agent needs independent specialists. For example, a release assistant might delegate one task to inspect failing tests, another to summarize recent changes, and a third to check deployment configuration. The parent agent then combines the results.

{
  "delegations": [
    {
      "name": "test-investigator",
      "instructions": "Inspect test failures and return evidence with file names and likely causes.",
      "permissions": ["filesystem.read", "process.run"]
    },
    {
      "name": "change-reviewer",
      "instructions": "Review the proposed diff for security and compatibility risks.",
      "permissions": ["filesystem.read"]
    }
  ]
}

Delegation is not automatically parallel or cheap. Set limits on depth, fan-out, runtime, and token usage. Give each subagent a narrow objective and a structured output contract. A parent should not receive ten pages of unfiltered scratch work when it only needs a list of findings and confidence levels.

Context compaction is helpful, not magical

Long sessions eventually exceed practical context limits. The managed harness can compact earlier turns into a shorter summary while preserving important state. This reduces the amount of history sent to later model calls, but compaction can lose details if your application has not made them explicit.

Persist important facts outside the transcript: customer identifiers, approval status, selected files, tool outputs required for audit, and decisions that must not be reversed. Ask the agent to maintain a concise working summary, and use structured state for workflow variables rather than hiding them in prose.

A good compaction strategy preserves goals, constraints, completed actions, unresolved questions, artifact locations, and authorization decisions. It should discard conversational repetition and low-value intermediate reasoning. Test compaction with long, branching conversations because the failure mode is often not an error; it is a plausible but incomplete answer.

Streaming events are the production interface

For a responsive customer-facing UI, consume structured events rather than waiting for one final response. Typical event categories include session status changes, text deltas, tool-call requests, tool results, sandbox output, subagent updates, compaction notices, and terminal completion or failure.

for await (const event of client.agents.sessions.stream(sessionId, {
  input: userMessage
})) {
  switch (event.type) {
    case "text.delta":
      sendToBrowser({ type: "text", value: event.delta });
      break;
    case "tool.started":
      sendToBrowser({ type: "activity", name: event.tool });
      break;
    case "session.completed":
      sendToBrowser({ type: "done" });
      break;
    case "session.failed":
      sendToBrowser({ type: "error", message: "The agent could not finish." });
      break;
  }
}

Make the stream resumable. Browsers disconnect, mobile networks change, and reverse proxies terminate idle connections. Assign an event cursor or sequence number, persist important events, and let the client reconnect without duplicating messages. Never use streamed text as proof that a side effect succeeded; rely on a typed tool result and an idempotency key.

Pricing: no separate Agents API fee, but tokens still matter

The practical pricing model in the public beta is that the Agents API itself does not add a separate platform charge. You pay for the model tokens used by the selected models. That does not mean an agent run is free: tool-heavy sessions, repeated retries, subagents, large context windows, and long-running reasoning can multiply token consumption.

Track cost by tenant, user, session, model, and tool. Set maximum turns, per-session token budgets, and execution timeouts. Subagents should have smaller budgets than the parent unless there is a clear reason otherwise. Treat sandbox compute, storage, or other environment charges as separate from model-token accounting when applicable to your configuration.

How this differs from rolling your own loop

A custom loop gives you maximum control. You decide the exact prompt format, state machine, retry behavior, tool protocol, persistence model, and runtime. That is appropriate when you need deterministic workflows, unusual model providers, on-premises execution, or strict control over every intermediate step.

The managed harness trades some of that control for faster delivery and built-in orchestration. Sessions, streaming, compaction, sandbox coordination, and delegation become provider-managed capabilities. The tradeoff is dependency on beta APIs, provider-specific event semantics, and less freedom to customize the internal loop.

The safest production approach is to hide the harness behind an application-level interface such as startAgentSession, sendAgentInput, and cancelAgentSession. Keep your domain tools, authorization checks, audit records, and user-facing state in your own system. Then the Agents API can accelerate the runtime without becoming the only place where your application’s behavior exists.

Production checklist

Authenticate and authorize every session resume request.
Use separate read and write tools, with approval for destructive actions.
Apply tenant scoping inside every MCP server and business tool.
Set turn, token, time, concurrency, and subagent fan-out limits.
Use idempotency keys for side effects and retries.
Persist audit events independently of the streamed UI.
Test prompt injection through tickets, files, web pages, and tool results.
Design for disconnected clients and resumable streams.
Measure token usage and sandbox activity by tenant and session.
Pin beta API behavior behind an adapter so migrations remain localized.

The Agents API is most valuable when your team needs a capable, tool-using agent quickly and does not want to operate every part of the orchestration layer. It is not a replacement for application security, authorization, observability, or careful workflow design. Treat the managed Codex harness as an execution platform, keep business truth in your own services, and use sessions, MCP permissions, delegation limits, and compaction deliberately rather than accepting their defaults blindly.

Search This Blog

Technology On the Net