OpenAI Agents API: A Practical Guide to Managed Agent Runtimes
Making one model call is different from operating an agent that reads files, uses tools, and works through several steps. The latter also needs progress records, execution permissions, recovery decisions, and a plan for keeping its outputs. The OpenAI Agents API exposes the Codex agent harness through an OpenAI-managed API. Its value is not simply a different model endpoint: it changes who operates part of the agent runtime.
OpenAI announced the public beta on September 10, 2026. This guide explains what the service manages, how it differs from the Agents SDK and Responses API, and how to evaluate it with a small, reviewable task rather than immediately handing it an entire business process.
Documentation checked: September 16, 2026.
- A managed harness coordinates work and tool use; it is not the model itself.
- Choosing a managed runtime does not decide your data permissions, external-system access, or approval policy for you.
- Long-running work may benefit from this model, but a simple one-off call does not automatically need migration.
1. What does a managed harness actually manage?
A harness is the execution framework around the model: it helps connect an input, tool use, intermediate results, and the next step. The official overview says OpenAI manages sessions, orchestration, context compaction, and recovery, while the application provides tools and chooses its execution environment. Think of this as a division of operational responsibility rather than a promise that every workflow is ready-made.
- Agent: the configuration of the model, instructions, available tools, and MCP servers.
- Environment: an optional sandbox or computer where the agent accesses files and runs commands.
- Session: a durable instance that can work on tasks and respond to further input.
- Events and items: the inputs and outputs used to follow what happened during the session.
For example, you can establish a research scope, inspect an intermediate result, and send another instruction to the same session. The managed harness also supports summarizing previous context and delegating independent work to subagents. That is not a guarantee of unlimited memory or automatically correct conclusions. Keep important constraints and evidence in reviewable output rather than assuming every earlier detail will remain unchanged.
Here, self_hosted means your app manages the workspace lifecycle, not that you self-host the OpenAI-managed harness. The none mode has no local command or file workspace, while remote MCP and application function tools remain possible. Use the boundaries in the official architecture guide when designing the integration.
2. Agents API, Agents SDK, or Responses API?
These are not three pricing tiers of the same product. The official runtime guide distinguishes where orchestration runs and who manages state and integration. Start with the degree of control your application actually needs.
| Option | Main role | Decision question |
|---|---|---|
| Agents API | OpenAI-managed Codex harness with saved session state | Do you want to reduce the work of operating infrastructure for longer agent tasks? |
| Agents SDK | Agent loops, tools, and handoffs inside your application | Do deployment, storage, approvals, and runtime integration need to remain under your app's control? |
| Responses API | Direct model responses and tools used to build your integration | Is composing model calls within the existing service the simpler starting point? |
A short classification or summarization feature can start with the model-call structure you already have. A workflow that repeatedly moves between files, tools, and follow-up instructions has more reason to evaluate a saved session and managed harness. If your team already operates a carefully integrated runtime and approval system, the word “managed” alone is not a reason to replace it.
3. Choose the environment and data boundary first
The documentation distinguishes an OpenAI-hosted sandbox, a self-hosted sandbox, and execution without a sandbox. First ask whether the task needs local files or command execution. An agent that answers questions or calls external tools without local file work may not need a sandbox at all.
Self-hosting the sandbox does not mean self-hosting the Agents API harness. Separate the managed coordination layer from the workspace in which code and files live. Decide which packages and network connections are needed, which inputs can enter that environment, and which outputs must be retained. Review external MCP servers and the data or actions they can access separately.
Data requirements can rule out a design before a pilot begins. At the time of checking, the official overview states that Agents API data residency is supported only in the United States and that Zero Data Retention (ZDR) is not supported. A self-hosted sandbox does not make the API ZDR-eligible. Teams with region-specific storage or no-retention requirements should resolve that fit before moving sensitive data into a test.
4. Three concrete workflows to evaluate
The following are design examples, not out-of-the-box guarantees. Each needs the appropriate data connections, tool implementation, and permissions. Define the deliverable and the human review point before deciding how much work to delegate.
Case 1: assemble an incident investigation brief
Goal and inputs: prepare the first investigation material for an on-call engineer. Supply redacted logs, deployment timestamps, a change list, and read-only status tools. Do not include production restart or configuration-write permissions simply because the workflow concerns an incident.
Flow: separate independent investigations, such as finding the first abnormal log entries and checking recent deployment changes, then combine the findings into a timeline. Require each finding to retain its source and observation time. Check that different time zones or stale records have not been incorrectly treated as the same event.
Output and review: request a timeline with observed facts, possible causes, and unanswered questions clearly separated. An engineer should decide whether the evidence supports a cause and approve any recovery action separately. Reducing information-gathering work and authorizing automatic remediation are two different decisions.
Case 2: investigate a repository's failing tests
Goal and inputs: collect the failing test output, relevant code changes, and sample files needed for reproduction. If execution is required, use an isolated environment without production credentials or real customer data. Specify the branch and commit under investigation so that findings can be tied to a known version.
Flow: investigate the failing location, recent changes, and differences between documentation and configuration before asking for a proposed fix. Require unverified dependency or environment assumptions to be recorded. The useful result is not just an explanation of an error message: it is a connection between the evidence and the proposed change.
Output and review: ask for reproduction steps, candidate causes, a patch proposal, and a list of tests checked versus tests still outstanding. A developer reviews the diff and runs the appropriate checks before deciding whether to merge it. A completed session is not evidence that the patch is safe or that every test passed.
Case 3: produce a repeatable release comparison
Goal and inputs: define the products, the previous baseline version, official release-note URLs, and the time period to compare. “How does this change affect our current workflow?” is easier to evaluate than an unrestricted request for everything new.
Flow: split the source review by product, identify changed features and support conditions, and combine findings into a comparison. Distinguish the first announcement from a document updated later. Leave unsupported cells marked as unresolved instead of inventing a symmetrical answer for every product.
Output and review: return the change, affected workflow, source and check time, and a small validation task the team could try next. A person decides whether the change is useful and worth its adoption cost. Parallel investigations can increase model and tool usage, so define non-overlapping scopes rather than repeatedly checking the same source.
5. A small pilot, from setup to review
- Write one success criterion. For example: organize the facts and follow-up questions from a sample incident log. Bound both the inputs and the expected deliverable.
- Prepare the project and key permissions. The official Quickstart specifies an application API key with
api.agents.read,api.agents.write, andapi.responses.write. Keep the key outside the agent's sandbox. - Choose the environment and minimum tools. Distinguish a task that needs file execution from one that only needs data retrieval. Check the current Quickstart for supported setup and model configuration rather than assuming every account or model is interchangeable.
- Create a session and submit one task. Record the session ID and progress events so that follow-up input and recovery can refer to existing work.
- Check the completion signal and the deliverable. The Quickstart says to look for
agent.session.turn.completed, but notes that this does not guarantee every tool succeeded. Do not treatagent.session.idlealone as proof of success. - Save what you need and clean up. Decide whether to retain the session for follow-up work or delete it after saving required files. If a stream disconnects, retrieve the saved session and items before retrying so that you do not unnecessarily repeat work.
Treat agent.session.turn.completed as one terminal turn outcome, not as a guarantee that every tool succeeded or that the report is correct. Idle status or a closed stream is not enough either: inspect output, tool results, and saved items. The official sessions guide explains the distinction.
6. Costs, permissions, and operational limits
Look beyond the model bill. The official overview separates model usage at the selected model's API rates, OpenAI tools at their standard rates, and OpenAI-hosted sandboxes at container rates. Record what a longer session, repeated research, and subagents actually consume during a small pilot. Managed does not mean free or a flat-rate unlimited service.
Connecting a tool is not the same as approving an action. Start with retrieval and review. Keep file changes, external publishing, deployments, payments, and other consequential actions behind an application-level approval workflow where appropriate. For MCP, review the operator, data transmitted, and permitted actions rather than relying only on a familiar server name.
A session and a sandbox are not the same resource. Follow the state and cleanup instructions for the runtime you choose. Establish what work can share a session, which artifacts must be saved, and who removes data no longer needed. Recovery features do not remove the need to check whether a retry might perform an external action twice.
The decision is how far to delegate
Agents API is worth evaluating when you want managed execution infrastructure and state for longer tasks. Compare it with Responses API for direct model integrations and Agents SDK for detailed control inside your application. Start with one task that fits your data requirements, then measure output quality, review effort, and cost. The first goal is a useful, repeatable result a person can verify, not maximum automation on day one.
Official sources
한국어로 읽기: OpenAI Agents API 한국어 가이드
Comments
Post a Comment