OpenAI Agents API: Architecture, Pricing & Responses API Differences
The OpenAI Agents API is a managed, currently beta agent harness for durable software-engineering tasks. OpenAI manages sessions, orchestration, context compaction and recovery; your application still chooses the environment and tools and controls permissions and external side effects.
- Use the Agents API when you want managed, durable Codex-style agent sessions.
- Use the Agents SDK when your application should own the orchestration loop and handoffs.
- Use the Responses API for direct model-and-tool control without the managed agent harness.
- There is no single flat Agents API fee: model, built-in tool and hosted sandbox usage are billed separately.
What the Agents API manages
The API gives an agent a durable session in which it can run code, edit files, connect to MCP servers and produce artifacts inside a sandbox. OpenAI manages the execution harness, including turn orchestration, context compaction and recovery. The application supplies or selects the environment and exposes the tools the agent may use.
The current documentation and examples use the beta API namespace and the OpenAI-Beta: agents=v1 header. Treat the interface as beta and plan for change rather than describing it as generally available.
Agents API vs Agents SDK vs Responses API
| Option | Who runs the loop? | Best fit |
|---|---|---|
| Agents API | OpenAI managed harness | Durable cloud agents, managed sessions and sandboxed engineering work |
| Agents SDK | Your application using SDK primitives | Custom orchestration, handoffs, guardrails and application-owned workflows |
| Responses API | Your application | Direct model requests and explicit tool calls with maximum control |
How pricing works
OpenAI does not publish one flat price for an Agents API run. Budget each layer separately:
- Model tokens: charged at the selected model's normal API rates.
- Built-in tools: charged at their published tool rates when used.
- Hosted sandboxes: charged at standard container rates.
- External systems: MCP servers, databases and third-party APIs retain their own costs.
A realistic estimate therefore needs expected turns, tokens per turn, tool calls, sandbox duration and external service costs. Use the AI agent cost calculator for a workload estimate, then replace assumptions with trace data from a representative test set.
Sessions, turns and observability
A session preserves working context across turns. Traces and logs help teams inspect model calls, tool activity, timing and failures. A completed turn does not prove every requested tool action succeeded, so applications should verify important outcomes explicitly.
Security and responsibility boundaries
Expose only the tools and credentials required for the task. Validate artifacts before deployment, require human approval for irreversible actions and keep external side effects idempotent where possible.
When to choose it
- Choose Agents API for durable coding or research tasks that benefit from a managed sandbox and continuing session state.
- Choose Agents SDK when custom routing, multi-agent handoffs or application-specific control is the primary requirement.
- Choose Responses API when a straightforward request/tool loop is sufficient and you want to own state and execution.
Official OpenAI sources
- Agents API overview
- Agents API quickstart
- Agents API observability
- Agents API tracing
- Build agents with OpenAI