One endpoint, POST https://api.openai.com/v1/agents/sessions, plus an OpenAI-Beta: agents=v1 header.
That’s it. OpenAI took the harness that runs agents inside the Codex client, moved it server-side, and turned it into a REST API any backend program can call.
This isn’t a new model. It’s a new way to run one.
In the past, if you wanted an agent to run for a long time, read and write files, execute commands, and break work into subtasks, you had to build the whole stack yourself: sandbox VM, context management, checkpoint recovery, tool orchestration. Now OpenAI is saying: we’ll handle that, you just bring the tools and define the environment.
Sounds great. But don’t wire it up just yet.
Get the four concepts straight first, or the docs won’t make sense
OpenAI splits the whole thing into four words. Once you understand these four, everything else is detail.
| Concept | What it is | Who owns it |
|---|---|---|
| Agent | Model + instructions + tools + MCP servers | You define it |
| Environment | An optional sandbox or computer where the agent reads/writes files, loads skills, runs commands | You choose it; OpenAI can host it |
| Session | A persistent agent instance that handles tasks and responds to input | OpenAI hosts it |
| Events / items | Inputs and outputs during a session | Bidirectional |
The workflow is just as plain: create a session → assign a task → follow along via streaming or webhooks → continue or intervene.
Note that last step, “intervene.” This isn’t a batch API where you submit a job and wait for a result. You can cut in mid-task and change direction while the agent is working. That matters a lot for product teams — users won’t sit through a ten-minute black box.
What the hosted harness actually hosts
This is the part worth reading closely. Here’s the work OpenAI takes off your plate:
- Running commands and code inside a sandbox
- Applying skills and instructions
- Connecting to external data via tools or MCP
- Letting you intervene at any point during the work
- Compressing prior context
- Delegating subtasks to subagents
- Resuming from a checkpoint
I stared at “compressing prior context” for a while. This is the single easiest thing to get wrong in a self-built setup. Once context grows long, either you blow the window, or the model starts forgetting things, or you burn serious effort on summarization and still lose information. OpenAI making this a hosted capability means it’s taken that dirty work away.
Multi-agent mode is enabled via agent.multi_agent, with concurrency controlled by max_concurrent_subagents. Tools come in three flavors: programmatic_tool_calling, mcp (HTTP transport), and web_search. Environments come in two: self_hosted or an OpenAI-hosted sandbox.
SDKs cover Python, TS/JS, Go, Java, and Ruby, all unified under client.beta.agents.sessions.create(...). That’s refreshingly restrained — no language favoritism.
Two limits you must know, and the second one hurts more
The first is data residency: US only, for now.
The second: no Zero Data Retention (ZDR) support.
And here’s the trap — even if you pick self_hosted, that does not make you ZDR-compliant. Session orchestration and context compression still run on OpenAI’s side.
For teams building finance, healthcare, or legal applications, that sentence is basically a suspended sentence. ZDR isn’t a “nice to have” — it’s a hard checkbox on a lot of compliance lists. If you can’t check it, the project doesn’t pass review.
So if your customer contracts say data must not be retained, this API is off the table for now. Not a capability problem — a compliance problem.
Vague pricing is the hidden cost
The official line: model usage is billed at the selected model’s rate, OpenAI tools at standard prices, hosted sandboxes at container prices.
Sounds clear enough, but after real testing, people in the community raised a few questions that I think hit the mark:
- Does every agent session execution spin up a new environment?
- Is the environment billed at a minimum of one hour?
- Can you shut down the environment proactively to save money?
The official docs don’t give clear answers. If environments are billed by the hour, then running a 30-second task might still cost you a full hour. For high-frequency short tasks, that cost structure looks ugly.
My advice: run a small load test before launch and get the actual bill before deciding. Don’t trust estimates. Trust the invoice.
The community also tested sandbox network access, which has three modes: enabled, disabled, and restricted. In restricted mode, hitting an external domain returns “Domain forbidden.” The design is right, but you need to figure out upfront which domains your agent needs, or you’ll be staring blankly at the screen while debugging.
Should you use it? Three types of teams, three answers
The community is arguing hard. One camp says “this smells like reinforced vendor lock-in.” The other is pragmatic — “it saves me from maintaining a sandbox VM myself.”
Both are right. It depends where you stand.
Type 1: Small teams / indie developers — adopt it.
The cost of maintaining your own sandbox VM isn’t just money, it’s time. Security isolation, resource reclamation, image updates, network policy — every one is a pit. I built a setup myself once, and just solving “the agent ran wild and filled the disk” took me two weeks. If OpenAI can carry that, the time you save is worth two features.
Type 2: Teams with compliance requirements — wait.
No ZDR plus US-only data kills a lot of scenarios. It’s not that you can’t negotiate — it’s that right now there’s nothing to negotiate. Wait for an official ZDR roadmap.
Type 3: Teams already at scale — proceed carefully.
At your volume, hosted costs may exceed self-hosting. And with session state and execution environments in someone else’s hands, migration costs compound over time. If you must use it, design your architecture to be replaceable — wrap the Agents API in your own abstraction layer, and don’t let business code call client.beta.agents.sessions.create directly. When the day comes to switch, you change one layer.
In the end, this is a standardization of “how to run”
The substance of the Agents API is turning the Codex client’s harness into a server-side service, making long-running agents that read and write files and split subtasks into first-class citizens any backend can call.
The price is handing session state and execution environments to OpenAI.
The capability ceiling hasn’t changed. What changed is whether you want to carry the ops and compliance yourself. That math comes out differently for every team.
Would you hand your agent’s session state to OpenAI to host? Or would you rather maintain that sandbox yourself? Tell me your trade-off in the comments.