OpenAI Agents API — OpenAI’s managed service for running cloud-based AI agents. It gives your application access to the Codex harness — the same scaffolding that manages the model and tools in Codex. OpenAI handles sessions, orchestration, context compression, and recovery after failures, while the developer defines the agent, connects tools, and chooses where code runs. The API entered public beta on September 10, 2026. There is no separate fee for the API itself: you pay for model tokens, tools, and sandbox time (OpenAI documentation, changelog).
This article is for developers, technical leaders, and business owners choosing an agent platform. We cover architecture, environments, tools, pricing, beta limits, and use cases where the service is or isn’t a fit. A comparison with Claude Managed Agents is covered in a separate article, and this text is not a substitute for legal review of a specific project.
Editorial team: Vladimir Lomtev’s AI Studio. Prepared on October 4, 2026 based on OpenAI’s official documentation, verified on that date. The editorial team did not test the service itself: code samples and results are taken from the documentation and are labeled. The article is published on the website of Vladimir Lomtev’s AI Studio, which implements AI agents; the services section appears before the conclusion. There are no affiliate links or compensation from OpenAI in this article.
In a nutshell
- Agents API runs the agent on OpenAI’s side: the provider stores the “model → tool → result” loop and session state.
- The agent can run code in an OpenAI sandbox, in your own infrastructure, or without a sandbox at all.
- Tools: your functions, MCP servers, web search, browser control, skills, and plugins.
- Pricing consists of model tokens, paid tools, and container time; there is no fee for the API itself.
- Beta limitations: data is stored only in the US; Zero Data Retention is not supported. Russia is not on the list of countries where the OpenAI API is available.
Contents
- What OpenAI Agents API is
- Agents API, Agents SDK, and Responses API: what’s the difference
- What Agents API consists of
- How a session works
- Environments: no sandbox, OpenAI sandbox, or your own
- Agent tools
- Secrets and security
- Subagents and multi-agent workflows
- How much Agents API costs
- Beta limits and restrictions
- Quick start in Python
- What happened to Assistants API and Agent Builder
- When Agents API is a fit, and when it isn’t
- Availability in Russia and legal considerations
- Frequently asked questions
What OpenAI Agents API is
AI agent — a program in which a language model plans steps on its own, calls tools, and takes their results into account until the task is complete. Harness, or agent harness, is the code around the model: it passes context to the model, executes tool calls, stores history, and decides what to do on error. Usually, the product team writes the harness. In Agents API, OpenAI provides it: according to the documentation, the API “runs Codex harness and manages agent infrastructure” (Agents API overview).
Codex harness is the harness that powers the Codex programming agent. In the launch announcement, OpenAI describes the new API as: “build and run cloud agents with Codex harness, fully managed by OpenAI” (OpenAI forum announcement). The runtime for your own sandboxes is included in the Codex CLI package, whose code is published in the Codex repository on GitHub. The managed harness includes running commands in a sandbox, loading skills and instructions, connecting external data through tools and MCP, adjusting the task on the fly, compressing history, delegating to subagents, and resuming a session from where it stopped (Agents API overview).
The timeline is short. Public beta opened on September 10, 2026. On September 29, the day of DevDay 2026, OpenAI added browser control (computer use) to Agents API (changelog, DevDay coverage in InfoQ). That is why some features are still marked as beta, and API contracts may change. We covered the DevDay announcements in the article “OpenAI DevDay 2026: All Announcements”.
Agents API, Agents SDK, and Responses API: what’s the difference
OpenAI has three ways to build an agent, and the key difference is where the agent loop runs and who stores its state. The documentation summarizes the differences in one table; below is our translation with abbreviations (Agents section).
| Criterion | Agents API | Agents SDK | Responses API |
|---|---|---|---|
| Purpose | Long-running tasks where OpenAI manages the agent and saves progress | Agents with your own tools and processes inside your application | Direct model calls or an agent built from scratch |
| Where the agent runs | Managed Codex harness on OpenAI’s side | A library inside your application | Your application, optionally with hosted orchestration |
| Integration effort | Low | Medium | High |
| State between tasks | Saved session settings, steps, and items | Your storage and SDK sessions | Manual history, response chains, or Conversations |
| Where code runs | OpenAI sandbox, your own sandbox, or no sandbox | Your environment and sandbox provider integrations | Your environment |
Responsibility differences. Agents SDK — an open-source library: you run and maintain the agent loop, task handoff between agents, and state storage yourself (Agents SDK repository). Agents API moves that loop to OpenAI: your app sends tasks and receives events. Responses API — the lower-level, single model call on top of which an agent is built manually.
The practical rule follows from the table. If you need full control over the loop, storage, and deployment, choose the SDK. If it is more important to quickly get a long-running agent with a sandbox and recovery, the Agents API is a good fit. For a single operation—classification, field extraction, answering a question from a document—an agent usually is not needed: one request to the Responses API is enough.
What the Agents API consists of
The API is built around four entities (Agents API overview):
- Agent — the model, instructions, tools, and MCP servers available to the agent.
- Environment — an optional sandbox or computer where the agent works with files, loads skills, and runs commands.
- Session — a long-lived instance of an agent that completes tasks and responds to input.
- Events and items — incoming messages and everything the agent produces during a session.
You can pass the agent configuration when creating a session or save it separately and reuse it via agent_id. Changes to a saved agent apply only to new sessions: each session copies the settings at the moment of creation. For an existing session, via POST /v1/agents/sessions/{session_id} only the model, the reasoning level (reasoning.effort), and the service level (service_tier) can be changed. Instructions, tools, and multi-agent settings cannot be changed that way—you need a new session (agent configuration).
Architecturally, there are three participants in the system (architecture). Harness runs at OpenAI and manages the model and tool loop. The environment executes commands and stores files; this can be a remote sandbox, a laptop, a Docker container, or an AWS Lambda function. Application server — your code: it sends tasks, receives events, handles function calls, and, if the environment is yours, manages its lifecycle.
How a session works
A session stores the agent configuration, conversation history, and saved work. Within a session, work is divided into turns. A message to an idle session starts a new turn, while a message during an active turn adjusts the current work (steering). Turns run asynchronously: progress is received through an event stream or webhooks (sessions).
A typical flow looks like this:
- The application creates a session with an agent and the first task. When hosted by OpenAI, the provider prepares the sandbox automatically.
- The task starts a turn as soon as the environment is ready.
- The application reads the event stream or waits for a webhook about completion or the need for input.
- The application sends the next task to the same session or adjusts the current one.
The documentation highlights several non-obvious points. The event agent.session.turn.completed means that the turn has ended, but it does not guarantee that every tool ran successfully — the result still needs to be checked. An idle status (agent.session.idle) or a closed stream also does not mean success. The stream does not replay missed events: after a disconnect, the application opens the stream again, loads the saved session items, and restores state by item_id (events and items).
For resending messages, the documentation recommends an idempotency key. Create the key once for a logical message and reuse it when retrying after a timeout so the agent does not receive the same task twice. When the agent needs the result of your function or an environment connection, the session moves to requires_action, and the list of pending actions is in the required_actions field (session management).
Webhooks are convenient if the application does not keep the stream open. Supported events include session creation, action required, work started, idle, and failure. Requests are signed, and the signature must be verified before processing (session webhooks).
Environments: no sandbox, OpenAI sandbox, or your own
The environment type is set by the environment.type field, and the choice determines who is responsible for compute and files (Architecture).
| Option | When to choose | What to consider |
|---|---|---|
none |
The agent answers questions or works with external services through tools | No built-in Bash or apply-patch, workspace files, or MCP running in the environment |
openai_hosted |
You need to run scripts, edit files, and create artifacts without your own infrastructure | Packages, files, and network are configurable; the sandbox is removed after one hour of inactivity |
self_hosted |
You need your own infrastructure, a private network, or specialized software | You handle startup, reconnection, shutdown, and file persistence |
OpenAI sandbox
The OpenAI sandbox is a Linux environment with Python, Node.js, and command-line tools; the working directory is /workspace. Before the agent starts, you can install Python packages, system packages, and npm packages, run setup commands, upload files, and set environment variables. A non-zero exit code from the setup command prevents the agent from starting. Repeated configuration is saved in an environment template (OpenAI sandboxes).
| Size | vCPU | Memory |
|---|---|---|
small |
1 | 1 GB |
medium (default) |
2 | 4 GB |
large |
4 | 16 GB |
There are three network access modes: enabled (default), disabled and restricted. In restricted mode, only the listed hosts are allowed — 1 to 100 exact hostnames with no wildcards, protocols, or paths. Subdomains and redirect addresses are added separately (OpenAI sandboxes).
Files persist as long as the sandbox exists. Anything the agent saves in /workspace/outputs, is published as an immutable artifact when the turn ends and remains available for download after the sandbox is deleted. The sandbox itself may be deleted if there is no activity or keep-alive signal for one hour; this timeout is not configurable. Closing the event stream does not cancel the task — to stop it, you need to cancel the turn (files and artifacts).
Self-hosted sandbox
In self_hosted mode, OpenAI still runs the harness, while the executor codex exec-server runs inside your environment. It executes commands, reads and writes files, and starts local MCP servers on harness request. All connections are outbound: the executor registers through https://api.openai.com and receives commands over WebSocket through wss://codex-cloud-environments.chatgpt.com (self-hosted sandboxes).
A separate environment key is created for the executor, which only allows environment connections. The app’s main API key is not passed into the sandbox: code generated by the agent can read everything in its environment. If the executor is not connected, the API waits up to five minutes for a connection, then the submission fails. Deleting the session does not stop your compute — you need to shut it down separately (sandbox lifecycle).
At launch, OpenAI named sandbox providers with ready-made integration: Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle Cloud, Runloop, and Vercel (OpenAI forum announcement). This is useful when you need GPUs, special memory configurations, or deployment in your own VPC.
Agent tools
The tool set is defined in agent.tools. Tools differ in where they run and who is responsible for their result.
Function tools. You describe a function with a JSON schema, the agent requests the call, your code executes it, and returns the result with the agent.session.input.tool_result event with the same turn_id and call_id. Results larger than 4 MiB will be rejected. For functions with side effects, the documentation recommends storing results by session, turn, and call: after a failure, check whether the operation was completed before running it again (functions).
{
"type": "function",
"name": "get_customer",
"description": "Look up a customer by ID.",
"parameters": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
}
}The example function definition is taken from OpenAI documentation.
MCP servers. Model Context Protocol is an open protocol through which an external server publishes tools for the model. In the Agents API, there are three ways to connect (MCP):
| Connection | Where the connection originates | Sandbox required |
|---|---|---|
HTTP, connection_origin: "service" (default) |
From OpenAI infrastructure | No |
HTTP, connection_origin: "environment" |
From the session environment | Yes |
| stdio | Process inside the environment | Yes |
The allowed_tools parameter limits which server tools the agent can see, and required: true causes the run to fail if the server did not start. For servers on an internal network, an environment-based connection is a good fit: the server does not need a public address.
Web search. Built-in search works in live, cached or disabled modes. It can be restricted to a list of up to 100 domains, and you can set a location for local queries. A prompt like “search the internet” does not enable search by itself—the tool must be configured (web search).
Browser control (computer use). The agent works in a browser hosted by OpenAI. Before the first visit to each new site, user approval is required; sign-ins are handled by your application. Approving a site does not guarantee approval for every action, so purchases and irreversible operations need separate oversight. The documentation says site content must be treated as untrusted: a page cannot grant permissions to the agent (computer use).
Tool discovery and programmatic calls. With a large function catalog, definitions can be loaded on demand: defer_loading: true plus the tool_search tool. Programmatic Tool Calling lets the agent call tools from code, in parallel and in chains (functions).
Skills and plugins. A plugin packages skills (instructions in SKILL.md) and MCP configuration. It is copied into your own sandbox as a directory, while OpenAI's sandbox receives it as a ZIP archive. After a plugin is changed, a new session is required: existing sessions do not reload tools (plugins).
Secrets and security
The core principle in the documentation: code generated by the agent has access to all files, credentials, and network resources in its environment (sandbox security). Four rules follow from this:
- Isolation. Different users and workloads should run in separate environments; for an application, use a separate OpenAI project.
- Least-privilege keys. The application key needs
api.agents.read,api.agents.writeandapi.responses.write, and for working with secret stores—api.vaults.read, andapi.vaults.write. - Network restrictions. Outbound traffic should be allowed only to required addresses.
- Secrets outside the sandbox. Third-party keys should not be placed in the environment.
For the last point, there are vaults. Credentials for MCP servers such as static_bearer or mcp_oauth is used by OpenAI itself when connecting to the server. The type environment_variable works differently: code in the sandbox sees only a placeholder, while a network proxy injects the real secret into HTTPS requests to approved hosts. That way, the agent can call, for example, the GitHub API without knowing the token (the store). The placeholder cannot be used for local computations such as signing a request — those operations are better left in the application and exposed to the agent through a function.
Removing credentials from the store does not revoke the original token at the provider or stop an active session. Your application handles revocation and cancellation. For more on protecting agents from malicious instructions, see our article “AI Agent Security”.
Subagents and multi-agent workflows
The parameter agent.multi_agent.enabled: true lets an agent delegate tasks to subagents. Each subagent has its own context, they can work in parallel, and the main agent coordinates them and gathers the result. Harness adds the tools for creating, sending messages to, waiting on, and interrupting subagents automatically. The limit on concurrent subagents is set by max_concurrent_subagents (multi-agent mode).
These constraints matter for architecture. Subagents use the shared environment and file system — no separate sandbox is created for them. They inherit MCP tools with their credentials and web search settings, but do not support functions. That means your backend calls should be made by the main agent. The documentation recommends giving subagents independent tasks — for example, analyzing different documents or testing different hypotheses about a failure — and leaving short, dependent steps to the main agent.
How much the Agents API costs
There is no separate fee for the Agents API. According to the documentation, the model is billed at its API rates, OpenAI tools are billed at standard rates, and OpenAI sandboxes are billed at standard container rates (Agents API overview). The cost of a task is made up like this:
Cost = tokens for all model calls (agent + subagents + retries) + paid tools + container time + third-party services.
Model rates as of October 4, 2026, standard processing, short context, USD per 1 million tokens (OpenAI pricing):
| Model | Input | Cached input | Output |
|---|---|---|---|
| gpt-6-astra | $10.00 | $1.00 | $50.00 |
| gpt-6.1-sol | $2.00 | $0.10 | $10.00 |
| gpt-6-luna | $0.10 | $0.01 | $0.50 |
According to the same page, containers cost $0.03 (1 GB), $0.12 (4 GB), and $0.48 (16 GB) per 20-minute container session. For eligible sessions, billing is by the minute with a 5-minute minimum. The small, medium and large sandbox sizes in the Agents API correspond to 1, 4, and 16 GB of memory. To see exactly how the rates apply to your bill, check the OpenAI usage dashboard.
Calculation example (illustration, not a forecast). Suppose an agent on gpt-6.1-sol processed 400,000 input tokens for a task, 250,000 of them from cache, generated 30,000 output tokens, and ran in a medium sandbox for 40 minutes: medium:
| Item | Calculation | Amount |
|---|---|---|
| Uncached input | 150,000 × $2 / 1 million | $0.30 |
| Cached input | 250,000 × $0.10 / 1 million | $0.025 |
| Output (including reasoning) | 30,000 × $10 / 1 million | $0.30 |
| 4 GB container | 40 min × ($0.12 / 20 min) | $0.24 |
| Total | $0.865 |
The calculation does not include cache writes, which have a separate price for these models, paid tools, or retries. The documentation warns that usage fields in the Agents API are filled in “best effort,” may be empty, and do not show cache writes separately, so they are not the final bill (observability and costs). A high cache share also does not necessarily mean savings on a task: cached tokens are billed, and the long history is reprocessed on every call.
What has the biggest impact on the bill:
- Model choice. The input rates for gpt-6-astra and gpt-6-luna differ by 100x.
- Length of history. Every model call rereads the instructions, tool definitions, and accumulated context.
- Number of subagents. Each subagent makes its own model calls.
- Sandbox time. Unclosed environment sessions keep billing; delete them after you're done.
Our breakdown helps compare cloud APIs and self-hosted deployment “Cloud or Local LLM: How to Compare TCO”, and the flagship model specs are covered in the overview GPT-6 Astra.
Beta Limits and Restrictions
| Parameter | Value | Source |
|---|---|---|
| Status | Public beta; requests with the header OpenAI-Beta: agents=v1 |
Quick Start |
| Data Storage | Data residency is US-only; Zero Data Retention is not supported, including with your own sandbox | Overview |
| Instructions + tool configuration | Up to 4 MiB | Setup |
| Request input | Up to 4 MiB | Sessions |
| Files when creating a session | 50 files; inline — 5 MiB per file and 10 MiB total; from the Files API — 50 MiB per file | Files |
| Artifacts | 200 MiB per file, 500 MiB per publication | Files |
| OpenAI sandbox idle timeout | Deleted after one hour of inactivity, not configurable | OpenAI sandboxes |
| Waiting for your sandbox | Up to 5 minutes | Lifecycle |
The data retention limit should be checked before making architecture decisions: the Agents API stores session state on OpenAI’s side so work can be resumed. Sessions and published artifacts can be deleted, but according to the documentation, physical cleanup may happen asynchronously (session management).
Quick Start in Python
The minimal example from the official quick start creates a session with an OpenAI sandbox, asks the agent to write and run a script tree.py and prints the event stream. The API key needs the permissions api.agents.read, api.agents.write and api.responses.write. Store the key outside the agent sandbox (quick start).
pip install --upgrade openai
export OPENAI_API_KEY="your-api-key"from openai import OpenAI
with OpenAI() as client:
with client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output.",
},
environment={"type": "openai_hosted"},
input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream=True,
).with_result_collection() as stream:
for event in stream:
print(event.to_json(indent=None), flush=True)
result = stream.get_final_result()
print(result.output_text)
session_id = result.session_idThe code is reproduced from OpenAI documentation as of October 4, 2026; the editorial team did not run it.
What to do next: save session_id, send a clarification to the same session, check the outcome of the run in the events, and delete the session after you're done. For an agent without code execution, environment={"type": "none"} is enough. In that case, the initial input is required at session creation.
Debugging is convenient in the logs panel: on the Agents tab, the session ID shows its runs, tool calls, and subagents. Tracing is enabled by default, and traces can be exported in OTLP JSON format (tracing).
What happened to the Assistants API and Agent Builder
The Agents API appeared as OpenAI’s agent tooling changed. In March 2025, the Responses API and the open-source Agents SDK were released (OpenAI). In October 2025, OpenAI introduced AgentKit with the visual Agent Builder (OpenAI). After that, some tools began to be phased out (deprecation page):
- Assistants API was turned off on August 26, 2026; the recommended replacement is the Responses API and Conversations API.
- Agent Builder was deprecated on June 3, 2026, with shutdown scheduled for November 30, 2026. For migration, OpenAI recommends Agents SDK or ChatGPT Workspace Agents. ChatKit remains available.
- The Evals platform will be shut down on November 30, 2026; starting October 31, existing evaluations will become read-only.
For teams that built agents on the Assistants API or in the visual builder, this is a reason to revisit the architecture. The Agents API is closer to the Assistants API in the “provider stores state” model, but it is designed for long-running tasks with a sandbox and tools.
When Agents API fits, and when it doesn’t
Suitable if:
- the task takes minutes or hours, involves multiple steps and code execution — data analysis, repository review, preparing a report with files;
- the team doesn’t want to write and maintain its own wrapper: state storage, context compression, recovery after failures;
- you need isolated code execution, and the sandbox infrastructure itself is not critical;
- the data and jurisdiction allow state to be stored in the United States with OpenAI.
It’s better to choose another option if:
- you need full control over the agent loop, storage, and deployment — then use the Agents SDK or your own wrapper;
- the requirements prohibit storing data with the provider or require Zero Data Retention: in the Agents API beta, there is none, and your own sandbox does not change that;
- the task boils down to a single model operation — an agent wrapper will add cost and latency without benefit;
- the application operates in a country that is not on OpenAI’s supported list — more details below;
- you need independence from a single vendor or model, deployed within your own environment.
One separate “against” argument is often underestimated. A managed wrapper does not eliminate engineering work entirely: function handlers, webhooks, cost control, recovery after stream interruptions, and access permissions still remain on your side. We covered how to validate the agent as a whole, not just the model, in the article “AI Agent Wrapper”. The levels of agent autonomy are described in the article “Managing AI Agent Autonomy”.
Availability in Russia and legal issues
As of October 4, 2026, Russia is not on the list of countries and territories where OpenAI supports access to its APIs. The same page states that using the services or providing access to them outside the listed countries may result in account blocking or suspension (supported countries). For Russian companies and products with users in Russia, this limitation is more important than any technical characteristics.
The second issue is personal and commercial data. Agents API stores session state in the United States and does not support Zero Data Retention. If the agent processes personal data, whether its transfer and storage abroad is permissible should be evaluated with a lawyer before development. This article is not legal advice.
If cloud APIs from foreign providers are unavailable or not suitable, consider models deployed in your own infrastructure and Russian cloud services. The architectural patterns of Agents API — long sessions, a sandbox with limited network access, secrets outside the environment, and validation of each step’s result — are also applicable to such systems.
Frequently asked questions
Do you have to pay for the Agents API itself?
No. According to OpenAI documentation, there is no separate fee for the API: you pay for model tokens at their rates, tools at standard rates, and OpenAI sandboxes at container rates. Your own sandbox is paid for through your provider.
How is Agents API different from Agents SDK?
Agents SDK is a library that runs the agent loop inside your application: state and deployment are your responsibility. Agents API runs the Codex harness on OpenAI’s side and stores sessions, compresses context, and restores operation itself. The SDK gives you more control; the API requires less infrastructure.
Can you run agent code on your own servers?
Yes. In self_hosted mode, the executor codex exec-server runs inside your environment with an outbound connection to OpenAI. The agent loop itself remains with OpenAI, so data retention requirements and the lack of Zero Data Retention still apply.
Which models work in the Agents API?
The documentation examples use gpt-6-astra. The model is set in the agent configuration; for an existing session, it can be changed if the new model supports the selected settings. Check the current list in the API reference — it may change in beta.
Does Agents API support MCP?
Yes. HTTP servers are connected from OpenAI infrastructure or from the session environment, and stdio servers run inside the environment. Credentials are passed in the session configuration or through vaults.
How do you control agent costs?
Choose a model matched to the task complexity, keep instructions and tool definitions stable for caching, limit the number of subagents, and delete sandbox sessions after work is done. Review per-step spend in Agents logs and in the usage fields, keeping in mind that they are not the final bill.
What happens to the sandbox if the agent is idle for a long time?
An OpenAI sandbox may be deleted after an hour without activity or keep-alive signals. Files in /workspace/outputs published as artifacts remain available. Other files should be saved in advance.
How Vladimir Lomtev’s AI studio helps implement a cloud AI agent
The choice between Agents API, your own wrapper, and a model in your own environment depends on the company’s process, data, and constraints, not on a single platform. Vladimir Lomtev’s AI studio designs AI agents integrated with communication channels and business systems, and deploys models, including on the client’s servers. For the tasks in this article, three areas of work are especially useful:
- process and data audit: which steps the agent needs, which systems it touches, and which data cannot be sent to an external service;
- developing an agent MVP with integration into CRM, ERP, or 1C, testing, and connecting tools with limited permissions;
- deploying and configuring a language model within the company’s environment if external APIs are unavailable or do not meet data requirements.
The first step is to describe one process: its current metrics, data sources, constraints, and the criterion for successful task completion by the agent. After that, it becomes clear which architecture is worth piloting. Discuss the task.
Conclusion
OpenAI Agents API is a managed option for agent development: OpenAI runs the Codex harness, stores sessions, compresses context, and provides a sandbox, while the team defines the agent and connects tools. This reduces the amount of infrastructure code needed for long-running tasks with files and program execution, but leaves function handlers, access permissions, cost control, and result validation on your side.
Before choosing, check three things: whether the jurisdiction and data storage model are acceptable, whether the beta limits are sufficient, and whether the task economics can handle the formula “tokens + tools + container.” If the answers are yes, start with one session without subagents, with limited network access and a measurable success criterion. If not, compare managed platforms from different providers or your own wrapper with a model in your own environment.