OpenAI Agents API vs Agents SDK: Which One Should You Use?

If you want a long-running agent that edits files, runs code and survives a restart without you building a state store, use the OpenAI Agents API. If you want the loop, the storage and the approvals to live in your own service, use the Agents SDK. The two are separate products, and picking the wrong one mostly costs you in state handling and cleanup, not in model quality.

I checked the vendor pages on 30 October 2026. The guide pages are thin on pricing and on release stage, so I point to the changelog where it matters. I have not run either one: no API key was available for this post, so everything below is from OpenAI's documentation, and the one code sketch is labelled unrun.

What is the difference between the Agents API and the Agents SDK?

OpenAI's agents guide compares three options. In its own words, the Agents API is for long-running tasks where "OpenAI runs a managed Codex harness" and saves progress. The Agents SDK is for custom tools and workflows that run inside your application. The Responses API is the direct, build-it-yourself option.

The guide also lists four things that are easy to confuse: an Agents API session, an SDK session, a Responses conversation and a sandbox. They are different resources with different lifetimes. A sandbox is not a session, and deleting one does not delete the other.

What does the Agents API manage for you?

According to the overview, OpenAI manages sessions, orchestration, context compaction and recovery. You supply tools and choose the environment. A session is a durable agent instance. You create it with POST /v1/agents/sessions, passing an agent, an environment and input. Input starts a turn of work, and you follow progress by streaming or webhooks.

The managed pieces the page lists: running commands and code in a sandbox, applying skills, connecting MCP servers, steering the agent mid-task, summarising earlier work to manage context, delegating to subagents and resuming sessions.

Dated changes since launch, all from the OpenAI changelog:

• 10 September: Agents API released in public beta, with OpenAI-hosted or self-connected sandboxes.
• 29 September: computer use added, with an OpenAI-hosted browser. I compare it with Claude and Gemini in the computer use post.
• 9 October: you can pre-warm a hosted sandbox before attaching it to a session, and sandbox compute is billed during active turns.
• 16 October: hosted sandboxes include the Artifact SDK and skills, and Ultrafast mode was added.

What do you still own with the Agents API?

Less than with the SDK, but not nothing. Three things stand out in the architecture page.

1. Function tools run in your application. That application must stay available. If the handler is down, the page says the agent can wait indefinitely for a result. Put a timeout and an alert on that path.
2. Self-hosted sandboxes are yours to start, reconnect and shut down. You "own provisioning, reconnection, shutdown, and any files you need to preserve". Before stopping compute, check the turn outcome so you don't kill a pending execution.
3. Cleanup for OpenAI-hosted sandboxes is not described on that page. The overview says sessions and published artifacts can be deleted. Read the sandbox lifecycle guide before you promise a client anything about retention.

Data controls matter too. The overview says the Agents API supports data residency only in the United States and does not support Zero Data Retention. That is a hard constraint for some regulated work, so check it before you prototype. For wider context on vendor retention, see the data retention table.

What do you own with the Agents SDK?

Everything the Agents API manages, which is the point. The guide says the SDK "gives your application control over deployment, storage, approvals, and runtime integration". Its runner handles the loop and handoffs. State lives in your storage and SDK sessions, or in Responses conversation state. Tools run on your runtime.

That is more work and more control. If you need the agent to wait for a human in your own approval UI, write to your own database in the same transaction as a tool call, or run on infrastructure with no outbound path to a managed service, the SDK fits. For the SDK mechanics, see handoffs, guardrails and tracing. If you are unsure whether you need a framework at all, plain Python loop vs framework is the cheaper first question.

How do the costs differ?

The pricing statements I could verify are short:

• Agents API model usage is billed at the model's API rates. OpenAI tools use standard rates. OpenAI-hosted sandboxes use standard container rates (overview page).
• Sandbox compute is billed during active turns, not idle time between them (changelog, 9 October).
• Each model call follows the model's token and caching rules, "Cached input is still billed", and reasoning tokens bill as output (observability page).
• Usage is recorded per session and per turn, but it is best-effort, "Missing usage does not mean zero usage", and the counts are "not a final bill".

What I could not find: a sandbox rate in dollars, a minimum session charge, or any extra fee for the managed harness. The guide page itself states no pricing. Run a day of realistic traffic and compare the dashboard with your invoice before you quote a customer.

One cost that is easy to miss: with the Agents API you can't see the loop, so a runaway task is something you find out about in usage records. With the SDK you can put a step counter in your own code. If you are on the Agents API, set limits at the session level and read token budgeting for agents.

How should you decide? A table

A caution on approvals. The Agents API computer use page warns that asking for confirmation through a function tool "relies on the agent calling that function". If you need a guarantee, do not depend on the agent to ask. The pattern in human-in-the-loop approval gates puts the gate in code the model cannot skip.

An unrun sketch of creating a session

This follows the overview page's example, trimmed. I did not run it. The client.beta namespace and the gpt-6-astra model name are copied from that page as of 30 October; confirm both before use.

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer from the docs. Delegate independent lookups to subagents.",
        "tools": [{"type": "web_search"}],
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
    },
    input=[{
        "role": "user",
        "content": [{"type": "input_text", "text": "Summarise the setup steps."}],
    }],
)
print(session.id)

With self_hosted you still have to start the executor and connect it. The sketch above creates the session only.

A migration checklist if you start on one and move to the other

1. Write down which of the four resources (Agents API session, SDK session, Responses conversation, sandbox) your current code touches. They don't map one-to-one.
2. List every tool and mark where it executes. Function tools stay in your service in the Agents API.
3. Re-check data controls. Moving to the Agents API means US-only residency and no ZDR.
4. Rebuild your cost view. Per-turn session usage replaces whatever counters you kept in the loop.
5. Re-test approvals. Anything that relied on your loop pausing needs a new path.

What is unverified

• Whether the Agents API has left beta. Guide pages are silent; the changelog says public beta on 10 September.
• Sandbox prices and any limits on concurrent sessions.
• How OpenAI-hosted sandbox cleanup works.

If a later changelog entry answers any of these, trust it over this post.