マネージドエージェントのセッション、実行環境、使用量、データ管理の基本をご案内します。

概要

Agents API はベータ版として利用できます。開発者は、OpenAI が管理する Codex エージェントを使ったアプリケーションを構築できます。このエージェントは複数のステップにわたって作業し、同じセッション内で作業を継続できます。

タスク、ツール、設定は、お使いのアプリケーションから提供します。OpenAI は、エージェントのセッションと、モデルとツール間の連携を管理します。

エージェントでできること

ツールや実行環境に応じて、エージェントはコードの実行、ファイルの編集、MCP 接続の利用、アプリケーション用のファイル作成を行えます。同じセッション内で追加の指示を送ったり、続けて別のタスクに取り組んだりできます。

対応する機能や使用例については、Agents API の概要をご覧ください。

OpenAI Platform のプロジェクトで、アプリケーション用の API キーを作成します。セッション用に api.agents.read と api.agents.write、モデルへのリクエスト用に api.responses.write の権限を付与します。
クイックスタートに従ってエージェントを設定し、セッションを作成してタスクを送信します。
セッションのイベントを追跡して、進捗と結果を確認します。作業を継続する場合は、セッション ID を保存してください。

API キーは、エージェントのサンドボックス外で保管してください。リクエストには OpenAI-Beta: agents=v1 ヘッダーが必要です。OpenAI SDK はこのヘッダーを自動的に追加します。

タスクに適した環境を選択してください。

環境なし：組み込みのシェルコマンドやワークスペース内のファイルを必要とせず、エージェントが質問に回答したり、外部ツールを使用したりする場合に選びます。
OpenAI ホスト型サンドボックス：エージェントがスクリプトを実行したりファイルを操作したりする必要があり、サンドボックスの管理を OpenAI に任せたい場合に選びます。
セルフホスト型サンドボックス：独自のインフラ、ソフトウェア、プライベートネットワークが必要な場合に選びます。環境のライフサイクルは、お使いのアプリケーションで管理します。

設定の詳細については、Agents API のアーキテクチャをご覧ください。

Platform ダッシュボードのログを開き、Agents を選択して、セッション ID を検索します。ターン、ツール呼び出し、サブエージェントの動作を確認できます。

記録されたトークン使用量の確認方法は、可観測性ガイドでも説明しています。

再試行する前に、既存のセッションと保存済みの項目を取得してください。これにより、追加の作業を送信する前に、それまでの処理状況を確認できます。

ターンが完了していても、すべてのツールが成功したとは限りません。報告された結果を確認してください。セッションがアイドル状態であるだけでは、タスクが正常に完了したとは判断できません。

モデルへのリクエストには、選択したモデルの API 料金が適用されます。OpenAI のツールと OpenAI がホストするサンドボックスには、それぞれ該当するツール料金とコンテナ料金が適用されます。

最新の料金は、API 料金をご覧ください。

Agents API はセッションの状態を保持するため、複数のターンにわたって作業を継続できます。不要になったセッションや公開済みの成果物は削除できます。セッションを削除する前に、必要なファイルを保存してください。

Agents API は現在、米国内のデータレジデンシーのみに対応しています。セルフホスト型サンドボックスを使用する場合も含め、ゼロデータ保持には対応していません。データ管理の詳細については、Agents API ドキュメントをご覧ください。