OpenAI Agents API: what replaced the Assistants API

The OpenAI Agents API is OpenAI's hosted agent: you start a session with a model, instructions and tools, send it tasks, and OpenAI runs the Codex harness that calls the model, runs the tools, compacts the context and keeps the session's state between turns. It went into public beta on 10 September 2026, 2 weeks after the Assistants API shut down on 26 August.

Officially, the Assistants API's replacement is the Responses API with the Conversations API. That is the right home for apps that only used Assistants as a chat store. For apps that leaned on OpenAI running the loop and holding the state, the Agents API is the closer match. This guide maps one to the other, shows a first session, and covers what it costs and where it stops.

The short answer: 2 places to move to

Which API replaces Assistants depends on who you want to run the tool loop. With Assistants, a run executed against a thread on OpenAI's side, calling tools until it finished. The 2 successors split that job differently:

The Agents SDK is a third option: a library whose runner executes the loop inside your application. Pick it when you want the loop but on your own servers, with your own storage and approvals.

What each part of an Assistants app becomes

Every Assistants object has a counterpart in both APIs, but 1 of the guide's mappings is a dead end. OpenAI's migration guide turns assistants into reusable prompts, created in the dashboard. On 3 June 2026 OpenAI announced that reusable prompts are being deprecated too, and the v1/prompts API is scheduled to shut down on 30 November 2026. Moving there means moving twice.

Pick what your app used:

Try itWhere your Assistants API code goes

Your app used

·All·Assistant objects·Threads·Runs·Run steps·Function calling·Code interpreter·File search

Responses APIAgents API

1. Assistant objectsA saved agent: create it once and start each session with its agent_id. Updates apply to new sessions only.
2. ThreadsA session: it keeps the configuration, the conversation and the sandbox's files between turns.
3. RunsA turn. A message to an idle session starts one, and the harness runs the tool loop until the turn completes, fails or is cancelled.
4. Function callingFunction tools on the agent. The session emits agent.session.requires_action and waits for your agent.session.input.tool_result.
5. Code interpreterAn OpenAI-hosted sandbox (small, medium or large) where the agent runs shell commands and Python, billed at container rates during active turns.

The rest of the mapping is direct. Threads become conversations, which store tool calls and outputs as well as messages, or sessions on the Agents API. Runs become responses, or turns. And the history in your old threads is gone with the API: OpenAI's guide says the call that read thread messages no longer works, so only messages your own app stored can be carried over.

A first Agents API session in Python

A session needs an agent, an environment and the first input, and an agent can be saved once and reused. This one gives a saved agent a function tool that looks up an order, so it can answer support questions against data only your app can reach:

from openai import OpenAI

client = OpenAI()

# Once: a saved agent, the successor of an assistant object.
agent = client.beta.agents.create(
    model="gpt-6.1-sol",
    instructions="You answer order questions. Look the order up before you answer.",
    tools=[{
        "type": "function",
        "name": "get_order",
        "description": "Look up an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
    }],
)

# Per conversation: a session, the successor of a thread.
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Where is order 48213?",
)

When the agent wants the order, the session emits agent.session.requires_action and waits. Your code runs the function and sends the result back as an event, and the harness carries on with the turn:

import json

# action: one entry of session.required_actions
client.beta.agents.sessions.events.create(session.id, events=[{
    "type": "agent.session.input.tool_result",
    "turn_id": action["turn_id"],
    "call_id": action["call_id"],
    "success": True,
    "output": json.dumps(get_order(action["arguments"])),
}])

The SDKs add the OpenAI-Beta: agents=v1 header themselves; with cURL you send it. The API key needs api.agents.read, api.agents.write and api.responses.write.

3 behaviours trip up code written for Assistants runs:

• Idle is not success. Check for agent.session.turn.completed, turn.failed or turn.cancelled, and read the output: a completed turn does not mean every tool call worked.
• A message during a turn steers it. Sent to an idle session it starts a new turn; sent while the agent works it changes the current one.
• Streams do not replay. After a disconnect, read the session and its saved items to catch up, and send each message with an idempotency key so a retry does not send it twice.

Sandboxes: none, OpenAI's or yours

The environment decides whether the agent can run code, and an agent that only calls your functions needs none. With "type": "none", as above, there is no shell, no file editing and no workspace, and nothing to pay for beyond tokens.

An OpenAI-hosted sandbox gives the agent a Linux workspace with Python, Node.js and command-line tools, in 3 sizes: small (1 vCPU, 1 GB), medium (2 vCPU, 4 GB, the default) and large (4 vCPU, 16 GB). You can install packages, add files and run setup commands before the agent starts. Files the agent writes to /workspace/outputs are kept as artifacts after each turn. A sandbox with no activity and no keep-alive for an hour can be deleted, and that limit cannot be changed.

The hosted sandbox's network is open by default. Set restricted with a list of up to 100 exact host names, or disabled, before an agent that reads untrusted text gets a shell.

A self-hosted sandbox runs OpenAI's executor, codex exec-server, on a machine you control, connecting out to OpenAI over WebSocket. OpenAI lists setup guides for Modal, Cloudflare, Vercel, Daytona, E2B, AWS Lambda MicroVMs and others. You own its start, reconnection and shutdown.

What the Agents API costs

There is no fee for the Agents API itself: you pay for tokens, tools and sandbox time. Every model call the agent makes, and every call its subagents make, is billed at the model's token prices with the usual cached-input discount; reasoning tokens count as output. On GPT-6 Astra that is $10 per million input tokens and $50 output; on GPT-6.1 Sol, $2 and $10.

OpenAI-hosted sandboxes use the container price list, which goes by memory: $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. Since 9 October 2026 sandbox compute is billed only during active turns, so a sandbox waiting for the user's next message no longer costs anything. Web search is $10 per 1,000 calls.

As with any agent, tokens dominate: each step re-sends the history, so a long task reads millions of input tokens long before the sandbox bill matters. What an AI agent costs per month works through that sum, and the agent cost simulator runs the same task on every current model. 1 caution from OpenAI's own page: the usage figures a session reports are best effort, can be null, do not show cache writes and are not your bill.

Where it stops

• No Zero Data Retention, US residency only. Sessions keep their state on OpenAI's servers. A self-hosted sandbox moves the commands, not the harness or the model calls, so it does not change this.
• It is a beta. Fields and behaviour can change; how to evaluate an AI agent is the safety net for every update.
• 4 MiB limits. A request's input, the agent's instructions with its tools, and each function result must each stay under 4 MiB.
• Saved agents do not update running sessions. A change applies to new sessions; an existing session can switch only its model, reasoning effort and service tier.
• On AWS it is a different service. Amazon Bedrock Managed Agents, powered by OpenAI, adapts the Agents API with Bedrock inference, AgentCore Runtime and IAM, and OpenAI warns that its API contract and features are not identical.

Agents API, Responses or Claude Managed Agents

Move to the Agents API when your Assistants app depended on OpenAI running long tool loops and keeping their state. Move to Responses and Conversations when it was mostly a chat history with a few function calls, or when you need Zero Data Retention or residency outside the US. Anthropic's hosted equivalent works on the same idea with its own sandbox and a runtime fee; Claude Managed Agents covers it, and LangGraph vs CrewAI vs the Claude Agent SDK covers the libraries for running the loop yourself. If you reach OpenAI through Azure, Azure OpenAI vs OpenAI explains what is and is not the same there.