OpenAI's Agents API: The Managed Way to Run AI Agents in Production

TL;DR: OpenAI’s Agents API (POST /v1/agents/sessions, public beta since September 10, 2026) turns “agent” from a while-loop you own into a durable, resumable object OpenAI hosts for you — model, instructions, tools, and a sandbox, addressed by one session_id. You stop rebuilding job queues and container orchestration for every agent project and start managing session state instead. This post covers what actually changed, the real pricing, where it breaks in practice, and a full worked example you can run today.

The loop you’ve probably already written by hand

If you’ve shipped anything agentic on OpenAI’s models, you’ve written this loop, or something close to it: call the model, check if it asked for a tool, run the tool, stuff the result back into the context, call the model again, repeat until it stops asking for tools. Then you wrapped it in a job queue so it could survive longer than one HTTP request. Then you built a container orchestrator so tool calls that run code had somewhere safe to run. Then you added a state machine so a crashed worker could resume a task instead of losing it.

None of that is agent logic. It’s plumbing every team building agents ends up writing, independently, slightly differently — and it’s exactly the layer OpenAI decided to sell as a managed service on September 10, 2026: the Agents API. It’s not a new model, and it’s not a replacement for the Agents SDK you might already be using — it’s a hosted version of the plumbing.

What it actually is

A session is the unit that replaces your loop. It bundles four things:

• Agent — the model, its instructions, its tools, and any MCP servers it’s allowed to call
• Environment — where the agent’s tool calls actually execute: an OpenAI-hosted sandbox, or one you bring yourself (E2B, Modal, DigitalOcean, Vercel are supported)
• Session — the durable, resumable object doing the work, addressed by a session_id that outlives your client connection
• Events/Items — the timestamped record of everything that happened, readable back at any time

This sits at a different layer from tools you’ve likely already used, and mixing them up is the single most common source of confusion in this space:

The Agents SDK didn’t get replaced — it got a sibling. If your server already owns tool execution and approval logic, the SDK still gives you tighter, typed, in-process control. The Agents API exists for the specific case where you’d rather not run that infrastructure yourself.

Why this is worth your attention right now

Long-running agent work fundamentally doesn’t fit the request/response model most backends are built around. “Refactor this repo, run the test suite, fix what’s red” can take ten minutes, needs to keep going if your server restarts, and needs a real filesystem and shell to run in — not a sandboxed eval(). Before September 2026, you built all of that yourself. Now it’s three HTTP calls:

POST /v1/agents/sessions               start a session
POST /v1/agents/sessions/{id}/events   steer it mid-turn, or continue it
GET  /v1/agents/sessions/{id}/items    read back what happened, paginated

And critically, a session is a real object with a lifecycle independent of your process. Your laptop can sleep, your Lambda can time out, your pod can get rescheduled — the session keeps running server-side, and you reconnect to it with the same session_id and pick up exactly where it left off. That’s the actual unlock. Everything else is convenience on top of it.

A turn is one cycle of work. Message an idle session and you start a new turn. Message a session that’s already mid-turn and you steer it — you redirect the current work without waiting for it to finish and re-prompting from scratch. That distinction matters more than it looks: steering keeps the model’s original context and reasoning intact, while “wait, then correct” throws it away and starts cold.

Worked example: a repo task, start to finish

Here’s the whole lifecycle, not just the create call everyone quotes.

export OPENAI_API_KEY="your-api-key"

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)

curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"agent.session.input.message","content":"Also add type hints."}]}'

curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"agent.session.input.cancel"}]}'

curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/items \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

What it actually costs

There’s no separate “agent fee.” You pay the model at its normal API rate, plus standard rates for any hosted tools, plus container time for the sandbox — billed per minute, with a 5-minute minimum, in 20-minute pricing bands by memory size:

Web search, when the agent uses it, is billed separately at $10 per 1,000 calls (plus the search content’s own token cost).

Where teams are actually pointing this

OpenAI’s cookbook examples for the Agents API/SDK cluster around a specific shape of problem: long, semi-autonomous work with a real filesystem or shell underneath. SRE incident-response agents. Legacy codebase migrations run inside sandboxes. Prior-authorization review in healthcare. AML analysis with a security-evaluation layer on top. Database change-impact analysis that generates and checks SQL before anyone runs it. The common thread isn’t “chatbot” — it’s “task that would otherwise sit in someone’s queue for an hour.”

Common pitfalls

Which one should you actually use?

Further reading

• Agents API overview
• Agents API quickstart
• Run and continue sessions
• Agents SDK guide
• Orchestration and handoffs
• OpenAI pricing
• Announcement: Introducing the Agents API and hosted sandboxes