何が変わったか
従来のResponses APIでは、アプリ側がモデルを呼び出し、必要に応じてツール実行の結果を返す設計が中心でした。Agents APIでは、その繰り返しを「エージェントのセッション」として管理し、作業途中の状態やイベントを保持できます。
| 項目 | Agents APIで扱えること |
|---|---|
| 作業状態 | セッション単位で会話や進捗を保持する |
| 実行環境 | OpenAIホスト環境か自社・パートナー環境を選ぶ |
| ツール | シェル、コード実行、MCPなどを接続する |
| 長時間処理 | コンテキスト圧縮や中断後の再開を管理する |
| 複数エージェント | サブエージェントへ仕事を分ける |
OpenAIの説明では、基盤にはCodexのエージェント実行系が使われています。単発のプロンプト応答よりも、リポジトリを調べてファイルを直す、社内ツールから情報を集めて成果物を作る、といった工程の多い仕事を想定した仕組みです。
ただし、Agents APIが仕事の目的や権限を自動で決めてくれるわけではありません。どの環境を渡すか、何を実行してよいか、完了をどう判定するかは、導入側が設計する必要があります。
4つの基本要素
公式ドキュメントは、基本要素をAgent、Environment、Session、Eventsの4つに整理しています。導入時は、この4つを分けて考えると構成を理解しやすくなります。
| 要素 | 役割 | 設計時の確認点 |
|---|---|---|
| Agent | 指示、モデル、ツール、スキルを定義 | 何を任せ、何を禁止するか |
| Environment | ファイルやコマンドを扱う作業場所 | OpenAI、自社、パートナーのどこで動かすか |
| Session | 一連の作業状態を保持 | どこまでを同じ仕事として扱うか |
| Events | 実行中の出来事をストリームで通知 | 成功、失敗、承認待ちをどう表示するか |
環境はOpenAIがホストするコンテナだけに限定されません。自社インフラや、Vercel Sandbox、E2Bのようなパートナー環境も接続できます。機密ファイルを扱う場合は、モデルに送られる情報と、作業環境内だけに残る情報を分けて設計することが重要です。
Vercelは、セッションごとに隔離したSandboxと永続ワークスペースを組み合わせる統合例を公開しています。E2Bも、チャットごとに専用Sandboxを割り当てる実装例を案内しました。Agents APIは実行環境そのものを一種類に固定するのではなく、エージェントの制御面と作業場所を分離する考え方です。
SDKとの違い
名前が似ていますが、Agents SDKとAgents APIは置き換え関係ではありません。SDKはエージェントの処理をアプリ側で組み立てるための部品で、APIはセッションや環境を含む実行基盤をサービスとして使う選択肢です。
| 比較点 | Agents SDK | Agents API |
|---|---|---|
| 主な役割 | 処理の流れをコードで構成 | 実行管理をマネージドで提供 |
| 状態管理 | アプリ側で設計する | セッションとして扱える |
| 実行環境 | 開発者が用意する | OpenAIまたは外部環境を接続 |
| 制御の自由度 | 細かく設計しやすい | 共通機能を早く利用しやすい |
| 運用負荷 | 監視や再開も自前になりやすい | 圧縮、回復、イベント管理を任せやすい |
単純な問い合わせ対応や、数回のツール呼び出しで終わる処理なら、Responses APIやSDKだけで十分な場合があります。一方、数分以上続く調査、コード変更、複数システムをまたぐ定型業務では、セッションと環境をまとめて管理できるAgents APIの価値が出ます。
AIエージェントの方式を広く比較したい場合は、TechCreateのAIエージェントフレームワーク比較も参考になります。今回のAPIは、その中でも「実行基盤をどこまでサービス側に任せるか」という判断軸を強めるものです。
最小構成で試す
JavaScript向け公式SDKでは、openaiパッケージのベータ名前空間からAgentの設定を含むSessionを作成します。開始前にAPIキーへ api.agents.read、api.agents.write、api.responses.write の権限を付けます。
npm install openaiでSDKを追加する- Agentにモデルと指示を設定する
- Sessionに作業環境と依頼内容を渡す
- Eventsを読み、ツール失敗や承認待ちを確認する
- 完了条件を満たした成果物だけを保存する
import OpenAI from 'openai'
const client = new OpenAI()
const events = await client.beta.agents.sessions.create({
agent: {
model: 'gpt-6-astra',
instructions: '変更内容を調べ、根拠付きでレビューする',
},
environment: { type: 'openai_hosted' },
input: 'このリポジトリを調べ、変更点をレビューしてください',
stream: true,
})
実際のフィールドはSDK更新で変わる可能性があるため、実装時は公式Quickstartの最新版を確認してください。直接HTTPで呼ぶ場合は、現時点で OpenAI-Beta: agents=v1 ヘッダーが必要です。公式SDKはこのヘッダーを自動で付けます。
注意したいのは、セッションの完了イベントが届いても、途中の全ツールが成功したとは限らない点です。Eventsを確認し、コマンドの失敗、権限不足、ユーザー承認待ちをアプリ側で区別する必要があります。
料金の読み方
OpenAIは、Agents APIそのものに追加料金は設定していません。実際の費用は、利用したモデルの入出力トークン、Web検索などのツール、OpenAIホストのコンテナ利用料で決まります。
| 費用項目 | 公式の案内 |
|---|---|
| Agents API | 追加料金なし |
| モデル | 選んだモデルのトークン料金 |
| Web検索 | 1,000回あたり10ドルに加え、検索内容のトークン料金 |
| 1GBコンテナ | 20分あたり0.03ドル |
| 4GBコンテナ | 20分あたり0.12ドル |
| 16GBコンテナ | 20分あたり0.48ドル |
| 64GBコンテナ | 20分あたり1.92ドル |
公式料金表は、各容量の金額を「コンテナごとの20分セッションあたり」で示しています。一方、同じ料金ページでは、対象となるコンテナセッションは分単位で請求され、1セッションあたり最低5分と説明されています。つまり、表の金額は20分利用時の基準額で、短時間の対象セッションは5分を下限に利用時間分が請求されます。
長時間エージェントでは、モデル料金だけを見積もると費用を過小評価します。1セッションの平均時間、同時実行数、コンテナ容量、Web検索回数を分けて試算するのが安全です。
モデルごとの料金や特性を確認したい場合は、GPT-6 Astraの料金と機能も参照できます。ただし、Agents APIは特定モデル専用ではないため、処理の難易度に合わせてモデルを選ぶ設計が基本です。
導入前の制約
現時点のAgents APIは公開ベータです。本番の重要業務へ組み込む前に、次の条件を確認しておく必要があります。
| 制約 | 実務への影響 |
|---|---|
| 公開ベータ | API仕様やSDKの変更を見込む |
| データレジデンシーは米国のみ | 地域要件がある業務は適合性を確認する |
| Zero Data Retention非対応 | 厳格なデータ保持要件にはそのまま使えない |
| 自社SandboxでもZDR対象外 | 実行場所だけ変えてもAPI側の条件は変わらない |
| ツール成功は別途確認 | 完了イベントだけで業務完了と判定しない |
特にデータ保持条件は、作業環境を自社で用意すれば自動的に解決するものではありません。公式ドキュメントは、自己ホスト型Sandboxを選んでもAgents API自体はZero Data Retentionの対象にならないと説明しています。顧客情報、未公開コード、規制対象データを扱う場合は、送信範囲を絞り、組織の法務・セキュリティ要件と照合してください。
また、外部ツールへ書き込む権限を与える場合は、読み取りと更新を分離し、削除や公開などの重要操作には人の承認を挟む設計が必要です。APIが長時間処理を支えても、権限設計と監査ログの責任までなくなるわけではありません。
向いている用途
Agents APIは、工程が多く、途中状態を保ちながら完了まで進めたい仕事に向いています。逆に、低遅延の一問一答では構成が重くなる可能性があります。
- リポジトリを調査し、修正案や成果物まで作る開発支援
- 複数の社内システムを横断する調査とレポート作成
- 長い文書や大量ファイルを扱うレビュー業務
- 人の承認を途中に挟むバックグラウンド処理
- サブエージェントへ役割を分ける複雑なタスク
まずは、失敗しても外部へ影響しない読み取り中心の業務から試すのが現実的です。たとえばコードレビューや社内資料の要約で、1件あたりの時間、費用、失敗率、手戻りを測ります。そのうえで更新権限を段階的に追加すると、便利さだけでなく運用コストも比較できます。
GoogleのAgent Development Kitを含む別の実装方法は、ADK for Kotlin 1.0の解説で確認できます。特定クラウドや言語との相性を重視する場合は、Agents APIだけで決めず、既存の開発基盤との接続性を比べることが重要です。
まとめ
- OpenAI Agents APIは、モデル呼び出しに加えて、作業環境、セッション、ツール実行、再開までを管理するエージェント実行基盤です。
- APIの追加料金はありませんが、モデル、ツール、コンテナの費用を分けて見積もる必要があります。
- 公開ベータ、米国のみのデータレジデンシー、Zero Data Retention非対応を踏まえ、読み取り中心の小さな業務から検証するのが安全です。
