Skip to content
Independent guide · Developer & API Guides

OpenAI Agents API Explained

Understand what the managed Agents API runs, how it differs from the Agents SDK and Responses API, and how to build a session using current official documentation.

Updated 29 October 2026 · Independent of OpenAI

At a glance

What the OpenAI Agents API does

The OpenAI Agents API exposes the Codex harness through an OpenAI-managed API. Your application creates a session, configures an agent, supplies work, and receives events and output. OpenAI manages the agent runtime and session orchestration; you still choose tools, access, environment, and how your application handles outcomes.

This is a developer API for building durable cloud agent workflows. It is different from a ChatGPT dot, which is a user-facing assistant, and different from the Agents SDK, which runs an agent loop in your own application.

The current Agents overview groups the choices this way: use the Agents API when you want OpenAI to run the managed harness and preserve session progress; use the Agents SDK when your app owns runtime and orchestration; use the Responses API when you want the model interface and intend to build the loop yourself.

Availability changes: API endpoints, SDK support, scopes, model access, and environment options can evolve. Verify implementation details in the official quickstart and API reference before deploying.

Choose the runtime

Agents API, Agents SDK, or Responses API?

OptionWhere it runsWho owns the main decisionsGood fit
Agents APIOpenAI-managed Codex harness, with hosted, self-hosted, or no sandbox options as documented.OpenAI manages session infrastructure; your app configures tools, inputs, environment, event handling, and application-level approvals.Long-running work where you want durable sessions, managed orchestration, streaming events, and a managed environment.
Agents SDKInside your application runtime.Your service owns deployment, tools, state storage, and approval decisions; the SDK provides an agent loop and higher-level primitives.Code-first workflows where you need direct control over runtime behavior, tool implementations, and app integration.
Responses APIYour application calls the model API.Your app owns the loop, tool dispatch, and state strategy, while using Responses for model interaction and supported tools.Direct model responses or a custom agent design where you want to control orchestration yourself.

These products overlap in the broad task of building agentic software, but they are not interchangeable names for one endpoint. The Agents API vs. Agents SDK vs. Responses API comparison maps the main tradeoffs. Choose a runtime for the responsibilities you want your application to own.

Prerequisites

What to prepare before your first session

  1. Create a Platform project and server-side API key. The current quickstart specifies api.agents.read and api.agents.write for session operations and api.responses.write for model inference.
  2. Keep credentials outside the agent environment. Load the key in your application’s server environment. Do not place it in browser code, source control, task input, or files the agent can read.
  3. Choose an execution environment. An OpenAI-hosted sandbox is the quickstart path for code execution. The API also documents self-hosted and no-sandbox choices; select according to the task and current environment requirements.
  4. Define the tool and data boundary. Give the agent only the functions, MCP connections, files, or sandbox capabilities needed for the task. Separate read-only work from actions that change external state.
  5. Plan how your service handles events. Decide how to display progress, handle required actions, report errors, and let a user continue or steer a session.

Requests use the Agents API versioning header. OpenAI’s SDKs add OpenAI-Beta: agents=v1 automatically; raw HTTP clients must send it as documented. Confirm current authentication scopes, model availability, and API reference fields for your project before implementing.

Session, SDK session, Responses conversation, and sandbox are different resources. Keep the state model and cleanup steps specific to the runtime you select.

Illustrative example

Create a session and stream its first turn

The following example follows the current OpenAI Python SDK quickstart. It creates an agent session with an OpenAI-hosted sandbox, submits a small file task, streams events, and reads the collected result. It is an illustrative developer example and was not executed as part of this page update. Use a model available to your Platform project and compare the code with the current official quickstart before running it.

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,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()

    print(result.output_text)
    session_id = result.session_id

The quickstart requires an application API key and shows the SDK’s beta.agents.sessions.create namespace. The example creates a sandboxed coding task, so it should not be copied into an app without reviewing the sandbox’s file, command, network, and resource limits.

For a question-answering or tool-only agent that does not need command execution or local files, the official quickstart describes environment.type as none. Confirm that the selected task and tools fit that environment.

Implementation flow

A practical implementation sequence

  1. Configure the agent. Specify the model, instructions, and only the tools or MCP connections the task needs. Keep the requested outcome and approval policy explicit.
  2. Create the session with an initial task. Choose an environment, provide the input, and enable streaming when your interface needs progress from the first turn.
  3. Consume events and required actions. Show useful progress to the user. If the session requires a function result or environment connection, inspect the required action and handle it deliberately.
  4. Check the turn outcome and output. Handle completed, failed, and cancelled outcomes. A terminal event is not evidence that each tool succeeded; inspect the output and tool result details.
  5. Continue or steer the same session. Use the returned session ID to send a follow-up task when the application needs the existing context. Subscribe to events before submitting messages if you need early progress.
  6. Manage retention and recovery. Decide when sessions and created artifacts are no longer needed, and use documented cleanup endpoints. Build retries around idempotency and observed failures instead of replaying an action blindly.

OpenAI’s session documentation describes durable sessions, streaming events, steering, webhooks, and outcome handling. Your application still needs explicit timeouts, cancellation behavior, logging, user-visible errors, and a safe recovery path.

Permissions and observability

Plan for tools, approvals, and failures

The agent can only use tools and resources made available through its configuration and execution environment. Keep secrets out of the sandbox, limit network and file access to the task, and make any external write action identifiable before it runs. The API runtime does not replace your application’s permission model or product-specific approval policy.

For observability, record the session ID, event type, relevant tool result, and final outcome in the application’s normal logging system. Avoid logging secrets or unnecessary personal data. Treat output as untrusted until it passes the validation your product requires.

  • Completed: inspect the result and confirm it contains the required evidence.
  • Failed: read the error and recovery guidance, then decide whether retrying is safe.
  • Cancelled: preserve the cancellation state and avoid presenting partial work as complete.
  • Waiting for input: resolve the documented required action or return a clear request to the user.

For computer access, sandbox security, and integration details, use the official API documentation linked below. The existing computer-use guide and MCP and plugin guide cover adjacent implementation topics.

Related reference

Continue with the right developer guide

Start with the official quickstart when you are ready to make your first API request. Use the comparison guide to choose a runtime, then consult the relevant API reference for exact parameters and event fields.

OpenAI Agents API quickstart · Agents API overview · Agents runtime comparison · Agents SDK overview

On Dots-Bot, continue to Agents API vs. Agents SDK vs. Responses API, the Developer & API Guides hub, or the specific computer-use and MCP references relevant to your design.

Planning template

Define a bounded API prototype

Use this short plan before creating a session. Fill in only the requirements for your actual application.

Your review

Check the prototype before production

0 of 6 checked

Questions

OpenAI Agents API FAQ

What is the OpenAI Agents API?

The Agents API gives an application access to OpenAI’s managed Codex harness through a durable session. OpenAI manages session orchestration and the managed environment; the application configures the agent, supplies inputs, handles events and required actions, and chooses an environment.

How is the Agents API different from the Agents SDK?

The Agents API runs a managed harness in OpenAI’s service. The Agents SDK runs its agent loop inside your application, where your server owns deployment, tools, storage, and approval decisions.

How is it different from the Responses API?

The Responses API is the lower-level interface for model responses and tool calls. Your application can use it directly and own orchestration and state, or use a higher-level agent runtime where that fits the design.

What credentials and permissions does the quickstart require?

OpenAI’s current quickstart calls for an application API key with api.agents.read and api.agents.write for session operations and api.responses.write for model inference. Keep the key on your server and outside the agent sandbox.

Does a completed event prove every tool succeeded?

No. Inspect the final output and relevant events or required actions. OpenAI’s session guide says an idle session alone does not mean a turn succeeded, and a completed turn does not guarantee every tool succeeded.

Can the Agents API run without a sandbox?

The documentation supports an environment type of none for agents that answer questions or call external tools without running commands or working with local files. Check current environment limits and requirements before choosing it.