OpenAI’s Agents API is a managed platform for building and running cloud agents that can work for long periods, use tools, operate inside sandboxed environments, coordinate subagents, and preserve intermediate work. OpenAI introduced the API in public beta on September 10, 2026, positioning it as a way for developers to use the same kind of agent harness and infrastructure that powers Codex without having to build every orchestration layer themselves.
That makes the Agents API more than another model endpoint. A model call answers a request. A production agent may need to inspect files, call APIs, run code, delegate work, recover from failures, preserve state, and continue operating for hours or days. The Agents API is designed around that broader execution problem.
This guide explains how the OpenAI Agents API works, how hosted sandboxes and subagents fit into the architecture, how it differs from the Agents SDK and Responses API, and what teams should think about before using it in production.
What Is the OpenAI Agents API?
The OpenAI Agents API is a managed agent runtime and orchestration layer. Instead of sending a single prompt and waiting for a single response, developers can define an agent’s model, tools, environment and task, while OpenAI manages the core agent loop and much of the surrounding infrastructure.
OpenAI says the service is built around the same harness and infrastructure behind Codex. The harness is responsible for the repetitive but difficult systems work that production agents need: maintaining context over long sessions, selecting and using tools, coordinating subagents, working with files, and keeping an execution moving across many steps.
The important distinction is this: the model reasons, but the harness keeps the work organized. In a real system, those are different responsibilities.
If you are new to agent systems, start with our broader guide to AI agents and autonomous systems. For the execution layer specifically, see our guide to AI agent runtimes, checkpoints and recovery.
Why the Agents API Matters
Teams have been able to build agents before the Agents API. The hard part has been operating them reliably. Once an agent moves beyond a short tool call, developers often end up building their own versions of:
- run state and session storage;
- tool routing and tool permissions;
- context compaction and memory policies;
- sandboxes for code and file execution;
- artifact storage;
- subagent orchestration;
- retries, checkpoints and recovery;
- concurrency controls;
- observability and evaluation hooks.
The Agents API is OpenAI’s attempt to move more of that burden into a managed platform. Developers still define what the agent is allowed to do, what knowledge it receives, and what tools it can call, but they no longer need to own every part of the runtime.
1. The Codex Harness Is the Core Idea
OpenAI describes the Agents API as giving developers managed access to an evolving Codex harness. In practical terms, a harness is the software layer around the model that decides how work is structured and executed.
A capable harness can:
- feed the model the right context at the right time;
- expose tools without overwhelming the model;
- persist intermediate results;
- separate planning from execution;
- delegate independent work to subagents;
- recover from interrupted execution;
- keep long tasks within operational limits.
This is closely related to context engineering. The problem is not simply giving an agent more tokens. The system needs to decide which information should stay in active context, which information belongs in files or memory, and which details can be summarized or retrieved later.
2. Long-Running Agents Are a First-Class Use Case
Many APIs are designed around request-response interactions that finish in seconds or minutes. Agent workloads can be very different. A research agent may need to collect evidence from many sources. A software agent may inspect a repository, make changes, run tests, fix failures and repeat. An operations agent may investigate an incident across several systems before producing a mitigation plan.
OpenAI says the Agents API is intended for sessions that can continue for long periods, including workflows that may span hours or days.
That changes the engineering requirements. Long-running work needs durable state, resumability, checkpoints, bounded retries, explicit cancellation, and safe handling of side effects. Those concepts are covered in depth in our guides to AI agent reliability engineering and agent transactions and compensating actions.
3. You Can Choose Where the Agent Executes Work
One of the more important design choices in the Agents API is the separation between the managed harness and the compute environment.
OpenAI says developers can use:
- OpenAI-hosted sandboxes for a managed execution environment;
- their own infrastructure when they need tighter control;
- integrated sandbox providers for different CPU, GPU, storage, security or VPC requirements.
At launch, OpenAI named ecosystem integrations including Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel.
This separation matters because the agent harness and the code execution environment have different trust boundaries. Model-generated commands should not automatically inherit unrestricted access to production credentials. A well-designed sandbox limits what the agent can read, write, execute and reach over the network.
For a deeper security model, see AI Agent Sandboxing Explained.
4. OpenAI-Hosted Sandboxes
OpenAI-hosted sandboxes provide managed environments where agents can work with files, run code and produce artifacts. Developers can configure the environment with the files, packages, skills and other resources required for a task.
This can remove a significant amount of platform engineering for teams that do not want to operate their own ephemeral compute layer.
But “managed” does not mean “risk free.” Teams still need to think about:
- which files are mounted into the environment;
- how secrets are supplied;
- which outbound network destinations are allowed;
- how long containers live;
- what artifacts are retained;
- how data is removed after a run;
- what happens if generated code behaves unexpectedly.
For high-risk workflows, a good architecture keeps powerful credentials outside the agent’s execution environment and exposes narrowly scoped tools instead.
5. Tools: MCP, Functions and Built-In Capabilities
The Agents API supports multiple ways for an agent to act on external systems. OpenAI specifically describes support for MCP, custom functions and built-in tools such as web search.
This matters because modern agents rarely succeed with one giant tool schema. A production system may have dozens or hundreds of potential capabilities. Tool discovery, permissions and context efficiency become system-level concerns.
For a detailed comparison of tool interfaces, see MCP vs APIs vs Function Calling.
Why MCP Is Important Here
MCP gives agents a standardized way to discover and call tools exposed by compatible servers. In an Agents API architecture, MCP can help keep the core agent configuration smaller while moving domain-specific actions behind purpose-built servers.
That does not remove the need for security. Every MCP server should still be treated as a permission boundary. Tool descriptions, arguments and outputs can all become part of the agent’s attack surface.
6. Subagents Let the System Parallelize Complex Work
OpenAI’s launch announcement highlights multi-agent support as a core capability. A primary agent can break a task into independent pieces and delegate those pieces to subagents. Each subagent keeps its own focused context, while the main agent coordinates the overall result.
This is useful when a task naturally decomposes. Examples include:
- one subagent investigating application logs while another checks deployment history;
- separate research agents analyzing different source groups;
- multiple coding agents working on independent modules;
- one agent implementing a change while another reviews it;
- parallel document extraction across many files.
Parallelism can reduce wall-clock latency, but it introduces new operational problems. You need concurrency limits, rate-limit awareness, shared-resource protection and a strategy for resolving conflicting outputs. Our guide to AI agent concurrency control covers queues, worker pools, backpressure and parallel tool calls in detail.
7. Agents API vs Agents SDK vs Responses API
These products overlap, but they solve different layers of the stack.
| Layer | Best description | Typical reason to use it |
|---|---|---|
| Responses API | Model interaction plus built-in tool primitives | You want direct control over your application loop and orchestration |
| Agents SDK | Open-source framework for building and orchestrating agents in your codebase | You want a programmable harness, handoffs, guardrails, tracing and sandbox integrations while keeping orchestration close to your application |
| Agents API | Managed cloud agent runtime and harness | You want OpenAI to operate more of the long-running session, context and multi-agent execution layer |
The choice is not necessarily permanent. A team may prototype with the Agents SDK, keep sensitive execution on its own infrastructure, and use the Agents API for workloads where managed orchestration reduces operational complexity.
OpenAI’s April 2026 Agents SDK update is especially relevant because it added a model-native harness, native sandbox execution, filesystem tools, memory and integrations designed for long-horizon work. The Agents API extends the managed side of that direction.
8. How a Production Agents API Workflow Might Look
The exact API surface can evolve during beta, so the following is conceptual pseudocode rather than a copy-paste quickstart:
// Conceptual example — verify the current OpenAI docs before implementation
const run = await agents.create({
model: "frontier-model",
environment: {
type: "openai_hosted"
},
tools: [
{ type: "mcp", server: "internal-docs" },
{ type: "function", name: "create_ticket" }
],
multiAgent: {
enabled: true,
maxConcurrent: 3
},
task: "Investigate the incident, delegate independent checks, and save a report."
});
The interesting part is not the syntax. It is the system boundary. Your application defines policy and capabilities. The managed harness runs the agent loop. The selected environment performs file and code execution. External tools expose actions. Subagents parallelize work where appropriate.
9. Production Pattern: Incident Investigation Agent
Consider an operations agent investigating elevated 5xx errors.
A robust workflow might look like this:
- The main agent receives the incident scope and service identifiers.
- A deployment subagent checks recent releases.
- A logs subagent analyzes error clusters.
- A dependency subagent checks upstream failures.
- Each subagent writes evidence into separate files or structured artifacts.
- The main agent compares findings and proposes likely causes.
- Before any destructive action, the agent requests approval or calls a tightly scoped remediation tool.
- The final report includes evidence, confidence, rollback options and unresolved uncertainty.
This is where multi-agent orchestration becomes useful. But the system still needs the same engineering controls as any distributed service: timeouts, retries, budgets and safe failure modes.
10. Production Pattern: Software Engineering Agent
A coding agent can use a sandbox to inspect a repository, edit files, run tests and generate artifacts without giving model-generated code unrestricted access to the host machine.
A safer workflow separates:
- repository access;
- package installation;
- build and test execution;
- deployment credentials;
- production promotion.
The agent may be allowed to modify code and open a pull request, while a separate deployment pipeline handles production release. This preserves a strong security boundary and aligns with the ideas in our guide to safe AI agent deployment and rollback.
11. Production Pattern: Research and Document Workflows
Long-running document analysis is another natural fit. An agent can receive a controlled workspace, split a corpus among subagents, extract evidence, compare conflicting sources and produce a structured report.
The key is to make evidence durable. Instead of relying only on the model’s active context, subagents should save citations, intermediate calculations and extracted facts to files or structured stores. The coordinating agent can then reason over a smaller, cleaner evidence set.
This reduces the risk that the final answer depends on information that was once in context but later summarized away.
12. Reliability: Managed Does Not Mean Automatic
The Agents API can reduce infrastructure work, but developers are still responsible for the behavior of their application.
Production agents should still implement:
Idempotency
If a tool call is retried, it should not accidentally create duplicate payments, duplicate tickets or duplicate database updates.
Timeouts and bounded retries
Every external dependency can fail. Agents should have explicit retry limits and escalation paths rather than looping indefinitely.
Checkpoints
Important progress should be externalized so a run can resume after a process, sandbox or network failure.
Circuit breakers
If a dependency is failing repeatedly, the agent should stop hammering it and move to a degraded or human-reviewed path.
SLOs and observability
Measure completion rate, latency, cost, tool failure rate, human-escalation rate and correctness—not just whether the model returned text.
These patterns are explained in more depth in AI Agent Reliability Engineering Explained.
13. Security Architecture for Cloud Agents
Long-running agents expand the attack surface because they can read more data, call more tools and take more actions than a simple chatbot.
A strong security model should assume that the agent can encounter malicious or misleading content.
Separate reasoning from authority
The model can decide what it wants to do, but the application should decide what it is allowed to do.
Use least-privilege tools
Prefer a tool such as refund_order(order_id, max_amount) over broad database credentials.
Keep secrets out of the sandbox when possible
Expose narrow capabilities rather than mounting long-lived credentials into an environment where generated code executes.
Validate high-impact actions
Payments, deployments, account deletion and irreversible writes should use explicit approvals, policy checks or separate trusted services.
Treat tool output as untrusted input
Web pages, documents and tool responses can contain prompt injection. The agent should not treat retrieved text as system-level authority.
14. Cost Model: Tokens, Tools and Compute
OpenAI’s developer announcement says there is no separate fee simply for using the Agents API; developers pay for the underlying model tokens and tools they use. OpenAI-hosted sandboxes are billed using standard container rates, with model usage billed separately.
That means an agent’s cost is not determined only by prompt length. A production budget may include:
- model input and output tokens;
- web search or other built-in tool usage;
- container runtime;
- third-party sandbox costs;
- MCP/API usage fees;
- storage and artifact retention;
- parallel subagent execution.
Subagents can improve latency, but they can also multiply simultaneous model and tool spend. Teams should use explicit budgets and concurrency controls. See AI Agent Cost Management Explained for a deeper treatment of token budgets, rate limits and Agent FinOps.
15. Evaluation Is Essential
An agent that works in a demo can still fail badly in production. Agents have a much larger behavioral surface than a single model call because failures can happen at planning, tool selection, argument generation, environment setup, execution, recovery or final synthesis.
Evaluate the workflow, not only the final answer.
Useful metrics include:
- task completion rate;
- correct tool selection;
- tool argument accuracy;
- recovery after partial failure;
- unsafe-action rate;
- human escalation quality;
- cost per successful task;
- latency by workflow stage.
Our guide to AI Agent Evals explains how to test autonomous workflows systematically.
16. When Should You Use the Agents API?
The Agents API is most compelling when your workload has several of these characteristics:
- tasks take many steps;
- runs may last much longer than a normal request;
- the agent needs a filesystem or code execution environment;
- the workflow benefits from subagents;
- you need durable artifacts;
- you do not want to operate the entire orchestration layer yourself;
- your application can tolerate a managed platform dependency.
17. When Might You Prefer the Agents SDK?
The Agents SDK may be a better fit when:
- you want orchestration logic inside your own codebase;
- you need to run the full harness in a tightly controlled environment;
- you want deeper customization of the agent loop;
- your compliance model requires more direct infrastructure ownership;
- you need portability across model providers or execution environments.
OpenAI describes the Agents SDK as open source and designed to support custom tool use, memory, sandbox environments and multi-agent workflows. It gives developers more control, but that also means owning more operational responsibility.
18. When Is the Responses API Enough?
Not every application needs an agent platform.
If your workflow is short, deterministic and easy to orchestrate in application code, the Responses API may be simpler. For example:
- one model call plus one or two tool calls;
- short retrieval workflows;
- structured extraction;
- simple support automation;
- workflows where your own service already provides durable state and queues.
Using a full agent runtime for a simple request-response task can add cost and complexity without creating value.
19. A Practical Decision Framework
| If you need… | Start with… |
|---|---|
| Direct model + tool calls | Responses API |
| Custom agent orchestration in your application | Agents SDK |
| Managed long-running cloud agents | Agents API |
| Controlled code/file execution | Agents SDK or Agents API + sandbox |
| Parallel subagents with less custom orchestration | Agents API |
| Maximum infrastructure ownership | Agents SDK + your own runtime |
20. Production Checklist
- Define the trust boundary: decide what the model, harness, sandbox and external tools can access.
- Use least privilege: give tools narrow permissions and short-lived credentials.
- Externalize state: do not rely on model context as the only record of progress.
- Design for retries: make side-effecting operations idempotent.
- Set budgets: cap tokens, tool calls, sandbox time and subagent concurrency.
- Add approval gates: require human or policy approval for high-impact actions.
- Instrument every stage: trace model calls, tools, errors, latency and cost.
- Evaluate failure cases: test malformed inputs, tool outages, prompt injection and partial results.
- Version prompts and policies: agent behavior should be deployable and rollbackable.
- Keep a recovery path: a failed sandbox or interrupted run should not destroy the entire workflow.
Frequently Asked Questions
Is the OpenAI Agents API generally available?
No. OpenAI launched the Agents API in public beta on September 10, 2026. Teams should expect the product surface to evolve during beta.
Does the Agents API replace the Agents SDK?
No. They serve different deployment preferences. The Agents SDK is an open-source framework you integrate into your code. The Agents API is a managed service that operates more of the agent harness and long-running execution layer.
Can Agents API agents run code?
Yes. Agents can work in execution environments that support files and code. OpenAI offers hosted sandboxes, and developers can also use their own infrastructure or supported sandbox partners.
Can I use MCP with the Agents API?
Yes. OpenAI lists MCP alongside custom functions and built-in tools as supported ways to give agents capabilities.
What are subagents?
Subagents are focused agents delegated a portion of a larger task. They can work in parallel with separate context while a coordinating agent combines their results.
Are OpenAI-hosted sandboxes included in model pricing?
No. OpenAI says hosted sandboxes use standard container rates, while model usage is billed separately according to the selected model and tools.
Should every agent use subagents?
No. Subagents are useful when work can be split into independent pieces. For short or tightly coupled tasks, additional agents can increase cost and coordination complexity without improving quality.
Final Takeaway
The OpenAI Agents API represents a shift from “call a model” toward “operate an agent.” Its value is not one new reasoning capability. The value is the managed system around the model: long-running sessions, context management, tools, sandbox execution, subagents and durable work.
For teams already building their own queues, session stores, sandbox integrations and orchestration layers, the Agents API may reduce a large amount of undifferentiated infrastructure. For teams that need maximum control, the Agents SDK remains a strong option. And for simple workflows, the Responses API may still be the cleanest architecture.
The important design decision is not which product sounds most advanced. It is how much of the agent runtime you want to own.
Related Vynula Guides
- AI Agent Runtime Explained (2026)
- AI Agent Sandboxing Explained (2026)
- Context Engineering for AI Agents (2026)
- AI Agent Deployment Explained (2026)
- AI Agent Concurrency Control Explained (2026)
- AI Agent Transactions Explained (2026)
- AI Agent Reliability Engineering Explained (2026)
- AI Agent Evals Explained (2026)
- MCP vs APIs vs Function Calling
Primary Sources
- OpenAI — Introducing the Agents API (September 10, 2026)
- OpenAI — The next evolution of the Agents SDK (April 15, 2026)
- OpenAI — New tools for building agents
