OpenAI Agents API

// Overview

The OpenAI Agents API gives an application access to the same managed harness that runs Codex. OpenAI's documentation puts the split plainly: OpenAI manages sessions, orchestration, context compaction and recovery, while your application provides the tools and chooses its execution environment. It entered public beta on September 10, 2026 and requests carry the header OpenAI-Beta: agents=v1.

Four concepts make up the API. An Agent is a model plus instructions, tools and MCP servers. An Environment is an optional sandbox where code runs. A Session is a durable instance of that agent, and the session emits a stream of events and items that represent its inputs and outputs. Because session state is retained on OpenAI's side, work continues across turns without the application rebuilding the conversation context.

Inside a session an agent can execute code in a sandbox, edit files, connect to MCP servers over HTTP, run web search, apply skills, produce artifacts and delegate subtasks to subagents with a configurable concurrent-subagent limit. Sandboxes are either OpenAI-hosted or self-hosted. Two constraints are worth knowing before you build on it: data residency is limited to the United States, and zero data retention is unsupported even when you choose a self-hosted sandbox.

// What it does

• Managed Codex harness: OpenAI handles session orchestration, context compaction through summarization, and recovery
• Durable sessions that retain state, so work continues across turns without rebuilding the conversation context
• Two environment types — an OpenAI-hosted sandbox or a self-hosted one you provide
• Tools, web search and MCP servers over HTTP, plus programmatic tool calling and skills
• Subagents: break work into subtasks and delegate, with a configurable concurrent-subagent limit
• Progress streaming and agent steering while a session is running

// Getting started

The Agents API ships in the standard OpenAI SDK. Upgrade the client, then create a session with an agent definition, an environment and an input. The quickstart below is OpenAI's own Python example.

pip install --upgrade openai

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        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,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

OpenAI-Beta: agents=v1

Commands and code are distilled from the project's own documentation — always check the official docs for the latest.

// When to use it

• Reach for it when an agent has to keep working across many turns and you would rather not build session resumption and crash recovery yourself.
• Reach for it when context compaction is the hard part — long runs that outgrow the window and need summarizing without losing the thread.
• Reach for it to fan work out to subagents with a concurrency limit, instead of writing your own orchestration layer.
• Skip it when your data cannot leave the EU or must be under zero data retention — neither is supported today, on either sandbox type.

// How OpenAI Agents API compares

OpenAI Agents API alongside other open-source agent frameworks & builders tools AI/TLDR tracks, ranked by GitHub stars.