OpenAI’s Agents API Makes the Harness a Service—But State Ownership Should Decide Adoption

Verified against OpenAI documentation and terms available on September 12, 2026.

Building a durable agent is not merely a model-selection problem. The harder question is who owns the model-and-tool loop, retained context, compaction, recovery, approvals, execution lifecycle, and evidence that external actions actually succeeded.

OpenAI’s Agents API, announced in public beta on September 10, 2026, moves the Codex harness and durable session into an OpenAI-managed service. OpenAI says the beta is available to all developers and carries no separate Agents API platform fee; selected models, OpenAI tools, and OpenAI-hosted sandboxes remain billable at their applicable rates. (Launch announcement; Agents API overview)

The adoption decision is therefore not “Does it have more features than the Agents SDK or Responses API?” It is: Should OpenAI own the orchestration loop and retained session state for this workload? As of September 12, the answer is constrained by public-beta status, United-States-only Agents API residency, no Zero Data Retention eligibility, incomplete API-level trace export, and lifecycle responsibilities that remain with the customer when execution is self-hosted. (Agents API overview; Observability)

Key Takeaways

Treat the Agents API as managed agent control-plane infrastructure, not as another model endpoint.

A self-hosted sandbox relocates commands, files, and local tool connections; it does not relocate the harness or Agents API session state.

OpenAI labels integration effort low for Agents API, medium for Agents SDK, and high for Responses API. Those are vendor classifications, not workload-specific measurements.

Agents API session state currently supports residency only in the United States and is not ZDR-eligible, including with self-hosted execution.

Compare runtimes using cost per verified successful task, not token price, session completion, or prototype speed alone.

Figure 1: Illustrative photograph: a close up of a computer screen with a message on it. Image: Unsplash / Jonathan Kemper

What OpenAI Actually Released

Hands-on API Example: Creating a Durable Session

The smallest useful implementation test is a session that declares the model, one MCP tool, an execution environment, and a concrete task. The following JavaScript example is adapted from OpenAI's official Agents API announcement. Replace the vault identifier and MCP endpoint with resources your team controls; never paste production credentials into the source.

Runnable shape · JavaScript

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "observability",
        transport: {
          type: "http",
          server_url: "https://observability.example.com/mcp",
        },
      },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: ["vault_YOUR_VAULT_ID"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input:
    "Investigate service-api's elevated 5xx rate over the last 30 minutes and save findings in /workspace/outputs.",
});

console.log({ id: session.id, status: session.status });

OpenAI Agents API architecture overview — Figure 4: Official Agents API overview showing the managed harness and selectable execution environment. Image: OpenAI, official announcement.

What this example proves—and what it does not

The request shape makes the ownership boundary visible: OpenAI receives the agent configuration and runs the harness, while the developer still chooses the tool endpoint, vault, environment policy, and acceptance criteria. A successful HTTP response or a queued status is not proof that the investigation finished correctly.

Validation note: The snippet passed a local JavaScript syntax check, but this article does not claim a live Agents API run. Before production adoption, run the same task with a disposable vault and record session status transitions, tool-call evidence, artifact existence, retry behavior, and cost per verified result. The official example is an implementation reference, not an independent benchmark.

OpenAI documents four central concepts:

Agent: the model, instructions, tools, and MCP servers available to the agent.
Environment: an optional sandbox or computer for files, skills, and commands.
Session: a durable agent instance that accepts tasks across turns.
Events and items: the inputs and outputs generated during the session.

The managed harness provides orchestration, session management, context compaction, subagent delegation, tool use, steering, and session resumption. The application supplies tools, chooses the environment, sends work, and consumes events or webhooks. (Agents API overview; Architecture)

An environment is optional. When one is needed, execution may occur in an OpenAI-hosted sandbox, a self-hosted environment, or a supported provider environment; the API can also run with no sandbox. Regardless of that choice, OpenAI’s hosted Codex instance runs the model-and-tool loop and maintains the Agents API session. (Architecture; Runtime comparison)

The following architecture view captures the distinction between the managed control plane and the selectable execution plane.

Figure 1: The Agents API keeps orchestration and durable session state in OpenAI’s managed control plane; only the command-and-file execution environment is selectable.

Agents API Versus Agents SDK Versus Responses API

OpenAI’s comparison is explicit about orchestration and state ownership. The implications for auditability, migration cost, and operational control are editorial conclusions that teams should validate against their own workloads. (Runtime comparison; Agents SDK overview)

Decision dimension	Agents API	Agents SDK	Responses API	What must be validated
Orchestration owner	OpenAI runs the managed Codex harness.	The SDK runner executes in the application.	The application works directly with model responses; optional hosted capabilities may still run service-side.	Map retries, stopping, delegation, compaction, approvals, and recovery.
State between tasks	OpenAI saves session configuration, turns, and items.	Application storage, SDK sessions, or Responses conversation state.	Manual history, response chaining, or Conversations.	Inventory prompts, tool results, artifacts, deletion paths, and recovery metadata.
Execution environment	OpenAI-hosted, self-hosted, or none; provider-hosted execution uses the self-hosted connection model.	Application runtime plus configured sandbox integrations.	Application-owned execution, with separately configured hosted tools where used.	Record where commands, files, identities, and network connections originate.
Vendor integration-effort label	Low.	Medium.	High.	Replace the labels with implementation, upgrade, testing, on-call, and incident-recovery hours.
Tool execution	Service-connected tools, application function handlers, and optional sandbox execution.	Tools and integrations configured in the application.	Hosted tools and tools executed by the application.	Trace identity, timeout, approval, result validation, and connection origin for every tool path.
Recovery	Durable sessions can resume, but environment and command failures still require outcome checks.	Depends on SDK state, storage, sandbox, and application recovery design.	Depends on application persistence, retry, and idempotency design.	Inject disconnects, crashes, duplicate submissions, and ambiguous completion.
Approvals	Approval and policy enforcement must be assessed per tool path; function tools execute in application code.	The application owns approval decisions, and the SDK supports resumable human-review interruptions.	The application owns approval and continuation logic.	Reject a sensitive action and verify that no tool, retry, or alternate path bypasses the denial.
Observability	Events, saved items, turns, dashboard traces, and best-effort root/subagent usage; no public trace retrieval or external trace exporter in beta.	SDK tracing plus application telemetry.	Application telemetry plus endpoint and tool events.	Reconcile traces with approval records, tool receipts, invoices, and external system logs.
Data controls	US-only Agents API residency; `/v1/agents` is not ZDR-eligible.	Depends on the API endpoint, application storage, tracing, tools, and sandbox configuration.	Endpoint- and project-specific controls; application-owned state remains separate.	Verify project, region, retention, third parties, deletion commitments, and DPA treatment.
Pricing	No separate Agents API fee; model, tool, container, provider, storage, and external-service charges may apply.	Models, tools, sandbox, storage, and operating labor.	Models, tools, storage, infrastructure, and custom orchestration.	Hold task set, model, tools, compute, retries, and acceptance criteria constant.
Portability	Managed session, harness, tool, and environment semantics create replacement work.	More orchestration remains in application code, although SDK and sandbox abstractions still require migration.	Offers the most direct control over a custom loop but remains tied to chosen endpoint and tool semantics.	Maintain an exit inventory and estimate replacement work before production adoption.
Maturity	Public beta as of September 12, 2026.	Maturity varies by SDK capability; sandbox agents are separately documented as beta.	Maturity varies by endpoint, model, and hosted tool.	Review change control, support, SLA, security scope, and contractual treatment.
Outcome quality	No universal advantage is established by the runtime documentation.	Same.	Same.	Compare verified completion, safety, latency, cost, and operator effort using a shared oracle.

Figure 2: Illustrative photograph: a purple background with a black and blue circle surrounded by blue and green cubes. Image: Unsplash / Deng Xiang

What the Agents API Does Not Replace

The managed harness reduces orchestration work, but it does not transfer every production responsibility to OpenAI. This distinction is the practical boundary that a feature checklist can hide.

Independent context: contemporaneous coverage, including S5 Labs’ overview, focuses on managed sessions, sandbox choices, and cost boundaries. This article takes a different lens: it maps state ownership and verified side effects so a team can decide what should remain in application code.

Responsibility	Agents API	Developer
Session state	OpenAI manages the Agents API session, turns, and items.	Define retention, deletion, recovery evidence, and the records your product must own.
Context compaction	The managed harness coordinates context across a durable session.	Decide what context is safe to retain, what must be reloaded, and what must be summarized or discarded.
Tool permissions	The API exposes tools and environment paths; it does not define your business authorization policy.	Approve tools, scopes, identities, timeouts, and human-review gates.
Credentials	Execution environments may access only the connections you configure.	Keep application keys and third-party secrets outside the sandbox where possible, and broker access deliberately.
Business logic	The harness coordinates model and tool work.	Own domain rules, idempotency, side-effect ordering, and decisions that require customer context.
Output validation	A completed turn or returned event is not proof that an external action succeeded.	Validate schemas, artifacts, receipts, tests, and the final business outcome before marking work complete.

Our view: the Agents API can remove a meaningful amount of plumbing, but it cannot remove application-level permission controls, evaluation, or recovery logic. Teams should therefore compare verified successful work, not merely shorter agent code.

Self-Hosted Execution Does Not Self-Host the Agent

In a self-hosted environment, OpenAI still runs the harness. The customer runs codex exec-server, which executes requested shell commands, reads and writes files, and uses local MCP servers. It registers with an environment ID and restricted environment key, then connects outbound by WebSocket to receive commands and return results. (Self-hosted sandboxes; Architecture)

Each session receives its own environment ID and needs its own executor. The executor reconnects when its transport connection drops, but this should not be confused with command recovery: OpenAI’s lifecycle documentation says a mid-turn disconnect can fail a tool, does not automatically restart a killed command, and does not automatically issue a reconnection webhook. (Self-hosted sandboxes; Sandbox lifecycle)

Persistence, Waiting, and Cleanup

The application owns provisioning, the session-to-compute mapping, reconnection coordination, files it needs to preserve, and shutdown. Reusing an environment ID does not recreate files on replacement compute; preservation requires provider storage or snapshots. (Sandbox lifecycle; Self-hosted sandboxes)

When input arrives without a connected executor, the API waits up to five minutes for an input-time connection. If the wait expires, the submission fails; a late connection does not replay timed-out input, and recovery of pending input after a process crash is not guaranteed. Applications must inspect request and session outcomes before retrying. (Sandbox lifecycle)

Deletion is also split. Deleting the API session neither stops the self-hosted environment nor emits a deletion webhook. Teams must stop new input, coordinate with any concurrent startup work, delete the API session, stop provider compute, and clean customer-controlled storage separately. (Sandbox lifecycle)

The lifecycle below highlights why session resumption and outcome recovery are different engineering properties.

Figure 2: Self-hosted execution adds customer-owned provisioning, reconnection, persistence, outcome verification, and teardown responsibilities around OpenAI’s managed harness.

Decision rule: recovering conversation state does not prove that a command, file write, ticket update, payment, or deployment happened exactly once.

OpenAI-Hosted Sandboxes: Convenience With Explicit Limits

An OpenAI-hosted sandbox supplies a Linux workspace managed and connected by OpenAI. Outbound network access is enabled by default unless the session inherits a more restrictive template policy. Restricted mode accepts 1–100 exact hostnames; wildcards, protocols, paths, and ports are invalid, and subdomains and redirect destinations require separate entries. (OpenAI-hosted sandboxes)

Each session has a separate workspace. Files persist across turns only while the sandbox exists. Files placed under /workspace/outputs are published as immutable artifacts when a turn completes, and those published copies remain downloadable after sandbox expiry. If activity and keep-alives stop for one hour, the sandbox can be deleted; the timeout is not configurable. (OpenAI-hosted sandboxes)

OpenAI also states that a completed turn does not guarantee that every tool succeeded. Applications should inspect saved items, verify required artifacts, and reconcile external side effects instead of treating terminal session status as evidence of business completion. (OpenAI-hosted sandboxes; Observability)

Pricing: No Harness Fee Does Not Mean a Single-Layer Bill

The launch announcement says there is no additional fee for the Agents API itself. The overview separately states that model usage follows the selected model’s API rates, OpenAI tools use their standard rates, and OpenAI-hosted sandboxes use standard container rates. Partner sandboxes and external services have their own commercial terms. (Launch announcement; Agents API overview)

On the official pricing page reviewed September 12, OpenAI listed Hosted Shell and Code Interpreter containers at:

1 GB: $0.03
4 GB: $0.12
16 GB: $0.48
64 GB: $1.92

These are US-dollar rates per 20-minute session per container. OpenAI additionally says eligible container sessions are billed by the minute with a five-minute minimum. “GB” in this table means 2³⁰ bytes. Model tokens and applicable tool calls remain separate. (OpenAI API pricing)

An agent may make several root-agent and subagent model calls, including retries. Input, cached input, cache writes where applicable, output, reasoning, tools, sandbox compute, storage, and third-party services can therefore contribute to one task’s cost. The Agents API usage object is best-effort and does not expose a separate cache-write count, so it may not reconstruct the exact model charge for cache-write-priced models. (Observability; API pricing)

The useful denominator is:

total provider and operating cost ÷ verified successful tasks

A verified success should require accepted output, passing validations, complete artifacts, authorized side effects, and sufficient evidence—not merely a completed session.

Residency and ZDR Are Direct Adoption Gates

OpenAI supports API access from many countries and territories, but access geography is not the same as processing or storage residency. The Agents API documentation states that retained session state currently supports residency only in the United States and that the Agents API does not support Zero Data Retention. Choosing a self-hosted sandbox does not make it ZDR-eligible. (Supported countries; Agents API overview)

The platform data-controls table independently lists /v1/agents application state as retained until deletion and marks the endpoint ineligible for ZDR. This differs from eligible uses of /v1/responses, where ZDR can force store to false; it also differs from the broader regional options available to other supported endpoints. (Data controls)

For an architecture requiring non-US Agents API state, ZDR, or customer-owned conversational records, this is a current no-go, regardless of where shell commands execute.

Observability Is Useful but Not Independent Accounting

Agents API sessions expose live events, saved history and items, public turn resources, and subagent_id attribution for delegated work. The dashboard can display recorded model responses, tool calls, subagent activity, durations, and statuses. (Observability)

However, public-beta limitations matter:

Public API trace retrieval and external trace exporters are unavailable.
Detailed dashboard trace endpoints are not a supported customer API.
Usage can be null, may change as accounting arrives, and is not a final bill.
Cache writes are not separately counted in Agents API usage.
The customer API does not indicate whether command output was truncated.

These limitations do not make the telemetry unusable, but they do require application-side correlation IDs, approval records, idempotency keys, artifact manifests, side-effect receipts, external-system logs, and invoice reconciliation. (Observability)

Security Responsibility Follows the Execution and Connection Path

OpenAI warns that agent-generated code can access the files, credentials, and network available to its environment. Its guidance recommends isolated compute, separate environments for workloads that must not share data, dedicated projects, and outbound access limited to approved endpoints. (Sandbox security; Self-hosted sandboxes)

The broader application key should remain outside the sandbox. The self-hosted executor uses a restricted environment key that can only connect environments, but generated code can still read that key. OpenAI recommends keeping third-party credentials outside the environment where possible and using a credential broker to inject secrets only into approved outbound requests. (Sandbox security)

Connection origin also changes the trust boundary: executor MCP servers connect from the customer environment, remote MCP servers connect from OpenAI’s service, and function tools execute in application code. Each path needs explicit identity, egress, approval, timeout, logging, and result-verification controls. (Sandbox security; Architecture)

Beta Terms Make Procurement Review Mandatory

This is not legal advice. The applicable order form or negotiated terms may differ.

The OpenAI Services Agreement effective January 1, 2026 says beta services may be unsupported, may change without notice, may be less reliable or available, and may not have undergone the same security measures and auditing as other services. Its beta provision also limits OpenAI’s liability for those services. (Services Agreement)

The Service Terms updated September 10, 2026 describe beta services as offered “as-is” for testing and evaluation, exclude them from OpenAI’s indemnification obligations, and disclaim assurances of general availability, uninterrupted operation, error-free operation, or protection against content loss or damage. (Service Terms)

The editorial implication is straightforward: review the applicable agreement, Service Terms, DPA, security materials, audit scope, SLA, deletion terms, subprocessors, support, and indemnity treatment before making the beta part of production infrastructure.

A State-Ownership Rule for Adoption

Favor the Agents API only when:

The workload genuinely benefits from durable, multi-turn execution.
US-resident retained session state and lack of ZDR are acceptable.
Orchestration, compaction, and recovery are commodity plumbing rather than product differentiation.
Representative testing establishes an acceptable trade-off across verified completion, safety, operator effort, cost, observability, and exit complexity.

Choose the Agents SDK when the application must own deployment, storage, approvals, tool implementations, and runtime behavior. Choose the Responses API directly when the workflow is bounded enough that a durable managed session would add more state and lifecycle surface than value. (Agents SDK overview; Runtime comparison)

The following decision path treats state and policy constraints as gates rather than post-prototype cleanup work.

When I Would Use the Agents API—and When I Would Not

I would use the Agents API when the workload has a clear reason to keep working across turns: long-running tasks, sandbox execution, several coordinated tools, or resumable sessions where rebuilding the harness would not differentiate the product.

Use it when: the task is multi-step, the environment can be isolated, session state may be retained under the service's current residency terms, and the team can verify every external side effect.
Do not make it the default when: the workflow is a simple single-turn call, strict Zero Data Retention or non-US state requirements apply, or maximum runtime portability is itself a product requirement.
Run a bounded evaluation first: compare the same task set against an application-owned loop, recording verified completion, failed tool actions, operator intervention, recovery time, and cost per verified success.

The decision rule is simple: adopt the managed harness only when the infrastructure it replaces is less valuable than the control it gives up. If policy, approvals, storage, or runtime behavior are part of the product, keep those boundaries in application code.

Figure 3: Adoption should follow state, policy, and differentiation constraints first—then be confirmed by controlled workload testing.

Tech Trend Insight Editorial Verdict

The Agents API is a credible way to stop rebuilding generic harness infrastructure, but public beta should not become the default merely because the first prototype is shorter. Its strongest fit is a durable, tool-heavy workload whose session state may remain in the United States and whose orchestration is commodity infrastructure. The Agents SDK is the stronger default when policy, approvals, storage, or runtime behavior are part of the product; direct Responses integration remains defensible for bounded workflows. The deciding artifact should be a measured state-and-side-effect map—not a feature checklist.

Figure 3: Illustrative photograph: lines of HTML codes. Image: Unsplash / Florian Olivo

Proposed Validation—Not Yet Run

This is a proposed experiment, not observed testing, and its thresholds are editorial choices rather than OpenAI benchmarks.

Compare three variants:

A: Agents API with a self-hosted sandbox.
B: Agents SDK using the same sandbox image and provider.
C: Responses API with an application-owned loop and the same sandbox.

Use 60 synthetic or permissioned tasks: 20 repository defect investigations, 20 multi-file implementation-and-test tasks, and 20 defensive incident-triage tasks. Run each task three times per runtime: 180 proposed executions per runtime and 540 total. Exclude production credentials and personal data.

Hold constant the model identifier, instructions, tool schemas, repository snapshot, dependency lockfiles, network allowlist, compute size, timeout, approval policy, and output schema. If a fixed model snapshot is unavailable, interleave runtime variants to reduce time-order bias.

Inject executor termination during a command, network disconnection, malformed tool output, context exhaustion, denied approval, workspace expiry, and ambiguous completion followed by retry.

Measure verified completion, test pass rate, unsupported claims, missing artifacts, duplicate side effects, root/subagent calls, token categories, tool calls, retries, p50 and p95 latency, total provider cost, cost per verified success, operator intervention, recovery after forced disconnection, and complete session-plus-compute teardown.

Proposed acceptance thresholds are:

Zero unapproved destructive or external actions.
Verified completion no more than two percentage points below the best application-owned baseline.
At least 20% less implementation-plus-operator time than the selected baseline.
Cost per verified success no more than 10% above baseline unless an agreed reliability or latency target justifies it.
Complete evidence for every side effect.
Confirmed deletion of requested API state and cleanup of customer-controlled compute and files.

Conclusion

OpenAI’s Agents API changes the build-versus-buy boundary for agent infrastructure. It can remove substantial session, orchestration, compaction, subagent, and recovery plumbing, but it does so by moving the control loop and retained state into a beta managed service.

Adopt it when that transfer is policy-compliant and measurably valuable. Otherwise, retain control with the Agents SDK—or keep a bounded workflow explicit through the Responses API.

FAQ

Does a self-hosted sandbox keep all Agents API data inside my infrastructure?

No. It places command execution and customer-managed files in the selected environment, but OpenAI still runs the harness and retains Agents API session state. Self-hosting does not make the endpoint ZDR-eligible. (Self-hosted sandboxes; Agents API overview)

How should teams compare the real cost of the three runtimes?

Use identical tasks, model configurations, tools, compute, retries, and acceptance criteria. Include model calls, cache categories, tools, containers, provider services, implementation work, operator intervention, and failure recovery, then report cost per verified successful task. (Observability; API pricing)

Which workloads should wait or use an application-owned runtime?

Wait—or use the Agents SDK or direct Responses integration—when architecture requires non-US Agents API state, ZDR, portable state, API-accessible trace export, application-owned policy enforcement, or contractually mature service guarantees. (Agents API overview; Service Terms)

Tech Trend Insight