OpenAI Agents API Explained: Pricing, Setup and Agents SDK Differences

What is the OpenAI Agents API?

The Agents API exposes the same broad class of agent harness infrastructure that OpenAI uses behind Codex. A harness is the layer around the model that manages the repeated loop of understanding a task, choosing tools, executing work, inspecting results, preserving relevant context, recovering from failures, and deciding what to do next.

Without a managed harness, a developer often has to write a large amount of orchestration code: maintain state, decide when context should be summarized, handle tool definitions, retry failed steps, recover a long task after an environment disappears, and coordinate specialist agents. The Agents API moves much of that infrastructure into an OpenAI-managed service.

OpenAI describes the current product as a durable cloud-agent API. Your application supplies the task, model, tools, and environment. OpenAI manages the session and agent loop around them. Agents can execute code, edit files, connect to MCP servers, use supported tools, and produce downloadable artifacts.

That does not mean OpenAI must host your working environment. The harness and the compute environment are separate choices. Your code can use an OpenAI-hosted sandbox, a compatible partner environment, or your own infrastructure depending on where your files, secrets, dependencies, and regulated data need to live.

Official overview: OpenAI — Agents API and Introducing the Agents API.

Agents API pricing: there is no extra harness fee in public beta

OpenAI’s launch announcement says the Agents API is available in public beta to all developers with no additional fee for using the Agents API itself. That wording is important: it does not mean an agent is free to run.

The current documentation separates the bill into the resources your agent consumes. Model calls are charged at the chosen model’s normal API rate. OpenAI tools use their standard rates. If you select an OpenAI-hosted sandbox, the sandbox uses OpenAI’s standard container pricing. Any third-party sandbox, MCP service, database, storage provider, or external API can add its own cost outside OpenAI.

The practical takeaway is to measure cost per completed business task, not only tokens. An agent that works for twenty minutes, launches subagents, searches multiple systems, and runs code can have several cost sources even though the managed harness itself currently has no extra beta fee.

Pricing: OpenAI’s launch pricing statement, Agents API overview, and OpenAI-hosted sandbox pricing guidance.

Agents API vs Agents SDK: the difference is who operates the harness

The names are similar because both products help developers build agents, but they sit at different layers of your architecture.

OpenAI’s April 2026 Agents SDK update added a more capable model-native harness, configurable memory, sandbox-aware orchestration, Codex-style filesystem tools, MCP integration, skills, AGENTS.md instructions, shell execution, file patching, and portable sandbox manifests. It is meant for teams that want the harness in their own application and need flexibility over how it behaves.

The Agents API takes the opposite operational choice: OpenAI keeps that harness running and improving for you. The launch announcement says the API is powered by the open-source Codex harness, so developers can inspect the public foundation while using OpenAI’s managed version in production.

Simple rule: choose the Agents API when you want less harness infrastructure to operate. Choose the Agents SDK when owning and customizing more of that harness is part of the product requirement.

Sources: Agents API launch and The next evolution of the Agents SDK.

You choose where the agent runs code and works with files

The managed Agents API does not force every workload into an OpenAI sandbox. OpenAI deliberately separates the harness from the execution environment.

OpenAI-hosted sandbox

Fastest route to a managed workspace. OpenAI provisions the environment so the agent can run code, work with files, install allowed dependencies, and produce artifacts.

Your infrastructure

Use your own environment when data locality, proprietary networking, existing compute, or internal security architecture makes self-hosting preferable.

Sandbox partner

OpenAI lists first-class integrations with providers including Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, and Vercel.

In an OpenAI-hosted sandbox, each session receives a separate workspace. Files can persist across turns while the sandbox remains alive, and files written under /workspace/outputs are published as immutable artifacts when a turn completes. OpenAI says an inactive connected sandbox can be deleted after one hour without activity or keep-alives, so outputs that matter should be saved deliberately rather than treated as permanent workspace storage.

Network access can also be restricted. For workflows that only need supplied files and local computation, disabling network access gives the agent a narrower execution boundary.

Environment details: OpenAI-hosted sandboxes and Agents API environment choices.

Basic Agents API setup

The current quickstart uses the standard OpenAI SDK and the beta Agents namespace. A session request can define the model, instructions, environment, task input, and streaming behavior in one call.

1. Create or choose an OpenAI API project. Configure API billing, spend controls, and the project key you will use from your trusted backend.
2. Install the current OpenAI SDK. For Python, OpenAI’s quickstart uses pip install --upgrade openai; JavaScript uses npm install openai.
3. Choose the model. OpenAI’s launch and quickstart examples use gpt-6-astra, but the model should match the task’s difficulty, cost, and latency requirements.
4. Choose the environment. Start with openai_hosted when you want the simplest managed code-and-files workspace.
5. Give the agent one concrete task. Include the expected outcome, important constraints, allowed tools, and where outputs should be saved.
6. Stream or observe events. Treat the agent as a long-running process with progress, tool calls, files, and task state rather than expecting one immediate text completion.

The API is still in beta, so copy current examples from OpenAI’s documentation rather than assuming an older Agents, Assistants, or Responses example uses the same resource names.

Setup: Agents API quickstart and current agent API reference.

Sessions are designed for work that can span many steps and context windows

One of the strongest reasons to use the Agents API is durability. OpenAI manages session state and the agent loop so a task can continue across many tool calls and longer periods of work without forcing your application to reconstruct the full prompt after every step.

As a session approaches the model’s context limit, the Agents API can automatically compact earlier context while preserving information needed to continue. That allows workflows to cross multiple context windows without the developer implementing the entire compaction strategy manually.

Separating state from the sandbox also improves recovery. The working compute environment can be replaced without necessarily losing the full logical agent session. For production systems, that distinction matters: a container is disposable compute; the agent session is the durable work record.

Closing a streaming connection is also not the same thing as cancelling a running task. Your application should use the session and cancellation semantics in the current documentation rather than assuming a dropped client connection stopped the agent.

Long-running behavior: OpenAI’s long-session overview and sandbox lifetime guidance.

Tools can be loaded and used more selectively

Large agents can have access to dozens or hundreds of tools. Loading every schema into every model call wastes context and makes tool selection harder. The Agents API includes tool-search behavior that can load relevant definitions when needed, helping preserve model cache and reduce unnecessary token use.

OpenAI also supports programmatic tool calling so agents can run independent operations in parallel, chain related steps, filter data, and combine results before bringing the most useful information back into context.

Current Agents API tooling includes MCP connections, custom functions, plugins, vaults, web search, and other supported OpenAI tools. The practical design rule is to expose the smallest permission set required for the task. A research agent usually should not receive the same write permissions as a deployment agent.

Tools: OpenAI on tool search and programmatic tool calling and Agents API documentation.

Multi-agent support lets one session parallelize specialist work

The Agents API can create and coordinate subagents for tasks that divide cleanly into independent workstreams. Each subagent gets its own focused context while the main agent coordinates the assignments and combines the results.

OpenAI’s launch example enables multi_agent and sets max_concurrent_subagents. A service incident could delegate deployment history, error logs, and dependency health to separate specialists. A research workflow could send different markets or source groups to parallel agents before the primary agent synthesizes the findings.

Parallelism is useful when the subproblems are genuinely independent. It is not automatically cheaper. Several agents running simultaneously can increase model and tool consumption, so compare the latency benefit with total cost and evaluation quality.

Also avoid using subagents as a substitute for clear architecture. If every small action becomes a specialist agent, tracing failures and permissions can become harder than the original task.

Multi-agent support: OpenAI’s subagent overview.

Treat the sandbox as untrusted execution and keep authority outside it

Agents can read files, execute model-generated code, call tools, and interact with external systems. That makes permission design part of the application, not an optional hardening step after the prototype works.

Keep permanent secrets out of the sandbox

Store API keys and privileged credentials in trusted infrastructure. Give the agent narrow temporary access only when the task requires it.

Assume prompt injection is possible

Documents, webpages, repositories, and tool outputs can contain instructions that conflict with your application’s intent.

Separate read and write capabilities

A system that needs to inspect production should not automatically have authority to modify production.

Require approval for consequential actions

Deployments, payments, deletions, external messages, access-control changes, and similar actions should have explicit policy and confirmation boundaries.

Save evidence and artifacts

Keep the files, events, logs, or structured results required to understand what the agent actually did.

OpenAI’s Agents SDK guidance explicitly recommends designing agent systems under the assumption that prompt-injection and exfiltration attempts will occur. Separating harness, compute, credentials, and durable state makes it easier to recover safely when something fails.

Security architecture: OpenAI’s Agents SDK security guidance and sandbox documentation.

Should you use the Agents API or the Agents SDK?

Use the Agents API when the main thing you want to avoid building and operating is the durable agent harness itself. It is a strong fit for long-running cloud tasks, managed sessions, context compaction, recovery, hosted or connected sandboxes, and parallel subagents where you want OpenAI to operate the orchestration layer.

Use the Agents SDK when the harness must be deeply integrated into your own runtime and you want direct programmatic control over its behavior. The SDK is a better fit when custom orchestration, memory design, handoffs, guardrails, provider choices, local execution, or infrastructure integration are core product requirements rather than implementation details you want managed.

You can also prototype with the SDK to understand the agent loop and later move a suitable workload to the managed API, or use different approaches for different products. The decision is not “which one is more intelligent?” Both ultimately depend on the model, context, tools, environment, and quality of the workflow. The main distinction is who owns the operational harness.