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?
| Option | Where it runs | Who owns the main decisions | Good fit |
|---|---|---|---|
| Agents API | OpenAI-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 SDK | Inside 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 API | Your 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
- Create a Platform project and server-side API key. The current quickstart specifies
api.agents.readandapi.agents.writefor session operations andapi.responses.writefor model inference. - 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.
- 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.
- 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.
- 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_idThe 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.