OpenAI Agents API Documentation
by OpenAI
OpenAI runs the agent harness — sessions, context and sandboxes — and these docs show what you give up.
Overview
The overview builds the API from four concepts. An Agent is a model plus instructions, tools and MCP server configuration. An Environment is an optional sandbox — OpenAI-provisioned or self-hosted — giving the agent file and command access. A Session is the durable instance that carries tasks and state across multiple turns. Events and Items are the inputs given to the agent and the outputs it emits while running, which is how you inspect what it did step by step. Documented subpages include a quickstart with sandbox provisioning, configuration and environment settings, multi-agent patterns using subagents and delegation, pricing, and complete application showcases. Code is shown in JavaScript, Python, Go, Java, Ruby and raw cURL against the REST endpoints. Pricing is standard model rates plus standard rates for OpenAI tools and hosted sandboxes. The docs state their own limits clearly: the API is in beta (`agents=v1`), data residency is United States only, and Zero Data Retention is not supported — material constraints for regulated teams. The distinction from the Agents SDK is architectural rather than cosmetic: the SDK runs the loop inside your process with full control, while this API moves orchestration and sandbox execution onto OpenAI's infrastructure. The 10 September 2026 Hacker News thread (346 points, 187 comments) is the useful counterweight, where the dominant criticism is lock-in to OpenAI's own models versus a portable in-house harness.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~1-2 hours for the overview, quickstart and configuration pages
- Provider
- OpenAI
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Model an agent as instructions plus tools plus MCP server configuration
- ✓Provision a hosted sandbox environment, or point the agent at a self-hosted workspace
- ✓Use durable sessions to carry tasks and state across many turns
- ✓Inspect an agent run by reading its stream of events and items
- ✓Delegate work to subagents and compose documented multi-agent patterns
- ✓Call the same API from Python, JavaScript, Go, Java, Ruby or plain cURL
- ✓Price a run: standard model rates plus OpenAI tool and hosted sandbox charges
Highlights
- •The managed-harness option spelled out: OpenAI owns session state, context optimization and recovery instead of your code
- •The docs name their own limits up front — beta (`agents=v1`), US-only data residency, no Zero Data Retention
- •Six language surfaces documented side by side, including raw REST for anything unsupported
- •Clarifies the boundary against the Agents SDK, which runs the loop in your process — the decision most teams are actually making
- •Read alongside the 10 September 2026 Hacker News thread (346 points, 187 comments), where practitioners argue the lock-in case against it
Who It’s For
Best For
- ✓Teams that want agent orchestration and sandboxing without operating that infrastructure
- ✓Engineers comparing managed harnesses against self-hosted loops before committing
- ✓Product teams shipping code-executing or file-editing agents on a short timeline
Prerequisites
- •Working knowledge of the OpenAI API and an API key
- •Understanding of tool calling, and ideally of MCP servers
- •Enough Python or JavaScript to run the quickstart
- •Awareness of your data-residency constraints, given the US-only and no-ZDR limits
FAQ
What is OpenAI Agents API Documentation?
Documentation for OpenAI's Agents API, a managed orchestration service where OpenAI runs the agent loop: session state, context optimization and recovery, plus provisioned sandboxes in which an agent can execute code, edit files and produce artifacts. It is the counterpart to the client-side Agents SDK, and these pages are the fastest way for an engineer to decide which of the two layers they actually want.
Is OpenAI Agents API Documentation free?
OpenAI Agents API Documentation is free to access.
What level is OpenAI Agents API Documentation for?
OpenAI Agents API Documentation is aimed at a intermediate audience. Recommended background: Working knowledge of the OpenAI API and an API key, Understanding of tool calling, and ideally of MCP servers, Enough Python or JavaScript to run the quickstart, Awareness of your data-residency constraints, given the US-only and no-ZDR limits.
How long does OpenAI Agents API Documentation take?
Expect roughly ~1-2 hours for the overview, quickstart and configuration pages. Most learners work through it at their own pace.
What will I learn from OpenAI Agents API Documentation?
You'll learn: Model an agent as instructions plus tools plus MCP server configuration; Provision a hosted sandbox environment, or point the agent at a self-hosted workspace; Use durable sessions to carry tasks and state across many turns; Inspect an agent run by reading its stream of events and items; Delegate work to subagents and compose documented multi-agent patterns; Call the same API from Python, JavaScript, Go, Java, Ruby or plain cURL; Price a run: standard model rates plus OpenAI tool and hosted sandbox charges.
Topics
Sources
This page was written from 2 sources, 1 on domains other than developers.openai.com.