OpenAI Agents API quickstart: hosted sandboxes and the Agents SDK difference

OpenAI released the Agents API in public beta on September 10, 2026. The new part is not another model. It is API access to the agent harness behind Codex. OpenAI runs session state, orchestration, context compaction, and recovery; developers choose the model, tools, and execution environment.

That makes the API a fit for work that edits files, runs commands, creates artifacts, or continues across several turns. A short answer or one-off tool call is usually simpler through the Responses API. If you want the agent loop and handoffs to run inside your application, the open-source Agents SDK gives you more control.

Public beta at a glance

• Released: September 10, 2026
• Availability: public beta for all developers
• Managed layer: the Codex harness, sessions, orchestration, context compaction, and recovery
• Compute choices: no environment, an OpenAI-hosted sandbox, or a self-hosted environment
• Sandbox partners: Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel
• Charges: no separate Agents API fee; model tokens, tools, and OpenAI-hosted containers are billed separately

Public beta is a warning label as much as an availability milestone. OpenAI says API details, defaults, and supported capabilities may change before general availability.

What the Agents API manages

The API has four core objects: agent, environment, session, and event. An agent contains the model, instructions, tools, and MCP servers. The optional environment is where commands and file operations run. A session is the durable unit that keeps conversation and work state. Events and items expose progress and saved output.

The managed harness can run commands, apply skills, connect to MCP and external tools, accept steering during a turn, compact older context, delegate to subagents, and resume a session. Your application submits tasks, consumes events, and handles function tool requests.

Python quickstart

Create an application API key in an OpenAI Platform project. It needs api.agents.read and api.agents.write for session operations, plus api.responses.write for inference. Keep this key in the application, not inside the sandbox.

python -m venv .venv
. .venv/bin/activate
pip install --upgrade openai
export OPENAI_API_KEY="your-api-key"

This minimal example follows OpenAI’s official quickstart. One request creates a session, provisions a hosted sandbox, asks the agent to write and run tree.py, and streams the events.

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)

python quickstart.py

Treat agent.session.turn.completed as a signal to inspect the agent’s reported execution result, not as proof that every tool succeeded. An agent.session.idle event alone does not mean the turn worked. If the stream drops early, retrieve the saved session and its items before retrying the task.

The SDK adds the beta header automatically. Direct cURL requests must include OpenAI-Beta: agents=v1.

What the hosted sandbox provides

Set environment.type to openai_hosted to get a Linux workspace with Python, Node.js, and command-line tools. Its working directory is /workspace. You can install Python, system, or global npm packages; upload files through the Files API or inline base64; and configure setup commands, environment variables, skills, and plugins.

Network access has three modes. enabled permits outbound traffic and is the default. disabled blocks it. restricted allows only the 1 to 100 exact hostnames in allowed_domains. Wildcards, protocols, paths, and ports are not accepted, and redirects or subdomains need separate entries. Start with disabled or the narrowest practical allowlist rather than leaving the default open.

Every session gets a separate workspace. Files persist between turns while the sandbox exists. On turn completion, files under /workspace/outputs become immutable artifacts that remain downloadable after the sandbox expires. A connected sandbox can be deleted after one hour without activity or keep-alives, and that timeout cannot be configured. Save needed artifacts, then delete the session to request cleanup.

Choose self_hosted when you need a custom image, your own compute, or a private network. You run codex exec-server on a laptop, container, or remote sandbox and connect to the Agents API over an outbound WebSocket. This gives you the infrastructure boundary, but it also leaves provisioning, reconnection, shutdown, and file retention to your application. Partner sandboxes fit at the same boundary.

Use environment.type: "none" when the agent does not need a filesystem or shell.

Pricing

There is no separate platform fee for the Agents API. The bill comes from model tokens, built-in tools, and hosted containers. On the official price sheet checked September 16, 2026, standard short-context gpt-6-astra pricing is $10 per 1 million input tokens, $1 for cached input, $12.50 for cache writes, and $50 for output.

Hosted containers cost $0.03 for 1 GB, $0.12 for 4 GB, $0.48 for 16 GB, or $1.92 for 64 GB per 20-minute session. The same price sheet says eligible container sessions are billed by the minute with a five-minute minimum. Web search costs $10 per 1,000 calls for all models, with search content tokens charged at the selected model’s rate. Check the live pricing page before deployment because these figures can change.

Agents API vs. Agents SDK vs. Responses API

With the Agents API, OpenAI operates the harness. Your application talks to a session-oriented API while OpenAI handles orchestration and recovery. You still choose whether compute runs in an OpenAI-hosted, self-hosted, or partner environment.

Sandbox agents in the Agents SDK put the harness on the application side. Your code assembles the runtime with Runner, SandboxAgent, Manifest, and a sandbox client. You can swap local Unix, Docker, and hosted providers while controlling handoffs, guardrails, hooks, and lifecycle in code.

The Responses API is the lower-level starting point for a direct model response or built-in tool call. If the task needs neither a durable session nor a stateful workspace, adding the Agents API is extra machinery.

The practical dividing line is ownership. Use the Agents API when you want OpenAI to operate the Codex harness and keep durable sessions. Use the Agents SDK when the agent loop belongs in your application. Use the Responses API for short, direct calls.

Security boundaries and beta limitations

Agent-generated code can reach any files, credentials, and network endpoints exposed to its environment. Treat each sandbox as a trust boundary and isolate it by user or workload. Keep the application API key outside the environment. A self-hosted executor should receive a restricted CODEX_API_KEY that can only connect an environment. Do not bake long-lived credentials into images, source, or logs. A credential broker is safer when it can inject secrets only into approved outbound requests.

Keep MCP and tool permissions narrow as well. Read-only work does not need write access, and external side effects should have an approval step. A sandbox does not solve prompt injection. Untrusted files and web pages can still influence the agent, so tool permissions and network policy must assume hostile content.

The Agents API currently supports data residency only in the United States and does not support Zero Data Retention. A self-hosted sandbox does not make the API eligible for ZDR. OpenAI-hosted sandboxes are also the wrong choice when a job needs a custom image or private network; use a self-hosted environment in those cases.

For this article, the Python SDK 3.14.1 installation, OpenAI import, client.beta.agents.sessions.create surface, and example syntax were checked locally. No paid API call or hosted-sandbox end-to-end run was made because no API key or spending authorization was provided.

Who should use it now

Teams building coding assistants, document reviewers, incident investigators, or similar systems that need files, commands, intermediate artifacts, and multi-turn state have a good reason to evaluate the beta. The strongest case is a product that needs durable agent work but does not want to operate context compaction and recovery itself.

Wait if your service requires ZDR, residency outside the United States, or an API contract that will not move during beta. A basic chatbot or single tool call is also better served by the Responses API, with less structure and less cost to reason about.

Sources

• OpenAI: Introducing the Agents API
• OpenAI Developers: Agents API overview
• OpenAI Developers: Agents API quickstart
• OpenAI Developers: OpenAI-hosted sandboxes
• OpenAI Developers: Self-hosted sandboxes
• OpenAI Developers: Sandbox security
• OpenAI Developers: Sandbox Agents in the Agents SDK
• OpenAI API pricing

Verified: September 16, 2026