Your first agent on the OpenAI Agents API: what it replaces and what it costs

OpenAI put the Agents API into public beta on 10 September 2026. The one-line version from OpenAI's own docs: it gives your application access to the Codex harness through an OpenAI-managed API, where OpenAI manages sessions, orchestration, context compaction and recovery while your application supplies the tools and picks the execution environment.

That is a developer sentence. Here is the operator version. Somebody on your team is already doing a job every week that looks like this: open twelve pages, pull the same four things out of each, notice what changed since last time, write it up, put it somewhere. An agent is a way to run that job on a schedule for under a dollar. This guide is about whether that trade is real, what the run costs when the invoice lands, and the five places it breaks.

Every price, limit and capability below is quoted from OpenAI's published pages, linked where it matters. Nothing here is from memory, and you should check the pricing page yourself before you budget against it, because these numbers move.

What you'll have when you're done

• An agent session running in an OpenAI-hosted sandbox, with the exact request that starts it
• A per-run cost you can actually defend, built from the published rates
• A clear line between what the Agents API takes off your plate and what it does not
• The five failure modes written down before you hit them, not after
• The network and cleanup settings you want on before this touches anything real
• [SCREENSHOT: a completed session's streamed events with the usage object visible]

Before you start

• An OpenAI API key with the right permissions. The quickstart says the key needs api.agents.read, api.agents.write and api.responses.write. A key that works for chat will not necessarily work here.
• The beta header. Every request carries OpenAI-Beta: agents=v1. The official SDKs add it for you.
• A billing account you are willing to point at a loop. Agents make several model calls per task. That is the whole design.
• A job worth automating. Something you do on a schedule, whose output you would notice if it were wrong. If you cannot name one, stop here; the API is not the problem.
• 30 minutes.

What it actually replaces

The Agents API is not a model. It is the scaffolding around one. OpenAI lists what the managed harness does:

If you have ever written the loop that calls a model, reads the tool call, runs it, appends the result and calls again, that loop is the product. OpenAI's own comparison table puts it plainly: agent integration effort is Low for the Agents API, Medium for the Agents SDK, and High for the Responses API, and the difference is who keeps the state between tasks.

Now the honest other half, because this is where teams get disappointed.

It does not replace the decision about what to run. An agent that checks twelve competitor pages every Monday is worth something because somebody decided those twelve pages matter. That decision is the job.

It does not replace the schedule. Something still has to start the session. That is your cron, your queue, your webhook.

It does not replace review. The output is a draft with confidence. Ship it unread and you will eventually ship something wrong with a straight face.

It does not replace your data policy. See the compliance section below, because this one is a hard stop for some teams rather than a caveat.

Step 1: Start a session in a hosted sandbox

This is the whole first run. OpenAI provisions the sandbox, the agent writes a file, runs it, and reports what happened.

curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'

Four fields carry all the meaning. agent is the model and the instructions. environment is where it runs, and openai_hosted means OpenAI provisions and manages the sandbox. input is the task. stream decides whether you watch it or wait for a webhook.

One thing worth knowing before you wire it into anything: the create-session response only means setup has started. You check GET /v1/agents/environments/{environment_id} and wait for status connected before you add or list files. provisioning means it is still coming up.

Step 2: Give it the tools that make it replace something

A model with no tools is a chat box. The version that replaces a weekly job looks more like this, which is OpenAI's own configuration example:

"tools": [
  { "type": "programmatic_tool_calling" },
  {
    "type": "mcp",
    "server_label": "openai_docs",
    "transport": {
      "type": "http",
      "server_url": "https://developers.openai.com/mcp"
    }
  },
  { "type": "web_search" }
],
"multi_agent": { "enabled": true, "max_concurrent_subagents": 4 }

Three things to notice. MCP means the integrations you already have keep working, because MCP servers are the same ones a Claude or Codex setup uses. programmatic_tool_calling lets the agent orchestrate tool calls rather than round-tripping every one through the model. And multi_agent turns on the subagent fan-out, which is the feature that makes "check twelve pages" finish in a reasonable time.

Step 3: Work out what a run costs

There is no platform fee. OpenAI's announcement says there are no additional fees for using the Agents API and that you pay for the tokens and tools your agents use. The overview says the same in three parts: model usage at the selected model's API rates, OpenAI tools at their standard rates, hosted sandboxes at standard container rates.

So the bill is entirely made of published unit prices. Here are the ones that decide it, from OpenAI's pricing page:

Two footnotes on that table matter more than the table. Container sessions are billed by the minute with a five-minute minimum per session, so a thirty-second job is priced as five minutes. And reasoning tokens are billed as output tokens, which on gpt-6-astra means the thinking costs five times what the reading costs.

A worked run

Take the competitor sweep from the top: twelve pages, pull four fields from each, write the diff. Assume a run that uses 60,000 input tokens with 20,000 of them cached, 8,000 output tokens, twelve web searches, and nine minutes of a 1 GB sandbox. These are assumptions, not measurements, and they are the numbers you will replace with your own.

Read the shape of that, not the total. Model tokens are about 86 percent of it. The sandbox, which is the part that sounds expensive because it is a whole computer, is about one and a half percent. Tune the prompt and the output length; ignore the container.

At five runs a week that is roughly $21 a month. At twenty runs a week, roughly $82. Those are the numbers to put next to whatever the job costs in salaried hours today, and for most weekly reporting jobs the comparison is not close.

Step 4: Lock the network down and clean up after yourself

Two settings that are easy to skip and expensive to skip.

Outbound access. The sandbox network policy takes three values: enabled, which allows outbound access and is the default, disabled, which blocks it, and restricted, which allows only the hosts in allowed_domains. Restricted mode accepts 1 to 100 exact host names such as api.example.com. OpenAI is explicit that you must not include wildcards, protocols, paths or ports, and that subdomains and redirect destinations need their own entries.

That last clause is the one that bites. A shortened link, a CDN in front of a docs site, an OAuth hop: each of those is a different host, and each needs its own line or the request just fails.

Cleanup. Delete the session when you are done, which is what asks for sandbox cleanup. If deletion returns a 409 while setup or execution is still finishing, wait and retry with a cap on attempts. And note the one that surprises people: closing the event stream does not cancel the task. Hang up on a running agent and it keeps running, and keeps billing.

The five places it breaks

1. The sandbox is not storage

Connected sandboxes get keep-alives between turns, and OpenAI states that if activity and keep-alives stop for an hour, the sandbox can be deleted, and that this timeout is not configurable. Files persist across turns only while the sandbox exists.

The escape hatch is /workspace/outputs. Files there are published as immutable artifacts when a turn completes, and those copies stay downloadable after the sandbox expires. So the rule is simple: anything you want to keep gets written to /workspace/outputs before the turn ends, or it is gone.

2. The usage numbers are not a bill

OpenAI's observability page is unusually direct about this. Session and turn usage is best-effort, can be null when unknown, and recorded counts may change as accounting arrives. It says plainly that missing usage does not mean zero usage and that these counts are not a final bill. It also notes that the usage fields do not expose a separate cache-write count, so on a model with cache-write pricing they cannot determine the exact model charge.

Use the usage object to catch a run that has gone into a loop. Use the billing dashboard for money. Do not build a client-facing cost report on the usage field.

3. File limits arrive earlier than you think

Ten mebibytes of inline upload is about four screenshots from a modern phone. If your input is "here is the folder", route it through the Files API, where the per-file ceiling is 50 MiB, rather than inlining it.

4. Output tokens are where a run goes wrong

At $50.00 per million on gpt-6-astra, with reasoning billed as output, the expensive failure is not a slow agent. It is a verbose one, or one that reasons in a circle. And the long-context rate is $20.00 in and $75.00 out, double and one and a half times the short-context rates, so a run that grows past the short-context boundary re-prices itself mid-job.

Context compaction helps and is one of the reasons to use the managed harness at all. It is not a substitute for an instruction that says how long the answer should be.

5. Compliance may just say no

OpenAI states the Agents API currently supports data residency only in the United States and does not support Zero Data Retention, and adds that choosing a self-hosted sandbox does not make the Agents API ZDR-eligible.

If you are under a policy that requires EU residency or ZDR, that is the end of the evaluation for now, and it is better to find that out in week one than after you have built the thing. Self-hosting the sandbox is a real option, and OpenAI names integrations with Blaxel AI, Cloudflare Dev, Daytona, DigitalOcean, E2B, Modal, Oracle Cloud, Runloop AI and Vercel, but it solves where the code runs, not where the data is retained.

Which runtime you should actually pick

OpenAI publishes the comparison, so use theirs rather than a vendor's blog post:

For a marketing or ops team with no platform engineer to spare, the Agents API is the right first stop, and the reason is the state column, not the model. The thing that kills these projects is never the model call. It is the second week, when the job needs to resume, retry, and remember.

What I would do first

Run one job you already do by hand, on a schedule, for a month. Not a demo. The Monday sweep, the weekly digest, the thing nobody wants. One job gives you a real usage number, a real failure, and a real answer about whether the output gets read.

Write the output to /workspace/outputs on day one. Everybody learns this the hard way an hour after a good run.

Log the estimate next to the actual. Estimate the run cost from the rate table before you run it, record what billing says after, and keep both. Two weeks of that and you can quote a number for the next ten agents without guessing, which is the only way this stops being a science project and starts being a line item.