OpenAI Agents API migration is an infrastructure decision, not an SDK rename. OpenAI can now operate the Codex harness, sessions, orchestration, context compaction, and recovery, while your application still owns business tools, permissions, validation, and delivery. This guide turns that split into a testable migration contract.
Reading time: 8 minutes · About 1,550 words
TL;DR
- Map the three owners first: your application server, the managed harness, and the execution environment.
- Treat session state, tool authority, recovery, observability, and data controls as separate contracts.
- Benchmark the old and new runtimes on a frozen production task set.
- Keep a reversible adapter until failure recovery, denied actions, and total cost pass their gates.
- Public beta currently means US-only data residency and no Zero Data Retention, including with a self-hosted sandbox.
What OpenAI actually manages
OpenAI introduced the Agents API on September 10, 2026 as a public beta. The launch describes a managed service powered by the Codex harness, with long-running sessions, context management, tool use, and subagent coordination.
The detailed Agents API architecture draws a more useful boundary. A production system has three pieces:
| Layer | Primary owner | Main responsibility |
|---|---|---|
| Application server | Your team | Submit work, receive events, handle function tools, enforce business policy, deliver results |
| Agent harness | OpenAI | Run the model and tool loop, maintain the session, compact context, orchestrate work, support recovery |
| Environment | OpenAI, a partner, or your team | Execute code, expose files and network, manage compute and storage lifecycle |
This table corrects the most tempting migration mistake. One API call can create a session, yet production responsibility still spans all three layers. Managed orchestration removes repeated infrastructure work. It also moves failure boundaries, state semantics, and operational evidence into a new contract.
Audit 1: State ownership
An agent has more state than a conversation transcript. Inventory at least five categories before mapping the old runtime to the Agents API:
- Conversation state: instructions, messages, turns, items, and steering.
- Working state: files, generated artifacts, checkpoints, and intermediate results.
- Application state: customer record, workflow status, approval state, and idempotency key.
- External state: tickets, deployments, emails, payments, or any committed side effect.
- Evaluation state: task inputs, expected outcomes, traces, and review decisions.
The session documentation says a session keeps the agent configuration, conversation, and saved work over time. The management guide tells applications to store each session ID in their own data store.
That is the practical boundary: OpenAI retains session state, while your system still needs a durable mapping from a business object to its session. A recovery procedure cannot begin with search the dashboard. It should begin with a stable relationship such as:
business_workflow_id
-> agents_session_id
-> current_turn_id
-> last_verified_business_state
-> idempotency_key
Keep business truth outside the session. A session may explain what the agent attempted. Your system of record must prove what the business accepted.
Audit 2: Authority
A managed harness can choose and call tools. Your organization still decides which actions exist and which identity may perform them.
Build an authority matrix for every tool:
| Question | Required evidence |
|---|---|
| Who requested the action? | Authenticated user, service, and business role |
| What may the agent call? | Versioned tool schema and allowlist |
| What can the credential reach? | Source-system permissions and denied-path tests |
| Which actions require approval? | Risk class, approver, expiry, and approval receipt |
| What proves the final change? | Read-after-write result from the authoritative system |
OpenAI's sandbox security guidance is explicit: agent-generated code can access the files, credentials, and network visible to its environment. It recommends isolated workloads, approved network destinations, a restricted environment key, and keeping the application API key outside the sandbox. It also recommends credential brokers for third-party access.
Self-hosting the sandbox changes where code runs. It does not automatically solve tool authorization, secret exposure, or Agents API data retention. Those controls need their own tests.
Audit 3: Recovery
Recovery should be demonstrated with failure injection, not inferred from the word managed. Test four different failures because each has a different owner:
- Harness or turn failure: can the application identify the failed lifecycle event and safely continue or terminate?
- Tool handler failure: can a pending function call resume without executing the business action twice?
- Environment loss: which files survive, and can a replacement environment reconnect to the correct session?
- External partial success: if the tool committed a change and the response was lost, can the workflow detect the existing change before retrying?
The acceptance test should use committed state, not fluent output. For a ticket agent, success means the correct ticket changed once, the evidence is attached, and the customer received the intended result. A completed turn alone is an intermediate signal.
Audit 4: Observability and cost
The observability guide documents dashboard logs, session events, saved history, turn inspection, delegated command execution, and recorded token usage for root and subagent turns. It also states that trace retrieval and external trace exporters are outside the public beta API.
That leaves two practical questions for migration:
- Can your incident process retrieve enough evidence through supported interfaces?
- Can finance calculate cost per accepted business outcome rather than cost per model call?
Include root and subagent tokens, retries, tools, sandbox compute, partner charges, failed runs, and human review time. The launch says the Agents API has no separate fee, while model, tool, and hosted sandbox usage still carry their normal charges.
Customer results in the launch announcement include higher evaluation scores, lower latency, lower cost per case, and fewer failures. They are useful hypotheses. OpenAI does not publish the underlying task sets, sample sizes, or baselines there, so your frozen workload remains the decision instrument.
Run a reversible migration
Use a representative task set drawn from real production failures and common work. Freeze the inputs, expected outputs, permission boundaries, and scoring rules before testing either runtime.
Track at least these metrics:
| Metric | Why it matters |
|---|---|
| Accepted task rate | Measures business completion after review |
| Manual handling time | Captures hidden operational cost |
| P50 and P95 completion time | Exposes both normal and tail behavior |
| Cost per accepted task | Includes retries, tools, compute, and review |
| Denied-action accuracy | Tests least privilege and approval boundaries |
| Recovery success rate | Measures continuation without duplicate effects |
| Diagnosable failure rate | Shows whether operators can locate the failed layer |
Then migrate in four stages:
- Adapter: place old and new runtimes behind one internal task, tool, and result interface.
- Shadow: run the Agents API on copied or read-only inputs without business writes.
- Controlled write: enable low-risk, reversible actions with read-after-write verification.
- Cutover: move broader traffic only after quality, recovery, security, observability, and cost gates pass.
Keep the adapter until rollback has been exercised. The ability to inspect the open-source Codex harness is useful, while it does not establish behavioral equivalence with the hosted service. Portability must come from your own interfaces and tests.
Current public beta constraints
The Agents API overview currently states that session data residency is limited to the United States and Zero Data Retention is unsupported. A self-hosted sandbox does not make the Agents API ZDR-eligible.
Treat those as dated constraints, verified on September 11, 2026. Public beta surfaces can change quickly. Recheck retention, region support, pricing, API schemas, and observability before each production expansion.
FAQ
Agents API or Agents SDK: which should I choose?
Choose the Agents API when managed sessions, orchestration, compaction, recovery, and optional hosted environments remove a real operational bottleneck. Keep the SDK or a custom runtime when harness behavior, cross-provider routing, or full deployment control is part of your product differentiation.
Does a self-hosted sandbox keep the whole agent in my VPC?
It keeps execution in your environment. OpenAI still operates the harness and session. The current documentation also says self-hosting does not provide Zero Data Retention eligibility.
How do I prevent duplicate business actions after a retry?
Give each business operation a stable idempotency key, record the authoritative result, and perform read-before-retry or read-after-write verification. Session recovery and business transaction recovery are separate mechanisms.
What is the minimum migration benchmark?
Use a frozen set of real tasks and failures. Compare accepted task rate, tail latency, human handling time, total cost, denied-action behavior, recovery, and diagnosability under the same inputs and policies.
The migration decision
OpenAI now offers a credible managed foundation for durable cloud agents. The strongest reason to migrate is a measured bottleneck in session, orchestration, compaction, or recovery infrastructure. The strongest reason to wait is a hard requirement around region, ZDR, exportable observability, or harness-level differentiation.
Next action: select 20 representative production tasks, add three injected failure cases, and run both runtimes behind the same tool adapter. A migration earns approval when the new system produces better accepted outcomes and preserves a tested way back.
References
- OpenAI. Introducing the Agents API, September 10, 2026.
- OpenAI. Agents API overview.
- OpenAI. Agents API architecture.
- OpenAI. Run and continue sessions.
- OpenAI. Manage sessions.
- OpenAI. Sandbox security.
- OpenAI. Observability and usage.