Build1 publisher2 min readPublished
OpenAI's Agents API beta hosts the agent loop that teams used to write themselves
OpenAI's Agents API, in public beta since DevDay 2026, runs sessions, orchestration, context compaction and recovery for developers' agents. Teams that wrote their own loop can hand that state to OpenAI and keep their tools and their choice of sandbox.
The Engineer · Build desk
Drafted by a language model from the sources cited here and checked against its claim ledger before publication. How we use AISend a correction
What happened
- The API exposes the managed Codex harness behind OpenAI's own agents, the same engine that runs the always-on Dots agents announced at DevDay.
- OpenAI wound down the Assistants API in August, leaving the Agents API as the stateful option on its platform, according to the tutorial.
- There is no separate Agents API fee during the beta; users pay the model's API rates plus standard tool and hosted-container rates.
- Data residency is US-only, and Zero Data Retention is unsupported even when the customer brings its own sandbox.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint Migrating teams keep their own result checks, because a turn.completed event does not guarantee that every tool call inside the turn succeeded.
- decision Teams that built their own loop to meet Zero Data Retention or non-US residency rules have no migration path in this beta, since a customer-run sandbox changes neither limit.
- exposure The agent executes code in its environment, so any credential stored there, including the OpenAI key itself, is reachable by the agent.
- cost Teams that migrate during the beta carry the upkeep of an API surface that can still change, and have to pin SDK versions and track the changelog to contain it.
One call to client.beta.agents.sessions.create creates a session, provisions an OpenAI-hosted sandbox, starts a turn of work and streams progress back as JSON events [14]. In the quickstart, the model is gpt-6-astra and the environment type is openai_hosted [14]. The walkthrough comes from AI Frontier Post and was republished on dev.to. It says every call in it was checked against OpenAI's documentation and the Python SDK [20]. It describes the code this call replaces as the loop agent teams have written for the past year: call the model, parse its tool calls, run them, append the results, repeat, then add context management, retries and recovery [5].
The API has four objects. An agent holds the model, instructions, tools and MCP servers. An environment is the sandbox or computer where the agent works. A session is a durable instance of the agent, and events and items are the live and saved records of what happened [13].
The durable session changes how retries work. If the stream drops early, the tutorial says to retrieve the session and its saved items before retrying, because the work persists server-side [17]. A retry path that simply resends the request skips that step. The tutorial also tells readers to save the session_id from the event stream for later steps [19].
The event states are well separated. Events ending in turn.failed or turn.cancelled, and session.failed, report failure or cancellation. agent.session.idle on its own does not mean success [16]. Idle and finished are different states for agents, as they are for contractors. A stream reader has to branch on the terminal event and then read the agent's reported result, because the docs warn that a completed turn can still contain failed tool calls [15].
The tutorial covers three environment options, tools including MCP servers, multi-turn sessions and subagents [18]. Access takes an application key with three scopes. Those are api.agents.read and api.agents.write for session operations, and api.responses.write for model inference [6]. Each request also needs the OpenAI-Beta: agents=v1 header. The official SDKs add it automatically. A cURL script or custom HTTP client that leaves it out gets failed requests [7]. The floor is Python 3.10 and OpenAI SDK 3.13.0, and the tutorial's snippets were verified against 3.22.0 [8].
Take a team with a working loop and no data retention requirement. I'd have it hand over recovery first. The tutorial's advice on dropped streams already assumes OpenAI holds the state [17].
What to watch
- Whether OpenAI adds Zero Data Retention or non-US data residency to the Agents API before it leaves beta.
- What the Agents API costs after the beta, since the no-separate-fee terms apply only during it.
- Breaking changes to the beta.agents SDK namespace or a successor to the agents=v1 beta header.