Building Agents With OpenAI's Agents API

Lesson 1: What the Agents API actually is

OpenAI's Agents API gives applications managed access to the same Codex agent harness that powers Codex and cloud agents in ChatGPT, exposed through an OpenAI-managed API rather than a framework you run yourself. Per OpenAI's official documentation, OpenAI handles session orchestration, context compaction across long tasks, sub-agent coordination, and crash recovery. Your application supplies the task, the tools, and the execution environment.

This sits alongside, not instead of, the code-first Agents SDK — OpenAI's other path for building agents directly in Python or JavaScript. The Agents API is the managed option: you send a task to an OpenAI-hosted session and get back structured events, rather than owning the orchestration loop yourself.

Lesson 2: The four core concepts

Everything in the Agents API is built from four objects, per OpenAI's overview docs:

• Agent — the model, instructions, tools, and MCP servers available to the agent.
• Environment — an optional sandbox or compute resource where the agent accesses files, loads skills, and executes commands. Set type to openai_hosted for a managed sandbox, or none for a tool-only agent with no local file access.
• Session — a durable instance of an agent working on tasks and responding to input; sessions persist state across multiple turns so you don't reconstruct conversation context yourself.
• Events and Items — the inputs sent to the agent and the outputs it streams back as it works, including status events like agent.session.turn.completed, turn.failed, and session.idle.

Lesson 3: Your first session

Sessions are created with client.beta.agents.sessions.create(). Per the Agents API quickstart, a minimal Python call looks like this:

client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra", "instructions": "..."},
    environment={"type": "openai_hosted"},
    input="Create tree.py that prints a directory tree",
    stream=True
)

Requests need the header OpenAI-Beta: agents=v1 and an application API key granting the api.agents.read, api.agents.write, and api.responses.write permissions. The docs show working examples in Python, JavaScript, Go, Java, Ruby, and cURL. Once a session starts, grab its session_id from the initial events to send follow-up prompts to the same running session, and call client.beta.agents.sessions.delete(session_id) once you've saved whatever artifacts the agent produced.

Lesson 4: Giving agents tools

Per OpenAI's documentation, agents built on the Agents API can use MCP (Model Context Protocol) server connections, custom functions, web search, and programmatic tool calling, and can delegate work to up to four concurrent sub-agents for parallel work on a larger task. If you've already built MCP servers for another client, the same servers plug directly into an Agents API agent's tool list.

The sandboxed environment itself is also a tool surface: an agent with environment.type set to openai_hosted can execute code, edit files, and produce artifacts inside that sandbox as part of completing a task, not just call out to external APIs.

Lesson 5: Choosing where the agent runs

Beyond OpenAI's own managed sandbox, OpenAI has partnered with a set of third-party compute providers for the Agents API: Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel, according to reporting on the public beta launch. Each offers first-class integrations covering fully managed environments or deployment inside your own VPC, with different CPU, GPU, memory, cold-start, and cost profiles — you can generally swap providers by changing which sandbox client class you instantiate, without rewriting your agent logic.

On pricing: there's no separate platform fee for the Agents API itself. You pay standard token rates for whichever model you select, plus standard rates for any tools, MCP connections, or hosted sandbox compute the agent actually uses — the same reporting confirms this is usage-based, not a flat subscription on top of the API.