Back to Blog

OpenAI Agents API Explained, What Changes for Teams Building Agents

In this article

• Quick Answer
• Key Takeaways
• What Is the OpenAI Agents API?
• What Does an Agents API Call Look Like?
• What Does the Managed Harness Do for You?
• Agents API vs Agents SDK vs Responses API
• How the Agents API Fits With Other OpenAI Agent Products
• Where Does the Agent Run?
• How Do Subagents Work in the Agents API?
• How Are Credentials Handled?
• What Does the Agents API Cost?
• Data Residency, Retention, and Security
• What Changes for Teams Already Running Agents?
• When Should You Use the Agents API?
• A Practical Adoption Checklist
• How Unico Connect Helps
• Frequently Asked Questions
• Sources

OpenAI released the Agents API in public beta on 10 September 2026. It gives developers the same harness that runs Codex, managed by OpenAI, so an application can start a long running agent with one API call instead of building its own loop for context, tools, and subagents. That changes who owns the hardest parts of an agent system, and it comes with limits that decide whether a regulated team can use it at all. This guide explains what the Agents API is, how it compares with the Agents SDK and the Responses API, what it costs, and what changes for a team that already runs agents in production. Every detail was checked against OpenAI documentation on 22 September 2026.

What Is the OpenAI Agents API?

The Agents API gives your application access to the Codex harness through an API that OpenAI operates. OpenAI describes the harness as the part that manages context, uses tools efficiently, and coordinates subagents, and it says the same harness and infrastructure power Codex. The harness itself is open source, so you can read the logic that coordinates model calls, tools, and context, while OpenAI runs and maintains it.

The API is built around four concepts.

1. Agent. The model, instructions, tools, and MCP servers available to the agent. You can pass it for one session or save it and reuse it by ID.
2. Environment. An optional sandbox or computer where the agent accesses files, loads skills, and runs commands.
3. Session. A durable instance of an agent that works on tasks and responds to input across turns.
4. Events and items. The inputs you send and the output the agent produces, available as a stream, through webhooks, or as saved history.

A session runs in a simple loop. You create it, give it a task, follow progress through streaming or webhooks, then continue or steer it by sending more input, including while it is mid turn.

What Does an Agents API Call Look Like?

This Python example from the OpenAI quickstart creates a session in an OpenAI hosted sandbox, gives it a task, and streams progress.

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,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

What Does the Managed Harness Do for You?

These are the parts that most teams used to build and maintain themselves.

• Context compaction. The API compacts earlier context automatically as a session nears its context limit, so work can span several context windows without your own summarization logic.
• Tool search. MCP tool definitions load as needed automatically when the model and provider support tool search. Your own function definitions load up front unless you add the tool_search tool and mark them with defer_loading. Deferred loading reduces token use and helps keep the prompt cache intact when an agent has many tools.
• Programmatic tool calling. On by default, so the agent can run tool calls in parallel, chain them, and filter results in code, bringing only the relevant output back into context.
• Subagents. The agent can split work into independent pieces and delegate them to subagents that run in parallel.
• Recovery and resumption. Sessions can resume where they left off.
• Tools and MCP. MCP servers, your own function tools, and built in tools such as web search.

OpenAI also says it versions and improves the harness alongside each model launch, so agents can benefit from new model capabilities without a harness rewrite. Our guide to context engineering for production AI explains why compaction, tool search, and subagents matter so much for agent quality.

Agents API vs Agents SDK vs Responses API

OpenAI now offers three ways to build an agent, and its own comparison makes the tradeoff clear.

The short version is that the Agents API trades control for speed. The Agents SDK keeps deployment, storage, and approvals in your application, and the Responses API keeps everything in your hands.

How the Agents API Fits With Other OpenAI Agent Products

The name overlaps with several OpenAI products. One of them has already shut down and another is being retired.

The Workspace Agents API is a different product again. It triggers agents that your team has already published inside ChatGPT from backend systems and automations, rather than giving your application its own agent harness.

Where Does the Agent Run?

Every session chooses an environment type, and the choice decides who manages compute and files.

Without an environment, the built in Bash and apply patch tools and workspace files are unavailable. For self hosted work, OpenAI names integrations with Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel, including fully managed environments and deployments inside your own VPC.

In a self hosted environment you run the Codex executor, codex exec-server, which registers with a restricted environment key and connects to OpenAI over WebSocket. All connections are outbound, and that key can only connect environments, not authorize other API actions.

How Do Subagents Work in the Agents API?

Set multi_agent.enabled to true when you create a session, and the harness supplies the tools to create, message, wait for, and interrupt subagents. You do not declare those tools yourself.

• Concurrency. max_concurrent_subagents defaults to 6, not counting the coordinator.
• Shared environment. The coordinator and subagents share one filesystem. Creating a subagent does not create another sandbox, so agents that edit the same files must coordinate.
• Tool inheritance. Subagents inherit configured MCP tools with their credentials, web search settings, and the environment files and command line tools. They do not support function tools.
• Observability. The event stream reports subagent creation and coordination items, and each turn carries a subagent_id, which is null for the main agent, so you can attribute every command.

OpenAI recommends subagents for independent tasks, such as reviewing separate documents or investigating different causes of a failure, and keeping short or dependent steps in the main agent.

How Are Credentials Handled?

Credentials live in vaults, separate from the agent instructions and configuration, and are attached to a session by ID. For MCP connections, OpenAI authenticates to the server with a stored bearer token or MCP OAuth credential. For API calls from an OpenAI hosted sandbox, the sandbox sees only a placeholder in an environment variable, and a network proxy swaps in the real secret for approved hosts over HTTPS on port 443 or 8443. Retrieving a vault never returns its secret values. That proxy pattern does not apply to self hosted environments or to your own function tools, which handle their own secrets.

What Does the Agents API Cost?

OpenAI charges no additional fee for the Agents API itself. You pay for model tokens at the normal API rates, for tools at their standard rates, and for OpenAI hosted sandboxes at container rates.

All model rates shown are short context rates. The gpt-5.6-sol rates are promotional pricing that OpenAI says is available at least through 21 November 2026.

The number to watch is cost per completed task, not cost per call. An agent may make many model calls, subagents make their own, retries count, and reasoning tokens are billed as output. OpenAI also notes that the Agents API usage fields do not expose a separate cache write count, so they cannot give the exact charge for models with cache write pricing. Our GPT-6 Astra guide covers the long context pricing cliff that applies once a request crosses 272,000 tokens.

Data Residency, Retention, and Security

This is the section that decides adoption for many companies.

• Data residency. The Agents API currently supports data residency only in the United States.
• Zero Data Retention. Not supported. OpenAI states that choosing a self hosted sandbox does not make the Agents API eligible.
• Training and logs. OpenAI lists the Agents API endpoint as not used for training and keeps abuse monitoring logs for up to 30 days. The endpoint is also not eligible for the Eyes Off and Safety Retention controls.
• Session state. OpenAI keeps session state until you delete it, so work can continue across turns, and you can delete sessions and published artifacts when you no longer need them.
• API keys. Sessions need a key with the api.agents.read, api.agents.write, and api.responses.write permissions, and OpenAI advises keeping that key outside the agent sandbox. Since 10 September 2026 you can set expiration dates on project API keys, and since 15 September administrators can restrict or disable new key creation.

For a team handling health data, EU personal data, or regulated financial data, the residency and retention limits usually settle the question before architecture does. In those cases the Agents SDK or the Responses API, with your own storage and retention controls, remains the safer route.

What Changes for Teams Already Running Agents?

If you already run agents in production, the Agents API changes the build in specific ways.

• You stop maintaining compaction and orchestration. That code, often the most fragile part of an agent, moves to OpenAI.
• State lives with OpenAI. Session history is stored on the platform, so your audit and deletion processes need to reach it.
• Some settings are fixed per session. You can change the model, reasoning effort, and service tier of a running session, but not its tools, instructions, or multi agent settings. Those need a new session.
• Saved agent changes apply only to new sessions. Existing sessions keep the configuration they were created with.
• Hosted sandboxes expire when idle. If activity and keep alives stop for an hour, OpenAI can delete an OpenAI hosted sandbox, and that timeout is not configurable. Files written to /workspace/outputs are published as artifacts when a turn completes and stay downloadable after the sandbox expires, so write anything you need to keep there.
• Function tools need a live handler. If your handler is unavailable, the agent can remain waiting for a result, so treat that handler as production infrastructure.
• Observability moves to the platform. The dashboard shows sessions, turns, tool calls, and subagents, and traces can be exported as OTLP JSON, but turn usage is best effort and can be null, and truncated command output is not flagged.
• It is a beta. OpenAI says it will iterate quickly toward general availability, so pin SDK versions and expect changes.

When Should You Use the Agents API?

A Practical Adoption Checklist

1. Confirm the data rules first. Check that United States residency and the lack of Zero Data Retention are acceptable for the data the agent will touch.
2. Pick the environment. Start with no environment for tool only agents, a hosted sandbox for quick prototypes, and a self hosted or partner sandbox when you need your network or custom software.
3. Put secrets in vaults. Keep tokens out of instructions, prompts, and files, and scope hosted secrets to exact hosts.
4. Scope and expire keys. Use restricted keys with only the agent, responses, and vault permissions you need, and set an expiry.
5. Budget per task. Measure token use across root and subagent turns on real tasks before setting limits.
6. Wire observability early. Export traces to your own tooling and alert on sessions waiting for a function result.
7. Plan for change. Pin versions during the beta and keep your prompts, tools, and evaluations portable.

How Unico Connect Helps

We build production agents on OpenAI, Anthropic, and open models, and we choose the runtime to fit the data rules rather than the other way round. For example, the AI ticket triage agents we build classify and route inbound tickets, automating about 75 percent of routing with a per ticket audit trail. Our agentic AI development team can prototype on the Agents API, move a workload to the Agents SDK or your own stack when residency or retention requires it, and set up the evaluations, cost tracking, and approvals a production agent needs. For planning, see our guides to AI agent development cost, durable execution for AI agents, AI agent security and prompt injection, single agents and multi agent systems, and MCP in production. If you are staffing the build, you can hire AI engineers, with vetted candidates within a week, or talk to our team.

Frequently Asked Questions

Sources

Launch details come from the OpenAI announcement Introducing the Agents API and the API changelog. Technical details come from the Agents API overview, the agent runtime comparison, the tool search guide, the programmatic tool calling guide, and the architecture, configuration, environments, multi agent, vaults, observability, and quickstart guides. Retention terms come from the Your data guide. Product status comes from the deprecations page, the Assistants migration guide, and the Agent Builder migration guide. Prices come from the OpenAI pricing page and the GPT-5.6 Sol model page. All were read on 22 September 2026.