OpenAI Agents API vs Agents SDK

OpenAI launched the managed Agents API on 10 September 2026. Choose it when session state, compaction, and recovery are the operational bill; choose the Agents SDK when your application must own the runtime, deployment, and data path. The OpenAI Agents API vs Agents SDK decision turns on control and operations because the managed service carries no separate harness fee.

Which One Should You Pick?

The OpenAI Agents API is the better default for a small platform team shipping long-running agents. OpenAI runs the Codex harness, keeps the session and its saved work, compacts context, coordinates subagents, and supports recovery across asynchronous turns. That removes a class of infrastructure work that rarely differentiates the product. OpenAI released it in public beta on 10 September 2026 and says it is available to all developers.

For a funded founder with a small backend team and a document-review agent that can wait on approvals for hours, the managed session is worth more than owning the loop. The product team should spend its scarce time on policy, tools, evaluations, and the user experience.

The OpenAI Agents SDK is the better choice when runtime control is a requirement rather than a preference. It runs inside your application, where you own deployment, storage, approval logic, tool implementations, and state strategy. A mid-market CTO with a mandatory Zero Data Retention policy should choose this path today because the Agents API public beta does not support ZDR.

For a senior builder with an established worker fleet, custom telemetry, and a tested recovery path, moving only to avoid maintaining a modest loop is a poor trade. The SDK keeps that control and still supplies agents, tools, handoffs, guardrails, sessions, human review, and tracing.

OpenAI Agents API vs Agents SDK at a Glance

The official distinction is where orchestration runs and who owns state between tasks. Both options can call OpenAI models and tools; neither makes model tokens free.

The practical flip is simple. If your agent completes one short request inside an existing service, the SDK's ownership burden may be tiny. If it edits files, pauses for approval, survives disconnects, delegates work, and resumes tomorrow, the managed API removes more machinery with every added lifecycle state.

The Harness and the Sandbox Are Different Decisions

The Agents API manages the brain loop, but it does not force every tool to run on OpenAI compute. OpenAI calls that managed loop the Codex harness: it coordinates model calls, tool use, context, sessions, and subagents. The execution environment is a separate resource where commands run and files live.

That environment can be absent, OpenAI-hosted, or self-hosted. With no environment, the harness can still call remote MCP servers and send function calls to your application, but it has no built-in Bash, apply-patch tool, or workspace files. With an OpenAI-hosted sandbox, OpenAI provisions the Linux workspace. With a self-hosted environment, your executor runs commands and file operations while the managed harness requests them. The architecture guide makes this split explicit.

This distinction prevents two expensive mistakes. First, choosing the Agents SDK solely because code must run in your VPC is premature: the Agents API can connect to a self-hosted environment. Second, choosing the Agents API because OpenAI should run everything is also premature: application function handlers still run in your code, and a self-hosted executor leaves provisioning, reconnection, shutdown, and file persistence with you.

For a private data-analysis workflow, the managed harness could send SQL function calls to an application service without receiving a general shell. For a coding agent, it could use an OpenAI-hosted sandbox. For a proprietary build system, it could connect to your own isolated worker. Those are three execution patterns under one managed orchestration surface.

Session Ownership: Agents API Wins Long-Running Work

The Agents API wins when a task has a lifecycle longer than one application request. A session retains the agent configuration, conversation, and saved work. New input starts an asynchronous turn when the session is idle or steers the active turn while it is working. Your application can follow a stream or receive state changes through webhooks.

OpenAI also manages context compaction as a session approaches its context limit. Compaction means replacing older detail with a smaller retained representation so the agent can keep working across multiple context windows. That is easy to describe and hard to operate well: the retained summary must preserve decisions, tool results, and unfinished work without carrying every prior token forever.

Recovery is the quieter advantage. Event streams do not replay missed events. After a disconnect, the application retrieves the session and its saved items, then continues from the durable record instead of reconstructing an agent turn from process memory. The sessions guide documents the distinction between a completed turn, a failed turn, a cancellation, and a session that is merely idle.

Consider a contract-review agent for a funded founder. It reads a document, asks a specialist subagent to compare clauses, pauses for legal approval, receives a correction later, and produces an artifact. The product value is the review. Session replay, compaction, interrupted streams, and turn recovery are operating costs. This is the workload the managed API is built to absorb.

The candid limit is accounting precision. Agents may make several model calls, and root agents, subagents, retries, tools, and sandboxes all contribute to cost. OpenAI says Agents API usage fields are best-effort, may be null or change later, and are not a final bill. Reasoning tokens count as output tokens, while cached input remains billable. Use the usage guide for debugging, then reconcile against billing data for financial controls.

The dashboard is also part of the observability boundary. Detailed trace retrieval and external trace exporters are not available through the public beta customer API. If your telemetry pipeline requires programmatic export of every trace, that gap matters more than a polished managed dashboard.

Runtime and Deployment Control: Agents SDK Wins

The Agents SDK wins when your application must decide exactly how a run starts, pauses, resumes, stores state, dispatches tools, and fails. Its runner performs the agent loop and handoffs, but the loop lives inside your service. That lets product code surround every transition with your own transactions, queues, rate limits, approval records, and telemetry.

The SDK is available for TypeScript and Python, and the Python repository uses the MIT License. The package therefore has no per-seat license charge. OpenAI model calls, hosted tools, sandbox providers, and the compute running your application remain separate costs. The SDK guide positions it for code-first apps that own deployment, storage, approvals, and runtime integration.

State is flexible rather than automatic. An SDK application can replay result.history, persist an SDK session in its own storage, attach an OpenAI Conversations ID, or chain from a previous Responses API response ID. Each is useful, but the running-agents guide warns that mixing local replay with server-managed state can duplicate context unless the layers are deliberately reconciled.

That flexibility earns its keep in a regulated internal service. You can make an approval and its agent continuation part of the same database transaction, place state in an approved region, run tools behind private network controls, and fit agent execution into an existing job system. You can also integrate models or providers through the SDK's model layer rather than making the managed Codex harness the permanent orchestration boundary.

The wall is operational ownership. A process crash is now your resume problem. Duplicate queue delivery is your idempotency problem. History growth, compaction policy, tool retries, state migrations, and deployment rollback are your problems. The SDK gives you control over all of them, which is valuable only when the application uses that control.

Cost Comparison: There Is No Separate Harness Fee

The token and hosted-tool bill is the same when both runtimes use the same OpenAI model, token mix, and tool calls. Pricing was verified against OpenAI's live pages on 11 September 2026. GPT-6 Astra standard short-context pricing is $10.00 per 1 million input tokens and $50.00 per 1 million output tokens. Web search is $10.00 per 1,000 calls plus search-content tokens at the chosen model rate. The managed Agents API itself adds no separate fee.

Here is one normalized workload. These are assumptions, not observed production data:

• 1,000 agent jobs per month.
• Each job uses an aggregate 10,000 uncached input tokens and 2,000 output tokens on GPT-6 Astra. Returned search content is included in the input allowance.
• Each job makes one web-search call.
• The Agents API hosted case opens one fresh 1 GB container billing session per job at the published $0.03 rate. Reusing a sandbox would reduce this line.
• The SDK case uses one shared worker assumed to cost $40 per month and to have enough capacity. Storage, network, and labor are excluded.

The model portion is $0.10 of input plus $0.10 of output, or $0.20 per job. Across the assumed 12,000-token mix, that is $0.0167 per 1,000 blended model tokens. One web-search call adds $0.01, taking the common OpenAI spend to $0.21 per job.

At 1,000 jobs, Agents API with a fresh 1 GB hosted container for every job costs $240: $210 for the common model and search usage, plus $30 for containers. The SDK case costs $250: the same $210 of OpenAI usage, plus the assumed $40 worker. On direct spend, hosted containers win at this low volume.

At 10,000 jobs, the managed-hosted case reaches $2,400: $2,100 common spend plus $300 of containers. The SDK case reaches $2,140 on the assumed shared worker. The direct-compute crossover is 1,334 fresh container sessions per month, the first whole session count where $0.03 per session exceeds $40.

The most important row is the self-hosted Agents API case. If the Agents API uses the same assumed $40 worker, its 10,000-job total is also $2,140. The Codex harness remains managed, but the execution bill matches the SDK scenario because OpenAI does not add a harness fee.

The cash bill still misses the largest variable: engineering time. Above the crossover, saving $260 per month on compute is irrelevant if the SDK consumes several hours of platform work. Below it, a mature SDK system may cost almost nothing to keep.

For hard budget controls around either architecture, pair workload estimates with the project-level safeguards in AI Agent API Budget Controls 2026. An estimate is a planning instrument, not an enforcement mechanism.

Agents API Migration: What Moving From the SDK Costs

Moving from the Agents SDK to the Agents API is a runtime migration, not a package rename. Agent definitions and tool schemas may look familiar, but session IDs, SDK sessions, Responses conversations, Agents API sessions, and sandboxes are different resources. Treat state as data that crosses a boundary, not as an identifier that will port intact.

1. 1

   Freeze the behavior contract

   Record the current agent instructions, tool schemas, approval points, output shape, token budget, and failure policy. Keep the model and tools fixed during the comparison so a quality change is not mistaken for a runtime improvement.

2. 2

   Map agent and tool configuration

   Move the model, instructions, MCP connections, and function definitions into the Agents API configuration. Application function handlers still need a service that receives calls and returns results; they do not become hosted merely because orchestration moved.

3. 3

   Draw a state boundary

   Start new conversations as Agents API sessions and store their IDs beside the application's conversation records. Keep legacy SDK histories readable during the transition. If old context must continue, transform only the necessary business state into an explicit input rather than pretending an SDK session is an Agents API session.

4. 4

   Replace lifecycle plumbing

   Swap the in-process runner entry point for session creation, events, saved items, required actions, webhooks, cancellation, and deletion. Add idempotency around every webhook and function result because managed state does not remove duplicate-delivery risk from your application edge.

5. 5

   Shadow and regress

   Run the same evaluation set through both paths. Compare task success, total input and output tokens, tool calls, elapsed time, recovery behavior, and human intervention. Move traffic only after the new path meets the old contract.

An illustrative migration budget makes the trade concrete. Assume an existing workflow has three function tools, persistent sessions, and human approval. Allocate 24 engineering hours at $150 per hour: 6 hours for configuration and tool mapping, 8 for session and lifecycle work, 6 for webhook, recovery, and idempotency handling, and 4 for regression and cost checks. That is a $3,600 one-time migration.

If managed compaction, recovery, sessions, and orchestration save an assumed 6 engineering hours each month, the labor saving is $900 per month and payback is four months. If the current SDK path needs only occasional attention, the payback can disappear. The assumptions are the point: migration is justified by removed operations, not by a cheaper token.

Who Should Not Switch to the Agents API

Do not switch if the public beta's data controls fail procurement. The current Agents API overview says data residency is limited to the United States and Zero Data Retention is unsupported. A self-hosted sandbox does not change that policy because the harness and session still live in the managed service.

Stay on the Agents SDK when any of these is true:

• Your runtime must execute under a custom scheduler, transaction boundary, or latency envelope that the application controls directly.
• Your storage, trace-export, or data-residency policy cannot fit the managed public beta.
• Your agent uses provider flexibility or a model abstraction that should not depend on the Codex harness.
• Your SDK system already has reliable compaction, recovery, observability, and deployment, with little ongoing maintenance.
• Most work is short-lived and stateless, so a durable managed session removes little infrastructure.

Public beta is also a release-stage decision. OpenAI says it will iterate quickly before general availability. A team with a rigid change-control calendar may prefer to evaluate now and migrate after the contract stabilizes.

The SDK has its own skip case. A lean startup should not choose it merely to avoid theoretical lock-in while quietly rebuilding sessions, recovery, sandbox lifecycle, and orchestration. Control that the product never uses is maintenance debt.

For agents that need code execution, compare the environment layer separately with Best AI Agent Code Sandboxes 2026. Sandbox selection cannot answer who should own orchestration state.

Treat Customer Results as Directional, Not Portable

The early numbers favor the managed path, but they are customer reports published in OpenAI's 10 September launch post, not a controlled independent benchmark. SafetyKit reported a 60% reduction in cost per case. Hypha reported an 86% reduction in failed agent responses after separating the managed harness from its sandbox. Ciridae reported an evaluation-score increase from 0.71 to 0.85 and a 4x latency reduction.

Those outcomes prove that the runtime boundary can matter. They do not establish what your migration will save because the post does not normalize the customers' prior architecture, model mix, token volume, task difficulty, or engineering labor. Use the reports to justify a shadow evaluation, not a forecast.

OpenAI Agents API and Agents SDK FAQ

Why use OpenAI agents SDK?

Use the OpenAI Agents SDK when your application needs direct ownership of deployment, storage, approval decisions, tool implementations, and the runtime loop. It gives you OpenAI's agent primitives without moving orchestration into the managed Agents API.

Which is better for me, OpenAI agents SDK or PydanticAI?

That is a separate framework comparison. First decide whether you want OpenAI to manage the Codex harness through the Agents API or want an application-owned SDK runtime; then compare SDK frameworks inside the second path.

Which AI agent SDK is best?

No SDK is best for every architecture. The OpenAI Agents SDK is a strong fit when its TypeScript or Python loop, tools, handoffs, guardrails, sessions, and OpenAI integrations match your application and you want to own deployment.

Is OpenAI agent SDK free?

The Python Agents SDK is MIT-licensed, so the package has no license fee. You still pay for model calls, paid tools, sandbox services, and the infrastructure that runs your application.

How to use OpenAI Agent SDK?

Install the official TypeScript or Python package, define an agent with instructions and tools, choose one state strategy, and run it inside your application. Add approvals, persistence, tracing, and sandboxing only where the workflow needs them.

How much does an OpenAI agent cost?

Add model input, cached input, output, tool calls, sandbox or application compute, third-party services, and operations labor. There is no separate Agents API harness fee; under this article's assumptions, direct environment cost flips at 1,334 fresh 1 GB container sessions per month against a $40 shared worker.

Is OpenAI API free or paid?

OpenAI API model and paid-tool usage is metered under API pricing. A ChatGPT plan is a separate product contract and does not cover an Agents API or Agents SDK application's API usage.

Why pay $20 for ChatGPT?

That is a ChatGPT subscription decision, not an Agents API-versus-SDK decision. A ChatGPT subscription buys access to the ChatGPT product under its plan terms; OpenAI API usage is billed separately.

Is OpenAI Agent Builder free or paid?

Agent Builder was included with standard API model pricing, but it is not either runtime compared here. OpenAI says it is winding Agent Builder down and that it is scheduled to shut down on 30 November 2026.

The Monday Move

Pick one long-running workflow next week and run a shadow comparison. Hold the model, instructions, token budget, tools, and evaluation set constant. Put new test conversations on the Agents API, keep existing user histories on the SDK path, and choose the same execution environment on both sides if you want to isolate the value of the managed harness.

Record task success, aggregate tokens, paid tool calls, sandbox billing sessions, recovery incidents, human intervention, and engineering time. Choose the Agents API if the removed session and recovery work outweighs the control you surrender. Keep the Agents SDK if the managed service fails a data requirement or saves too little operating time to recover the migration cost.

Before changing an agent runtime, get the AI Business Workflow Audit Checklist.