OpenAI Agents APIとは？使い方とAgents SDKとの違い

OpenAI Agents APIは、Agentの実行ループだけでなく、Session、context管理、回復、必要に応じた実行環境までOpenAI側で管理するクラウドAgent向けAPIです。2026年9月10日にpublic betaとして公開されました。まずはAgents SDKとの違いを押さえると、どちらを使うべきか判断しやすくなります。

まず結論：Agents APIとAgents SDKは管理する場所が違う

比較点	Agents API	Agents SDK
Agent harness	OpenAIが管理	自分のアプリ側で実行
Session	durable sessionをAPIで管理	アプリ側で実行状態を設計
実行環境	OpenAI-hosted sandboxなどを接続可能	SDK側でsandboxや実行環境を組み合わせる
向くケース	長時間・継続・クラウド実行を任せたい	実行ループやインフラを細かく制御したい

Agents APIは「modelを呼ぶAPI」だけではありません。OpenAIの現行ドキュメントでは、Codex harnessがSession、orchestration、context compaction、recoveryを管理し、必要ならAgentがファイルやコマンドを扱うEnvironmentも接続できます。

Agents APIを構成する4つの要素

用語解説：Agent
model、instructions、tools、MCP serversなど、Agentがどう動くかを定義する単位です。

用語解説：Environment
Agentがファイルを扱ったりコマンドを実行したりする場所です。処理にcomputeが不要ならEnvironmentを持たない構成も選べます。

用語解説：Session
Agent設定、会話、保存された作業を時間をまたいで継続するdurableな実行単位です。

用語解説：Events / items
Sessionへの入力や、Agentが処理中に生成する進捗・結果を追うための情報です。streamingやwebhookで状態変化を受け取れます。

最小構成ではSessionを作ってtaskを渡す

現行QuickstartではSDKのbeta.agents namespaceからSessionを作成します。OpenAI-hosted Environmentを指定すると、Agent用のsandboxもOpenAI側で用意できます。API keyはAgentのsandbox内へ置かず、アプリ側で保持します。

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "変更前に対象を確認し、実行結果を報告する",
        },
        environment={"type": "openai_hosted"},
        input="sample.txtを作成し、内容を確認して結果を報告して",
        stream=True,
    ) as events:
        for event in events:
            print(event.type)

cURLで直接呼ぶ場合は、public betaの現行仕様としてOpenAI-Beta: agents=v1 headerが必要です。公式SDKはこのbeta headerを付与します。Session操作にはAgents用のread/write権限に加え、model推論用のResponses権限も必要になるため、最小権限でAPI keyを発行します。

Sessionを継続すると、同じ作業を途中から再開できる

Sessionは1回のpromptで使い捨てるものではありません。session_idをアプリ側で保持し、同じSessionへ次の入力を送ると、会話や保存された作業を引き継いで続けられます。長い調査、複数stepの開発、途中成果物を残す処理と相性がよい設計です。

初回taskでSessionを作る
streamingまたはwebhookで進捗を追う
session_idをアプリ側の状態と紐付ける
追加指示は同じSessionへ送る
不要になったSessionは運用ルールに沿って終了・削除する

turn.completedだけで『全部成功』と判断しない

Agent処理では、最終turnが完了しても、途中のToolが期待どおり成功したとは限りません。公式Quickstartでも、agent.session.turn.completedはturnの完了を示しますが、すべてのTool成功を保証するものではないと説明されています。

見るもの	確認する内容
turn event	completed / failed / cancelledのどれか
Tool結果	errorや期待したoutputがあるか
成果物	必要なfileや変更が実際に残っているか
最終回答	実行結果とAgentの説明が一致しているか

長時間Agentほど、Agentの自己申告だけではなく、eventと成果物を分けて確認する方が運用しやすくなります。

Environmentは『Agentにcomputeが必要か』で決める

質問回答や外部Tool呼び出しだけなら、Environmentを持たない構成でも始められます。一方、ファイル編集、command実行、package利用、成果物生成が必要ならEnvironmentを接続します。OpenAI-hosted sandboxを使うと、Agentの作業場所もmanaged側へ寄せられます。

Toolだけで完結する：Environmentなしを検討
fileやcommandが必要：sandboxを接続
社内環境へ接続したい：実行境界と権限を先に定義
秘密情報：Agentの作業領域へ不用意に複製しない

（Codexそのものの役割については『CopilotとCodexの違いと使い分け10選｜VS Codeで効率化するAI開発ガイド』をご参照ください）

Agents APIを選ぶか迷ったときの判断基準

状況	判断
Session継続・回復・長時間実行をmanaged側へ寄せたい	Agents APIを先に検討
Agent loopやruntimeを自分のprocess内で細かく制御したい	Agents SDKを先に検討
file/command作業がない	EnvironmentなしのAgents APIも候補
beta変更を許容しにくい本番要件	仕様変更・制約を確認し、小さく検証してから採用

Agents APIは2026年10月2日時点でpublic betaです。動作やAPI surfaceが将来変わる前提で、beta header、SDK version、公式changelogを固定して検証する方が安全です。

最初の検証では、1つの小さなtaskをOpenAI-hosted Sessionで実行し、streaming event、成果物、最終回答の3点が一致するかを確認してみてください。

よくある質問

Agents APIを使うとAgents SDKは不要ですか？

用途が異なります。managedなCodex harnessやdurable sessionを使いたい場合はAgents APIが向きます。自分のアプリprocessでAgent loopを実行・制御したい場合はAgents SDKが向きます。

必ずOpenAI-hosted sandboxが必要ですか？

いいえ。公式Quickstartでは、command実行やfile作業が不要なAgentはenvironment.typeをnoneにできると案内されています。必要なcompute境界に合わせて選びます。

SessionがcompletedならToolも全部成功ですか？

保証されません。turnの完了eventと、各Tool結果・成果物を分けて確認してください。

ROUTE