# OpenAI Agents API Tutorial: Hosted Agents and Sandboxes

> A hands-on Agents API walkthrough: create a session in an OpenAI-hosted sandbox, stream turns, steer, handle webhooks, clean up, and check residency first.

URL: https://www.matthewswong.com/en/blog/openai-agents-api-hosted-sandbox-tutorial/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** The OpenAI Agents API, in public beta since 10 September 2026, runs the Codex harness: you create a session with an agent and an environment, send a task, follow events or webhooks, steer or cancel mid-turn, then download artifacts and delete the session. There is no platform fee, but data residency is US-only and Zero Data Retention is unsupported.

The job I had in mind was dull and real. Every month-end, someone at an ERP client exports invoices per branch, totals them in a spreadsheet and chases the rows that do not reconcile. It is exactly the kind of task an agent with a Python sandbox should finish unattended, and until September 2026 doing that on OpenAI meant writing and hosting the agent loop myself.

This OpenAI Agents API tutorial walks the whole session lifecycle in TypeScript, using only fields documented in OpenAI's own guides: creating a session in an OpenAI-hosted sandbox, streaming a turn correctly, steering and cancelling, handling webhooks and function results, choosing between hosted and self-hosted sandboxes, and cleaning up. It ends with the two data-handling limits to check before anyone ships it.

## What the Agents API runs for you, and what stays yours

The Agents API is a managed service around the open-source Codex harness. OpenAI's overview says it manages sessions, orchestration, context compaction and recovery, while your application provides tools and chooses the execution environment. The design rests on four objects:

- Agent: the model, instructions, tools and MCP servers. Pass it inline per session, or save it once and reference it by agent_id.
- Environment: an optional sandbox where the agent reads files, loads skills and runs commands. The type is none, openai_hosted or self_hosted.
- Session: a durable instance of the agent that keeps its conversation and saved work across turns.
- Events and items: events report live progress, items are the saved messages and tool calls you fetch later.

What the harness adds over a hand-rolled loop is listed plainly: running commands in a sandbox, applying skills, connecting to tools or MCP, steering while the agent works, summarising earlier work to fit the context window, delegating to subagents and resuming a session where it left off. What stays yours is everything with business consequences: the function handlers that touch your systems, the credentials, the decision about where code runs, and the check that a finished turn actually did the job.

## OpenAI Agents API tutorial: create your first hosted session

The beta lives under the beta.agents namespace of the official SDKs. Raw HTTP requests need the header OpenAI-Beta: agents=v1, which the SDKs add for you. Set the pieces up in this order:

1. Create an application API key with api.agents.read and api.agents.write for session operations, plus api.responses.write for model inference.
2. Install or update the SDK with npm install openai, and keep the key in your backend. The quickstart is explicit that it belongs outside the sandbox.
3. Pick the environment. For a reconciliation job, openai_hosted is enough: a Linux workspace at /workspace with Python, Node.js and command-line tools.
4. Restrict the sandbox to what the task needs: a container size, the packages to install, the input files and the network policy.
5. Create the session, store its id with your own job record, and only then send the task.

Two choices in that request are deliberate. Network access in an OpenAI-hosted sandbox defaults to enabled, so a job that only crunches a CSV should say disabled, or restricted with an allowed_domains list of 1 to 100 exact host names. And the session is created without input: the guides say to subscribe to the event stream before sending work, because a stream does not replay events you were not listening for. The documented sizes are small at 1 vCPU and 1 GB, medium at 2 vCPU and 4 GB, which is the default, and large at 4 vCPU and 16 GB.

> Check setup before trusting the sandbox. A successful create call only means setup has started. Retrieving /v1/agents/environments/ followed by the session's environment.id returns provisioning while packages and setup_commands run, and connected once they succeed. A nonzero setup command exit status stops the agent from starting at all, which makes a setup command the cheapest place to assert that a required file or package is present.

## Streaming a turn: why idle is not success

A turn is one cycle of work inside a session. The helper below opens the stream, sends the task, prints text deltas and returns only when the root turn completes. It is adapted from the send-and-stream helper in OpenAI's Events and items guide, and every case in the switch is there for a reason the docs spell out.

The trap I would have walked straight into is agent.session.idle. It fires when the session is ready for more input, not when the work succeeded, so code that treats idle as done will report a failed reconciliation as finished. The outcome events are turn.completed, turn.failed and turn.cancelled, and even a completed turn does not guarantee every tool call succeeded, so read the agent's output too. Two more details matter in production. Turn events from subagents carry a subagent_id and must not end the loop. And when a stream drops, missed events are gone: you recover by opening a new stream, retrieving the session and its saved items, and merging by item_id.

## Follow-ups, steering and cancelling a turn

There is no separate steer endpoint. The same agent.session.input.message event starts a new turn when the session is idle and steers the active turn when the agent is working, so a correction such as excluding a test branch lands while the agent is still mid-task. Cancelling is a different input event on the same endpoint, and it stops the turn without discarding the session or its earlier work.

Some settings can change on a live session and some cannot. A POST to the session itself can change the model, reasoning effort or service tier for turns started after the update, while an active turn keeps its settings even when you steer it. Instructions, tools and multi_agent are fixed for the life of the session, so changing what the agent may do means creating a new session. That is a useful property when an auditor asks what an agent was allowed to do on a given run.

## Webhooks and function tools instead of an open stream

A month-end job should not hold an HTTP stream open for as long as the agent needs. Session webhooks cover the state changes, namely agent.session.created, action_required, in_progress, idle and failed. They are signed, so the handler verifies the signature against your webhook secret before parsing anything. The interesting one is action_required, which fires when the session needs a function result, an environment connection or a computer-use approval.

Two details in that handler come straight from the docs and are easy to miss. The webhook deliberately omits call IDs and arguments, so you retrieve the session and read required_actions rather than trusting the payload. And the webhook is named agent.session.action_required while the matching stream event is agent.session.requires_action, a one-word difference that silently breaks a handler written against the wrong page. For functions with side effects, such as posting a journal entry, store each result by session, turn and call ID, and resubmit the saved result after a disconnect instead of running the function twice.

## Hosted or self-hosted sandbox: where the code actually runs

The environment type decides who provisions compute and how you get files back. Only OpenAI-hosted sandboxes publish files written to /workspace/outputs as downloadable artifacts. A self-hosted environment returns files through your own provider, even from that same path.

| environment.type | Who provisions it | Getting files out | Use it when |
| --- | --- | --- | --- |
| none | Nobody, there is no sandbox | Read the output from session items | The agent only answers questions or calls your functions and external tools |
| openai_hosted | OpenAI, using the size, packages, files and network policy you set | Artifacts API for files under /workspace/outputs, still downloadable after the sandbox expires | You want a disposable Linux workspace without running any infrastructure |
| self_hosted | You, on a laptop, a container or a provider such as Modal, E2B or Daytona | Your provider's file API or a mounted filesystem | You need your own image, your own compute or a private network |

Self-hosting works by running the Codex executor, codex exec-server, inside your environment. It registers with an environment ID and a restricted environment key, then holds an outbound WebSocket to receive commands, so no inbound port is opened. The environment key can only connect environments and cannot authorise any other API action, which is why it is the only OpenAI credential that should exist inside the sandbox.

> Sandbox options at launch: besides OpenAI-hosted sandboxes, the announcement lists first-class integrations with Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle Cloud, Runloop and Vercel, and the self-hosted guide also documents AWS Lambda MicroVMs. OpenAI-hosted sandboxes offer configurable CPU, GPU and memory, either fully managed or deployed into your own VPC.

## What it costs, and cleaning up a session

The Agents API itself carries no additional fee; the announcement says you pay for the tokens and tools you consume. On OpenAI's pricing page, gpt-6-astra, the model in every Agents API example, lists standard short-context rates of 10 USD per million input tokens, 1 USD per million cached input tokens and 50 USD per million output tokens. The containers line lists 0.03 USD for 1 GB, 0.12 USD for 4 GB and 0.48 USD for 16 GB per 20-minute session, with eligible sessions billed by the minute and a five-minute minimum. Those are the same memory tiers as the small, medium and large sandbox sizes.

Cleanup has an order. Artifacts are immutable copies published when a turn completes, and the API downloads one per request with no batch endpoint, so either loop over them or ask the agent to zip its outputs into one file. Download what you need first, then delete the session. A 409 on deletion means setup or execution is still finishing, so retry with a bounded number of attempts.

Do not lean on expiry as your cleanup mechanism. A connected sandbox receives keep-alives, including between turns, and only becomes eligible for deletion after an hour without activity or keep-alives, a timeout you cannot configure. Closing your event stream does not cancel the task either. For self-hosted sessions the warning is sharper: deleting a session emits no webhook and does not stop provider compute, so your provisioning code owns the shutdown.

## Before you ship: US-only data residency and no ZDR

The overview states both limits plainly. The Agents API currently supports data residency only in the United States, and it does not support Zero Data Retention. Sessions retain state by design, which is what makes follow-ups work, and you can delete sessions and published artifacts when you are done, but deletion is a cleanup step rather than a retention guarantee.

> Choosing a self-hosted sandbox does not make the Agents API ZDR-eligible. Running the executor on your own hardware keeps files and commands on your machine, but the harness, the conversation and the session state still live with OpenAI in the US. If a client contract requires in-region processing or zero retention, the Agents API in its current beta is the wrong runtime, whichever sandbox you pick.

For my month-end example, that splits the work cleanly. Aggregated, already-anonymised exports are a reasonable pilot for a hosted session with networking disabled. Raw ledgers containing customer names, or anything an Indonesian client has contractually kept in-region, stay on a runtime where I control the loop and the storage. Secrets follow the same logic: the hosted-sandbox guide warns that agent-generated code can read env values, and points to vault credentials for anything sensitive.

The Agents API removes the part of agent engineering nobody wanted to own, namely the loop, compaction, recovery and subagent plumbing, and leaves you the parts that carry risk. Treat it as a session protocol: open the stream before sending work, judge success by turn outcomes and output rather than idle, keep the application key out of the sandbox, download artifacts before deleting, and check residency and retention before the first real record goes in.

## Sources

- OpenAI Developer Community: Introducing the Agents API and hosted sandboxes (10 September 2026)
- OpenAI API docs: Agents API overview
- OpenAI API docs: Run and continue sessions
- OpenAI API docs: OpenAI-hosted sandboxes
- OpenAI API docs: Session webhooks
- OpenAI API docs: Pricing

## Source links

- https://community.openai.com/t/introducing-the-agents-api-and-hosted-sandboxes/1396481
- https://developers.openai.com/api/docs/guides/agents-api/overview
- https://developers.openai.com/api/docs/guides/agents-api/sessions
- https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted
- https://developers.openai.com/api/docs/guides/agents-api/sessions/webhooks
- https://developers.openai.com/api/docs/pricing

## FAQ

### What is the OpenAI Agents API?

It is a managed service, in public beta since 10 September 2026, that gives your application the Codex harness through an API. OpenAI manages sessions, orchestration, context compaction and recovery, while you provide tools and choose where the agent runs. You work with four objects: an agent, an optional environment, a durable session, and its events and items.

### How much does the OpenAI Agents API cost?

There is no separate platform fee. You pay the selected model's token rates, standard rates for OpenAI tools, and container rates for OpenAI-hosted sandboxes. The pricing page lists containers at 0.03 USD for 1 GB, 0.12 USD for 4 GB and 0.48 USD for 16 GB per 20-minute session.

### How do I steer an agent while it is working?

Send an agent.session.input.message event to the same session. If a turn is active, the message steers that turn; if the session is idle, it starts a new turn with the existing conversation. To stop the work instead, send agent.session.input.cancel, which keeps the session and its earlier work.

### Does agent.session.idle mean the task succeeded?

No. Idle only means the session is ready for more input. Check for agent.session.turn.completed, turn.failed or turn.cancelled on the root turn, and inspect the agent's output, because a completed turn can still contain failed tool calls.

### Is the OpenAI Agents API eligible for Zero Data Retention?

No. The Agents API currently supports data residency only in the United States and does not support Zero Data Retention. Choosing a self-hosted sandbox does not change that, because the harness and session state still run on OpenAI's side.

---

- HTML version: https://www.matthewswong.com/en/blog/openai-agents-api-hosted-sandbox-tutorial/
- Bahasa Indonesia: https://www.matthewswong.com/id/blog/openai-agents-api-hosted-sandbox-tutorial/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
