Writing ·
What does the OpenAI Agents API manage—and what must your application own?
Use the OpenAI Agents API when an OpenAI-managed Codex harness and durable sessions remove mechanics you do not need to operate; keep tool authority, execution-environment choice, application state, and consequential-action policy explicit in your application.
By Youssef Hemimy · OpenAI · agent workflows · AgentOps
Use the OpenAI Agents API when an OpenAI-managed Codex harness and durable sessions remove mechanics you do not need to operate. Keep tool authority, execution-environment choice, application state, event handling, and every consequential action explicit in your own application. Managed does not mean blank cheque. Shocking, but useful.
Managed harness
OpenAI Agents API
- Sessions and saved progress
- Orchestration and context compaction
- Recovery and run events
Application control plane
Your workflow
- Tools and their authority
- Execution environment selection
- Business state and action approval
Application-owned evidence
Reconcile each event to the business request, authorization decision, idempotency key, and completed effect. A managed session is useful; it is not the system of record for your side effects.
Start with the ownership boundary
OpenAI describes the Agents API as an OpenAI-managed Codex harness. It manages sessions, orchestration, context compaction, and recovery, while the application provides tools and chooses the execution environment. The runtime comparison positions it for long-running work where OpenAI manages the agent and saves progress.
| Concern | Managed-harness capability | Application decision |
|---|---|---|
| Session mechanics | Sessions, orchestration, compaction, recovery | Which business request owns a session; when it continues or ends |
| Agent configuration | Configured model, instructions, tools, and MCP connections | Which configuration and tool surface are approved for this workflow |
| Execution | OpenAI-hosted, self-hosted, or no environment | Which reach, data boundary, and effect are appropriate |
| Progress | Events and items for task input and output | How events update job state, retry safely, and notify operators |
| Consequential actions | Tools can connect models to functions, services, MCP, or an environment | Who authorizes the exact write, payment, deletion, or external message |
Make configuration a production artifact
OpenAI's configuration guide says an agent configuration includes the model, instructions, tools, and reasoning/output controls. It can be supplied when creating a session or saved for reuse. A session holds conversation and work; a saved agent holds reusable settings. When a session overrides tools, the supplied list replaces the saved tool list instead of merging with it.
Give that surface an owner, a version, and a review path. For every tool, record its effect, caller context, deterministic precondition, retained evidence, and failure behavior. That is the discipline behind production agent tool contracts: the prompt may propose an action, but an application-owned boundary decides whether and how it reaches a side effect.
Choose the environment per risk
The current guide documents three environment choices: none, openai_hosted, and self_hosted. For a self-hosted environment, the application prepares the compute and connects an executor. That makes environment selection a workload decision, not a brand preference.
| Workload | Decision to make | Evidence before promotion |
|---|---|---|
| Planning or text work | Whether an environment is needed at all | No accidental path to a write-capable tool |
| Bounded file or code work | Filesystem, package, and network reach | A test shows unapproved secrets and destinations are unreachable |
| Production-system action | What can be proposed versus executed | An authorization or approval result binds to the intended effect |
| Internal executor integration | Who operates compute and recovers disconnection | A repeated event cannot create a second external effect |
Own the state around the session
The overview says sessions retain state so work can continue across turns, and that sessions and published artifacts can be deleted when no longer needed. Keep a separate durable application record for the business request, active configuration, consumed event, idempotency key, completed effect, and operator controls. That record lets a team distinguish “the run resumed” from “the customer refund was sent twice.”
Treat API events as inputs to that record, not as a substitute for it. Connect the resulting state to an agent observability dashboard so an operator can see the run, its tool behavior, and its recovery path together.
Treat data controls as a selection constraint
The current overview says Agents API sessions retain state, data residency is currently supported only in the United States, and Zero Data Retention is not supported. Do not stretch that into a statement about every connected tool, MCP server, sandbox, self-hosted executor, or downstream business API. Evaluate the entire configuration and its data paths before moving sensitive work into production.
The application-owned side also needs a deliberate workload identity. For that separate decision, see OpenAI workload identity federation. Authentication to the platform is not the same thing as authority for a business effect.
Run an ownership test before production
- Create a session from the exact configuration you plan to approve.
- Use a controlled tool boundary that cannot make an irreversible effect.
- Reconcile every progress event to the application's job record.
- Force an interruption and show that recovery or retry does not duplicate the intended effect.
- Exercise cancellation, deletion, and escalation with the records an operator will use.
- Keep that evidence with the configuration version and tool contract.
Sources
FAQ
What does the OpenAI Agents API manage?
OpenAI documents the Agents API as a managed Codex harness that manages sessions, orchestration, context compaction, and recovery. Applications still provide tools and choose the execution environment.
Can an application use its own compute?
Yes. Current configuration documentation lists no sandbox, an OpenAI-hosted environment, and a self-hosted environment. For self-hosted execution, the application prepares the compute and connects an executor.
Does a managed session authorize business actions?
Do not assume so. The documented managed boundary covers harness and session mechanics. An application should make the authorization, approval, idempotency, and evidence for each consequential tool action explicit.
Does the Agents API support Zero Data Retention?
The current Agents API overview says Zero Data Retention is not supported and that data residency is currently supported only in the United States. Recheck the documentation and the entire connected data path for the exact configuration before making a retention or residency decision.
Building something that has to hold up?
We do this work for teams — agent reliability hardening, custom MCP servers, and full-stack AI systems built to survive production.