OpenAI Agents API Explained: How AI Agents Work, Tools, Sandbox, MCP and Pricing in 2026

For years, integrating artificial intelligence into software meant working with isolated, single-turn completions. An application dispatched a prompt, waited a few seconds for the model to generate text, and closed the connection. If the user’s request required reading an internal file, querying a database, or running a code script, the burden fell entirely on the software engineer to build custom glue code: storing conversation memory, orchestrating tool-execution loops, catching runtime exceptions, and feeding structured responses back to the model.

On September 10, 2026, OpenAI fundamentally shifted that developer workflow by introducing the Agents API in public beta. Instead of treating the language model as a disconnected text engine, the Agents API provides a managed runtime powered by OpenAI’s Codex harness. It handles session persistence, execution sandboxing, context compaction, and error recovery automatically—turning multi-step agentic workflows into a native, cloud-managed software primitive.

How OpenAI’s Agents API connects an AI agent with tools, MCP, sessions and execution environments. Conceptual editorial illustration.

Quick Takeaways: OpenAI Agents API at a Glance

Release Date: September 10, 2026 (launched in Public Beta).
Core Architecture: An OpenAI-managed Codex harness that oversees orchestration, session state, context compaction, and recovery loops.
Execution Sandboxes: Agents can run code, edit files, and generate artifacts inside isolated OpenAI-hosted sandboxes or secure self-hosted enterprise environments.
Tool & Protocol Support: Supports native function calling, skills directories, Programmatic Tool Calling, and the Model Context Protocol (MCP).
Pricing Structure: Metered on selected model API rates (such as GPT-6 Astra) plus standard charges for OpenAI tools and hosted container runtime compute.
Current Limitations: Public beta status, data residency restricted to the United States, and Zero Data Retention (ZDR) is currently not supported.

What Is the OpenAI Agents API?

Current OpenAI developer documentation positions the Agents API as the official starting point for building new agent applications. Rather than requiring developers to piece together third-party orchestration frameworks, vector caches, and custom subprocess runners, the Agents API bundles the operational machinery of an agent into a unified, managed service.

When an agent runs via the Agents API, it does not merely output text suggestions. It can plan a sequence of actions, execute shell scripts in a Linux container, inspect multi-file codebases, read contextual data from external services, recover from syntax errors independently, and stream progress events back to the client application in real time.

How the Agents API Architecture Works

The system decouples the developer’s client application from the execution environment. The client defines the task and supplies the allowed capabilities, while OpenAI's managed infrastructure handles the operational loops behind the scenes.

THE AGENTS API EXECUTION PIPELINE

    Client Application Submits Task

    ↓

    OpenAI Agents API (Session Coordinator)

    ↓

    Managed Codex Harness (Orchestration, Context Compaction & Recovery)

    ↓

    Tool Layer (Native Functions, Programmatic Tool Calls, Skills, MCP Servers)

    ↓

    Execution Environment (OpenAI-Hosted Sandbox OR Self-Hosted Infrastructure)

    ↓

    Completed Artifacts & Streamed Event Payload

The Four Core Concepts You Need to Know

To build effectively with the Agents API, developers interact with four foundational primitives:

Agent: The blueprint defining the personality, system instructions, default model (such as GPT-6 Astra), and the suite of tools or skills the system is permitted to use.
Environment: The physical or virtual computing runtime where tools execute commands and manipulate files. This can be a fully managed container hosted by OpenAI or a private endpoint within an organization's private virtual cloud (VPC).
Session: A durable, stateful interaction channel. Sessions persist across multiple conversation turns, preserving command history, environment states, and context compaction records without requiring the client to resend full chat transcripts.
Events and Items: The granular event stream emitted during an execution run. Clients subscribe to this feed to inspect internal reasoning steps, monitor tool call parameters, view file edits, and render real-time progress bars to end users.

What Can an Agent Actually Do?

The practical utility of the Agents API stems from the actions it is licensed to perform inside its assigned environment:

Multi-Step Reasoning: Break down abstract, high-level user instructions into sequential technical stages before executing them.
Code Execution & File Manipulation: Write scripts, compile programs, read local files, modify configurations, and inspect directory trees inside a secure shell.
Programmatic Tool Calling: Execute tools dynamically within code scripts without round-tripping every single tool call back to the host model over network hops.
Skills Loading: Pull specialized operational capabilities from modular capability directories inside supported environments.
MCP Server Connectivity: Query enterprise databases, external issue trackers, and SaaS endpoints using standardized connection protocols.
Artifact Production: Produce persistent deliverables—such as transformed datasets, compiled binaries, generated SVG charts, or finalized markdown documentation—ready for client download.

OpenAI Agents API workflow showing coding assistant, data analysis, MCP tools, and human approval controls — Comparison of OpenAI-hosted sandbox containers and self-hosted private cloud environments. Conceptual editorial illustration.

Execution Environments: OpenAI-Hosted Sandbox vs. Self-Hosted

Choosing an execution environment defines an agent's operational boundaries and security posture:

1. OpenAI-Hosted Sandbox

The hosted sandbox is a managed, isolated Linux container spun up on OpenAI’s cloud infrastructure. It requires zero infrastructure maintenance from the developer. The container comes equipped with standard developer runtimes, file storage, and command-line utilities. It is designed for applications that need to analyze uploaded spreadsheets, generate plots, run unit tests, or transform file formats safely away from corporate networks.

2. Self-Hosted Environment

For organizations with strict governance boundaries or private software stacks, the Agents API can connect to a self-hosted runner. Under this model, the Codex harness still manages the agent's logic and planning loops, but code execution and file modifications occur on the customer's own servers, Kubernetes clusters, or private cloud VPC. This setup allows agents to access proprietary internal APIs, legacy database engines, and custom hardware accelerators that cannot be exposed to public sandbox containers.

Choosing the Right Integration: Agents API vs. Responses API vs. Codex SDK

OpenAI offers multiple developer interfaces for interacting with its intelligence models. Understanding where the Agents API fits helps teams avoid rebuilding infrastructure that OpenAI already provides:

Dimension	Agents API (Managed)	Responses API (Direct)	Codex SDK (Self-Run Harness)
Primary Objective	Full-lifecycle, managed agent workflows with sessions and sandboxes.	Direct model integration, single-turn text completions, and custom agent loops.	Running OpenAI's Codex harness entirely on local or self-managed servers.
Orchestration Layer	OpenAI-managed Codex harness handles state, recovery, and compaction.	Developer writes and maintains the execution loop and state management.	Codex harness runs locally, controlled by developer code.
Execution Sandbox	Managed OpenAI containers or self-hosted runners.	None provided; developer executes tool outputs manually.	Self-managed containers or local host processes.
State Persistence	Native durable sessions stored on the platform.	Stateless; full message history must be resubmitted.	State stored in developer's local runtime memory or database.
Ideal For	SaaS builders, autonomous assistants, and background cloud agents.	Simple chatbots, custom pipeline orchestrators, and latency-critical tasks.	Air-gapped enterprise environments and bespoke platform engineering.

Native Model Context Protocol (MCP) Integration

One of the most consequential architectural choices in the Agents API is its native compatibility with the Model Context Protocol. Rather than forcing organizations to build proprietary connectors for every internal tool, the Agents API can connect directly to local and remote MCP servers.

As we detailed in our guide to MCP 2026 and how AI agents connect to apps and data, the open protocol decouples the reasoning engine from specific tool implementations. Through the Agents API, an enterprise agent can link to a GitHub MCP server, a PostgreSQL database connector, and an internal ticket management system simultaneously, discovering available tools dynamically at runtime under standardized OAuth 2.0 authorization rules.

Practical Real-World Use Cases

Software organizations are testing the Agents API across structured, multi-step problem spaces:

Automated Code Refactoring: Ingesting repository pull requests, identifying deprecated syntax, checking unit test coverage inside a sandbox, and generating clean commit diffs.
Financial & Data Analysis: Ingesting messy CSVs or transaction exports, writing Python data-cleaning scripts inside a container, and exporting verified summary tables and visual charts.
Site Reliability & Incident Triage: Reading server error traces, querying diagnostic endpoints via MCP connectors, reproducing bug conditions in an isolated shell, and compiling incident reports for engineering on-call teams.
Document & Compliance Auditing: Reviewing complex enterprise contracts against regulatory rule sets, verifying definitions across multiple annexes, and highlighting conflicting clauses in an executive briefing.
Business Workflow Automation: Handling multi-stage operations that connect communication channels, CRM updates, and inventory tracking without human intervention between routine steps.

Understanding Agents API Pricing in Plain Language

Because the Agents API orchestrates compute, storage, and multiple reasoning steps, its billing model reflects three separate components:

Foundation Model Token Costs: Input and output tokens consumed during reasoning and planning are billed at the standard published API rates for the selected model (such as GPT-6 Astra).
OpenAI Built-in Tools: Official OpenAI tools and capabilities (such as web search or file parsing utilities) are billed at their standard platform service rates.
Hosted Container Compute: When using OpenAI-hosted environments, developers are billed standard container runtime rates based on active compute time and memory allocation during code execution.

There are no arbitrary "agent subscription" fees; costs correlate directly to the compute resources, token volume, and execution minutes an agent requires to complete a given task.

Important Current Limitations and Considerations

While the Agents API streamlines agent development, engineering teams must evaluate several documented operational boundaries:

Public Beta Status: The API is in active development, meaning schemas, parameter conventions, and rate limits may evolve as OpenAI refines the platform.
US-Only Data Residency: Current documentation specifies that data residency for the Agents API is supported only within the United States. Organizations bound by strict regional sovereignty mandates (such as EU-only data requirements) must evaluate this constraint.
Zero Data Retention (ZDR) Not Supported: At present, Zero Data Retention is not available for Agents API endpoints due to the operational requirements of durable session state and container persistence.
State Mutation & Side Effects: Agents that modify external databases or create git commits can cause unintended downstream side effects if prompts contain ambiguities or encounter edge-case errors.

Security Architecture: Governing Autonomous Agents

Granting an AI system the power to write files and call APIs requires strict defensive programming:

Enforce Least Privilege: Restrict an agent’s sandbox permissions to only the files, directories, and network sockets strictly necessary for the immediate job.
Require Human Confirmation for Destructive Actions: Configure approval gates for tool calls that delete records, transfer funds, or push code directly to production branches.
Screen Third-Party MCP Servers: Only connect agents to trusted, authenticated MCP servers. Avoid routing untrusted public web text into an agent session that also holds credentials to sensitive internal databases.
Implement Continuous Evaluation & Auditing: Log session traces, track tool execution parameters, and inspect error recovery trajectories to catch prompt injection or agent drift early.

Context in the 2026 AI Agent Ecosystem

The launch of the Agents API is part of an industry-wide transition toward autonomous, agentic computing. Across developer tooling, platforms like Anthropic's Claude Opus 5.5 are driving down the cost of long-running terminal coding agents, while commercial platforms are introducing standardized checkout protocols seen in agentic commerce tools like ChatGPT, Gemini, and Meta Muse. By publishing a dedicated runtime API, OpenAI is establishing the cloud infrastructure layer designed to host these persistent agents at scale.

Who Should Use the Agents API?

SaaS Product Developers: Teams adding autonomous research, document processing, or code-editing capabilities into their existing software platforms.
Startups & Technical Founders: Builders who want to ship sophisticated agent applications quickly without building custom orchestration frameworks and sandbox management tools from scratch.
Internal Automation Engineers: Corporate developers building tools to handle multi-step back-office workflows, IT incident auditing, or data reconciliation.

Who May Not Need It Yet?

Not every application warrants an agentic runtime. If your application simply classifies user feedback, generates creative marketing copy, translates short paragraphs, or answers questions from a single knowledge base, the standard Responses API is simpler, faster, and more cost-effective. Agents add value when tasks require iterative reasoning, dynamic code execution, file changes, and multi-tool orchestration.

Frequently Asked Questions (FAQ)

What is the OpenAI Agents API?

The Agents API is an OpenAI-managed developer interface launched in public beta on September 10, 2026, that provides access to a Codex harness for running stateful, multi-step AI agents with native session management, sandboxes, and tool support.

When was the Agents API released?

OpenAI introduced the Agents API in public beta on September 10, 2026.

What is the Codex harness?

The Codex harness is OpenAI's underlying operational runtime that manages agent execution loops, state persistence across conversation turns, context window compaction, and automatic error recovery.

How does the Agents API differ from the Responses API?

The Responses API provides direct, single-turn model completions where the developer manages tool execution and conversation state manually. The Agents API provides a complete managed runtime with persistent sessions, isolated sandboxes, and autonomous tool calling.

What is the difference between an OpenAI-hosted sandbox and a self-hosted environment?

An OpenAI-hosted sandbox is a managed cloud container provided by OpenAI to execute code and edit files safely. A self-hosted environment connects the Codex harness to the customer's own cloud servers or private VPC to interact with internal infrastructure.

Does the Agents API support the Model Context Protocol (MCP)?

Yes. The Agents API supports connecting to local and remote MCP servers, enabling agents to discover and invoke tools across databases, code repositories, and external SaaS platforms using open industry standards.

How is the Agents API billed?

Pricing is based on the underlying model's API token rates, standard fees for official OpenAI tools, and container runtime compute charges for active hosted sandbox environments.

Does the Agents API support Zero Data Retention (ZDR)?

No. According to current official documentation, Zero Data Retention is not supported on the Agents API due to the requirements of stateful session management and persistent container environments.

What models are supported in the Agents API?

The Agents API supports OpenAI’s frontier reasoning and coding models, including GPT-6 Astra, with configurations defined within the Agent resource.

What is Programmatic Tool Calling?

Programmatic Tool Calling is a feature in the Agents API that allows an agent to invoke tools dynamically inside executable code scripts without requiring an individual network round-trip back to the model for every single tool invocation.

Conclusion

The OpenAI Agents API represents a mature evolution in AI platform engineering. By replacing fragile custom glue code with a managed Codex harness, durable sessions, and sandboxed containers, OpenAI has turned autonomous agent workflows into a standard, scalable API primitive. For engineering teams building the next generation of software assistants, data pipelines, and developer tools, the barrier to deploying persistent, tool-wielding AI agents has never been lower.

Sources & Official References

About the Author: Vishal Tiwari writes independent technology analysis, software architecture research, and developer guides for VISRAONJ / VISHAL TIWARI RESEARCH, covering AI agent runtimes, frontier models, cloud infrastructure, and emerging developer protocols.