Quick answer: OpenAI’s new Agents API puts the managed Codex harness behind an API. It is available to all developers in public beta, can run long-lived agent sessions in an OpenAI-hosted sandbox, your own infrastructure or a partner sandbox, and has no separate Agents API fee.[1][2] You still pay for model tokens, tools and any hosted container use.[1]
Five-minute setup checklist
- Create an OpenAI Platform application API key with
api.agents.read,api.agents.writeandapi.responses.writepermissions.[4] - Upgrade the official SDK:
pip install --upgrade openai.[4] - Keep
OPENAI_API_KEYin your application environment—never place it inside the agent sandbox.[4] - Start with
environment={"type": "openai_hosted"}and disable network access unless the task genuinely needs the internet.[5] - Stream events and require
agent.session.turn.completed, then inspect the agent’s claimed output and artifacts; completion does not prove every tool succeeded.[4] - Save needed files from
/workspace/outputs, then delete the session when finished.[4][5]
Minimal Python quickstart
This example follows OpenAI’s current beta namespace and hosted-sandbox pattern.[4]
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. "
"Do not access the network."
),
},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
},
input=(
"Create tree.py, a Python script that prints a readable tree "
"of files in the current directory. Run it and show the output."
),
stream=True,
) as events:
for event in events:
print(event.to_json(indent=None), flush=True)
Run it with:
export OPENAI_API_KEY="your-api-key"
python quickstart.py
The SDK adds the beta header automatically. Raw HTTP requests currently require OpenAI-Beta: agents=v1.[4]
Verification note: The Python structure above was syntax-checked locally. It was not sent to the Agents API because this publishing environment does not have a separate OpenAI Platform API key authorized for Agents API billing.
What the Agents API actually manages
The Agents API is not merely another model-response endpoint. OpenAI manages sessions, orchestration, context compaction and recovery while your application chooses the tools and execution environment.[3]
OpenAI’s documentation defines four core objects:[3]
| Object | What it means |
|---|---|
| Agent | Model, instructions, tools and MCP servers |
| Environment | Optional sandbox or computer used for files and commands |
| Session | Durable agent instance that accepts tasks and follow-ups |
| Events and items | Inputs and outputs generated during the session |
The managed harness can run code, edit files, use skills, connect through tools or MCP, accept steering, compact earlier context, delegate work to subagents and resume a session later.[1][3]
Agents API versus Agents SDK versus Responses API
Use the Agents API when you want OpenAI to operate the Codex-style harness, preserve a durable session and coordinate sandbox work.[3] Use the Agents SDK when you want framework-level control inside your own application. Use the Responses API for direct model-and-tool calls where you do not need this managed long-running harness.
A practical decision rule:
- Choose Agents API for multi-step coding, incident investigation, document review or analysis that needs files, commands, recovery and follow-up turns.[3]
- Choose a direct Responses API workflow for bounded calls that your application can orchestrate itself.
- Keep a human approval gate before destructive changes, money movement, outbound messages or production deployment.
OpenAI’s own example applications include incident response, a Slack investigation bot, read-only data analysis, GitHub issue investigation and document review.[3]
Choose the right sandbox
OpenAI offers three broad execution choices: OpenAI-hosted, self-hosted and supported partner environments. The launch names Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel as integration partners.[1]
OpenAI-hosted
This is the quickest start.[5] The sandbox is a Linux workspace with Python, Node.js and command-line tools; its working directory is /workspace.[5]
Use it when:
- you want managed disposable compute;
- standard tools and packages are enough;
- supplied files can safely be processed in the hosted environment;
- you do not need a private network or custom base image.
Self-hosted
Use your own environment when you need a custom image, specialized compute or private-network connectivity.[5] Remember that self-hosting the compute does not make the Agents API eligible for Zero Data Retention.[3]
Partner sandbox
Use a partner when its region, lifecycle, compute, VPC or operational model fits your existing platform better.[1] Compare both OpenAI charges and the partner’s separate charges before choosing.
Network and secret safety
OpenAI-hosted sandboxes default to outbound network access unless a template policy changes that behavior. You can set access to disabled, enabled or restricted; restricted mode accepts exact hostnames rather than wildcards or URLs.[5]
Use this safer default:
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
}
If an agent needs one API, use restricted access and allow only the exact required hosts.[5] Redirect targets and subdomains must be listed separately.[5]
Do not inject your main OPENAI_API_KEY into the sandbox.[4][5]
OpenAI explicitly rejects that reserved environment variable, and the quickstart says to keep the key outside the sandbox.[4][5] For business systems, use short-lived, narrowly scoped credentials and provide only the permissions needed for the current task.
Files, artifacts and cleanup
Each session receives a separate workspace.[5] Files can persist across turns while the sandbox exists.[5] Files written under /workspace/outputs are published as immutable artifacts when a turn completes and remain downloadable after sandbox expiry.[5]
An inactive hosted sandbox can be deleted after one hour without activity or keep-alives, and that timeout is not configurable.[5] Download required artifacts before deleting the session.[5] Closing an event stream does not cancel the task.[5]
Current pricing
OpenAI says there is no additional fee for the Agents API itself. Model tokens, built-in tools and hosted containers are billed separately at their normal rates.[1][3]
The current standard short-context model rates per one million tokens include:[6]
| Model | Input | Cached input | Output |
|---|---|---|---|
| GPT-6 Astra | $10.00 | $1.00 | $50.00 |
| GPT-5.6 Sol | $4.00 | $0.40 | $20.00 |
| GPT-5.6 Terra | $2.00 | $0.20 | $12.00 |
| GPT-5.6 Luna | $0.20 | $0.02 | $1.20 |
Hosted Shell and Code Interpreter containers are currently listed at $0.03 for 1 GB, $0.12 for 4 GB, $0.48 for 16 GB and $1.92 for 64 GB per 20-minute session per container. Eligible container sessions are billed by the minute with a five-minute minimum.[6]
Web search is currently $10 per 1,000 calls plus search-content tokens billed at the selected model’s rates.[6] Because an agent can loop through many turns and tools, enforce task limits, observe usage and test with the smallest suitable model before scaling.[3][6]
Production-readiness checklist
Before allowing an agent near a real workflow:
- ☐ Use a project-scoped application key with only required API permissions.
- ☐ Start with network access disabled or restricted.
- ☐ Mount or upload only the files needed for the task.
- ☐ Treat tool output as untrusted data.
- ☐ Require human approval for irreversible or external actions.
- ☐ Set spending alerts and limits outside the prompt.
- ☐ Log session IDs, request IDs, tool failures and final artifact IDs.
- ☐ Test retry behavior and disconnected-stream recovery.
- ☐ Verify artifacts independently instead of trusting the final message.
- ☐ Delete sessions and credentials when the work is complete.
OpenAI warns that agent.session.turn.completed is not proof that every tool succeeded. Failed or cancelled turn events must be handled explicitly, and a disconnected stream should be recovered by reading the saved session and items before retrying.[4]
Important privacy limitation
The Agents API currently supports data residency only in the United States and does not support Zero Data Retention. Using a self-hosted sandbox does not remove that limitation because the managed API still retains session state.[3]
That makes a legal and security review essential before sending regulated records, client secrets, health data, financial data or other sensitive material.[3] Public beta also means endpoint details, supported models, pricing and limits can change.[1]
FAQ
Is the OpenAI Agents API available now?
Yes. OpenAI announced it as a public beta available to all developers on September 10, 2026.[1]
Is the Agents API free?
There is no separate Agents API fee, but it is not cost-free. You pay for model tokens, applicable tools and hosted containers.[1][6]
Does the Agents API run code?
Yes, when you attach an execution environment. An OpenAI-hosted sandbox can run commands and code, work with files and publish artifacts.[3][5]
Do I need the beta header?
The official SDK adds it automatically. Raw HTTP requests currently need OpenAI-Beta: agents=v1.[4]
Can I keep a session and send another task?
Yes. Save the session ID and send follow-up input to continue the same session. Open the event stream first so early events are not missed.[4]
Is Zero Data Retention supported?
No. OpenAI’s current overview says the Agents API is not ZDR-eligible and currently supports only United States data residency.[3]
Should I deploy it directly to production?
Treat it as a public beta. Begin with a disposable project, restricted permissions, non-sensitive test data, cost controls and human approval gates.