How to use the OpenAI Agents API ?

The OpenAI Agents API runs OpenAI’s open-source Codex harness for you. You send POST https://api.openai.com/v1/agents/sessions with the OpenAI-Beta: agents=v1 header, an agent definition and a task; OpenAI runs the model and tool loop, keeps the session, and can provision a sandbox. There’s no Agents API fee: you pay for tokens, tools, and hosted container time ($0.03 to $0.48 per 20-minute session for the 1 GB to 16 GB sandbox sizes). It entered public beta on September 10, 2026, and OpenAI added computer use at DevDay on September 29.

Below: a first REST session, progress events, MCP tools, subagents, and the computer-use approval flow. For how it compares with OpenAI’s other agent surfaces, read Agents API vs Responses API vs Agents SDK; for the rest of the event, see the DevDay 2026 roundup. Every call is plain HTTP, so you can send it from Apidog before writing application code.

OpenAI Agents API at a glance

Sources: Introducing the Agents API, the Agents API overview, and the pricing page.

The four concepts

The docs build the API around four pieces:

• Agent: the model, instructions, tools, and MCP servers. Pass it inline, or save it and reuse its agent_id.
• Environment: an optional sandbox or computer where the agent reads files and runs commands.
• Session: a durable instance of the agent that keeps configuration, conversation, and saved work.
• Events and items: events report progress live; items are the saved messages and tool calls.

A message sent to an idle session starts a new turn; a message sent mid-turn steers it. The harness (per the architecture page, the hosted Codex instance running the model and tool loop) also handles context compaction, so you don’t configure it.

Pick an environment

environment.type decides where commands run:

• none: no compute. Remote MCP servers and your function tools still work; built-in Bash, apply-patch, workspace files, and executor MCPs don’t.
• openai_hosted: OpenAI manages a Linux sandbox with Python and Node.js in /workspace. Set container_size to small (1 GB), medium (default, 4 GB), or large (16 GB), and network.access to enabled, disabled, or restricted with allowed_domains. Files in /workspace/outputs become artifacts when a turn completes. An idle sandbox without keep-alives can be deleted after an hour.
• self_hosted: your infrastructure. You run codex exec-server on a laptop, container, or remote sandbox, and it connects outbound with a separate environment key.

The launch post lists sandbox partners Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel; the self-hosted guide adds AWS Lambda MicroVMs.

Your first session over REST

Export a key with the permissions above as OPENAI_API_KEY, then send the quickstart task with a small container:

curl --no-buffer 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", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

With stream: true, the response is the first turn’s event stream. Save the session ID from it; the rest of the lifecycle uses the same resource:

The JavaScript SDK takes the same shape. This version, adapted from the launch post, adds a tool, subagents, and a vault:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

Follow progress: stream or webhooks

Streaming. Open GET /v1/agents/sessions/{id}/events?stream=true with Accept: text/event-stream before you send input, so you don’t miss early events. Watch for:

• agent.session.turn.output_text.delta and agent.session.turn.output_text.done for text
• agent.session.turn.completed, agent.session.turn.failed, or agent.session.turn.cancelled for the outcome
• agent.session.requires_action when the agent needs a function result, an environment connection, or a computer-use approval

Three traps: agent.session.idle doesn’t mean the turn succeeded, a completed turn can contain failed tool calls, and closing the stream doesn’t stop the task. Streams don’t replay missed events, so after a disconnect, open a new stream and retrieve the session and its items.

Webhooks. Subscribe to agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle, and agent.session.failed. Note the naming: the stream says requires_action, the webhook says action_required. Payloads omit call details, so your handler retrieves the session and reads required_actions. Verify each signature (webhook signature verification); long-running API operations explains why webhooks suit multi-minute tasks.

MCP tools, tool search, programmatic tool calling, and subagents

MCP. Add a server to agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

By default OpenAI makes the connection (connection_origin: "service"), so the server must be reachable from OpenAI. Use connection_origin: "environment" for a private-network server, or stdio to start one in the sandbox. For credentials, pass transport.authorization for one session, or attach a vault credential (static_bearer or mcp_oauth) with vault_ids.

Tool search. MCP tools are discovered automatically when the model supports tool search. For many function tools, add {"type": "tool_search"} and mark functions defer_loading: true.

Programmatic tool calling. On by default: the agent gets an exec tool that runs JavaScript in an isolated V8 runtime, so it can loop over tool calls and trim large results before they reach context. Disable it with {"type": "programmatic_tool_calling", "enabled": false}.

Subagents. Set multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (the default limit is 6). Subagents share the environment’s filesystem and inherit MCP tools and web search, but can’t use function tools. A turn’s subagent_id is null for the main agent.

Computer use: the DevDay addition

Computer use gives the agent a hosted browser. Add the tool and a desktop to a hosted environment:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

The browser needs the user’s approval before visiting each new website origin, public sites included. On agent.session.requires_action, retrieve the session and find computer_use_approval_request entries. The nested request.type is one of two kinds:

• browser_origin_access: show origin and reason, then submit approve, deny, or cancel.
• browser_authentication: a sign-in form with fields, optional login options, and a credential_origin. Submit action: "submit" with the user’s values, or action: "cancel".

Both answers go back through the events endpoint:

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.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

Browser work appears as computer_use_call items with id, turn_id, title, status, and output, which carries a base64 JPEG screenshot when include_screenshots is on and one is available. Keep screenshots out of logs; they can show account data.

The computer use guide flags these caveats:

• Origin approval is not action confirmation. Approving a site doesn’t make the agent ask before each purchase or delete. If you need that, restrict the browser to resources that can’t take those actions, or use a browser runtime you control.
• Sign-in covers email, passwords, and verification codes. Passkeys and QR-code sign-in aren’t supported.
• Only the main agent can request authentication. Subagents can’t.
• Disable automatic retries on credential submissions (maxRetries: 0 in the SDK, --retry 0 in curl).
• A 202 means accepted, not that navigation or sign-in succeeded. Authentication requests expire after five minutes.
• Origin approval doesn’t override the network policy. Allow the site and its redirect domains in network too.

The recap says computer use ships “through the API and in Codex and ChatGPT Work on Pro 500 and Enterprise.” For UI-driven testing with the same model, see GPT-6 Astra computer use for API testing.

Give the agent your API, not your UI

A browser is the fallback for software without an API. If the system is yours, wrap it in an MCP server: typed tools, no origin prompts, checkable results. Computer use vs structured APIs covers the trade-off, and the Apidog MCP Server feeds your API spec to the coding assistant that writes the wrapper.

Test the Agents API in Apidog before writing code

The API is in beta, so confirm each call’s shape by hand in Apidog first:

1. Create an Apidog environment with OPENAI_API_KEY, VAULT_ID, and SESSION_ID. Send Bearer {{OPENAI_API_KEY}} and OpenAI-Beta: agents=v1 on every request.
2. Send the create-session request without stream, assert a 2xx status and a non-empty id, and extract id into SESSION_ID.
3. Open the event stream as an SSE request, send input from a second request, and watch events arrive.
4. Save the approval and cancel payloads as requests to replay each required_actions case.
5. Chain them into a test scenario and run it in CI with the Apidog CLI.

The AI agent API testing guide has assertion patterns for non-deterministic output. Download Apidog to follow along.

FAQ

Is the OpenAI Agents API free? There’s no platform fee, but you pay for model tokens, tool calls, and hosted container time.

Which models work with the Agents API? The docs’ examples, including every computer-use example, use gpt-6-astra. The pages don’t list other supported models, so test yours first.

Does the Agents API support Zero Data Retention? No. It supports US data residency only and isn’t ZDR-eligible, even with a self-hosted sandbox.

How is it different from the Agents SDK or the Responses API? The SDK runs the loop inside your app; the Responses API is the model call you build a loop around. See the full comparison.

Start with one read-only session

Begin with a session that only reads, add one MCP server, then add computer use behind an approval handler that denies by default. When ChatGPT should react to events from your own server instead, MCP Events is the matching piece.