AIImpish
OpenAI Agents API Beta: Builder Migration From SDK to Managed Harness
Coffee Summary
- FACT (changelog Sep 10, 2026): OpenAI released the Agents API in public beta — build agents with a managed Codex harness while OpenAI handles session orchestration, context compaction, and recovery.
- FACT (docs): Durable sessions, streaming, your tools + MCP, and sandboxes: OpenAI-hosted, self-hosted, or supported providers; endpoint
POST /v1/agents/sessionswith headerOpenAI-Beta: agents=v1. - FACT (pricing/announcement framing): No separate Agents API fee — pay model tokens, tools, and hosted sandbox/container rates at standard prices.
- FACT (limits): Data residency currently US-only; Agents API does not support Zero Data Retention — self-hosted sandbox does not make it ZDR-eligible.
- OPINION: Migrate long-running sandbox agents to Agents API; keep Agents SDK / Responses when you must own the loop in-process.
What happened
OpenAI’s Sep 10 changelog shipped Agents API public beta, pointing builders to the Agents API overview and quickstart. The product surface is a managed Codex harness: you create a session with model, instructions, tools, and environment; OpenAI runs the agent loop, compaction, and recovery while you stream events or continue the same session_id.
This pack is a migration checklist for teams that already know the beta exists (see prior AIImpish explainer) and need a ship plan.
Why it matters
Homegrown agent loops break on the boring parts: session resume, context bloat, mid-turn steering, subagent fan-out, and sandbox lifecycle. Agents API productizes that layer. Choosing wrong — API vs SDK vs raw Responses — still burns weeks.
What changed
Runtime decision table
| You need… | Prefer | Why |
|---|---|---|
| Long-running coding/research with OpenAI managing state | Agents API | Managed harness, durable sessions, compaction, recovery |
| In-app control of loop, handoffs, approvals, storage | Agents SDK | Runner lives in your process |
| Direct model calls / custom agent from scratch | Responses API | Maximum control, highest integration effort |
| Embedded chat UI | ChatKit | Productized chat surface |
Builder migration steps
1. Permissions — Create a project API key with api.agents.read, api.agents.write, and api.responses.write. Keep the key outside the sandbox.
2. Beta header — Send OpenAI-Beta: agents=v1 (SDKs under beta.agents add it; cURL must set it).
3. Smoke test — Quickstart environment: { "type": "openai_hosted" } with a tiny script task (e.g. create/run tree.py); confirm agent.session.turn.completed and that tool success is real, not just stream noise.
4. Tools — Port MCP servers, programmatic_tool_calling, web_search, and multi-agent (max_concurrent_subagents) from your SDK config into session agent config.
5. Environment — Pick openai_hosted for speed-to-demo; self_hosted / partner sandboxes for VPC, GPU, or secret locality. Docs list partner options (e.g. E2B, Modal, Vercel, Daytona, and others on the launch materials).
6. Steering & continue — Save session_id; open the event stream before follow-up input; support mid-turn guidance where your product needs it.
7. Cleanup — Download artifacts, then DELETE /v1/agents/sessions/{id}; do not leave paid sandboxes idle.
8. Compliance gate — Stop if you require non-US residency or ZDR; Agents API is currently US-only and not ZDR-eligible even with self-hosted compute.
Who should care
- Teams replacing brittle custom Codex-like loops.
- Platform engineers comparing Agents API to Agents SDK ownership.
- Security/compliance reviewers (residency + ZDR constraints).
- Product builders shipping incident bots, issue investigators, or sandbox coding assistants.
Limitations
- Public beta: field names and behaviors can still change before GA.
- Hosted sandbox minutes and tool calls still cost money — “no Agents API fee” ≠ free agents.
- Completed turns ≠ every tool succeeded; watch
turn.failed/session.failed. - Prior AIImpish morning pack covered the launch narrative; this piece focuses on migration mechanics only.
- Do not invent unpublished regional or ZDR exceptions.
What to do next
1. Run the official quickstart end-to-end in a throwaway project.
2. Map one production workflow to Agents API vs keep-on-SDK using the table above.
3. Add session delete + spend alerts before any multi-hour agent jobs.
4. Re-read overview “data controls” notes with legal before enterprise rollout.
5. Keep a Responses fallback path until beta stabilizes.
AIImpish Take
Agents API is the “stop rebuilding the harness” release. Migrate when durability and sandbox orchestration are your bottleneck; stay on the SDK when policy, storage, or in-process control are non-negotiable. Check residency/ZDR first — architecture enthusiasm does not override compliance.
