> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes で OpenAI Agents API を実行する

> OpenAI のマネージドエージェントを CoreWeave のサンドボックスに接続し、ツール実行と共有ワークスペースでの分析を行います。

OpenAI のマネージドエージェントの実行環境として、CoreWeave Sandboxes を使用できます。
アプリケーションは Agents API のセッションと CoreWeave のサンドボックスを作成します。サンドボックス内の Codex
エグゼキューターが OpenAI に接続し、エージェントのコマンドを実行します。
このページでは、実行モデル、各コンポーネントに必要な認証情報、
およびユーザーが管理するリソースの有効期間について説明します。これらを理解しておけば、
付属のレシピを実行し、同じパターンを独自のアプリケーションに応用できます。

付属のレシピでは、推論サービスで発生した架空のインシデントを
調査します。3 つの専門サブエージェントがそれぞれレイテンシー、エラー、キャパシティを分析し、
コーディネーターがその結果をまとめてインシデントレポートを作成したうえで、追加の質問に回答します。
アプリケーションが結果をダウンロードした後、別途ローカルで動作する検証ツールが
計算結果と記録されたエージェントのアクティビティを検証します。

<h2 id="execution-model">
  実行モデル
</h2>

OpenAI はエージェントループを実行し、会話コンテキストを管理し、委譲ツールを提供します。
CoreWeave はエグゼキューターと、エージェントが作成するプログラムを実行します。
サンドボックスのプロビジョニング、ファイル転送、クリーンアップは、お使いのアプリケーション側で管理します。

コーディネーターとそのサブエージェントは、1 つのサンドボックスと 1 つのファイルシステムを共有します。
サブエージェントを作成しても、CoreWeave サンドボックスが別途作成されることはありません。
各スペシャリストにはそれぞれ専用の出力ファイルを割り当て、最終レポートはコーディネーターが担当するようにしてください。
こうしたファイルの割り当ては、書き込みの競合を避けるための慣例であり、アクセス制御ではありません。
詳しくは、OpenAI の [マルチエージェントガイド](https://developers.openai.com/api/docs/guides/agents-api/multi-agent) を参照してください。

<h2 id="requirements">
  要件
</h2>

この例を実行する前に、次の要件を満たしてください。

* [Forge APIキー](https://forge.coreweave.com/settings#apikeys)、または `SANDBOX_USER` action を持つ CoreWeave API アクセストークン、
  および CPU サンドボックス 1 つ分のキャパシティ。
  [認証情報を選択する](/ja/products/sandboxes/placement#choose-and-get-credentials)の手順に従ってください。
* Agents API へのアクセス権と、選択したモデルへのアクセス権を持つ OpenAI の project。
* Python と `uv`。バージョンとロックファイルは、付属のレシピで指定されているものを使用してください。
* `api.openai.com` へのアウトバウンド HTTPS 通信と、
  `codex-cloud-environments.chatgpt.com` へのセキュアな WebSocket アクセス。イメージのセットアップでは、エグゼキューターとランタイムの依存関係をインストールするためのパッケージ
  レジストリへのアクセスも必要です。

この例では、CPU コンピュートを使用して、提供されたテレメトリを分析します。推論サーバーの起動や
GPU のリクエストは行いません。OpenAI モデルの使用料と CoreWeave サンドボックスの
コンピュート料金には、それぞれ別の請求条件が適用されます。

<h2 id="keep-application-and-executor-credentials-separate">
  アプリケーションとエグゼキューターの認証情報を分離する
</h2>

この例では、サンドボックス用の認証情報 1 つと OpenAI キー 2 つの、合計 3 つの認証情報を使用します。
各認証情報は 1 つのコンポーネントだけが使用するため、アプリケーションのアクセス権が
サンドボックスに渡ることはありません。

| 認証情報 | 使用元 | 用途 |
| - | - | - |
| `WANDB_API_KEY` | アプリケーション | Forge 認証 (`--sandbox-auth wandb`) でサンドボックスをプロビジョニングおよび操作する |
| `CWSANDBOX_API_KEY` | アプリケーション | CoreWeave 認証 (デフォルト) でサンドボックスをプロビジョニングおよび操作する |
| `OPENAI_API_KEY` | アプリケーション | セッションの作成、入力の送信、結果の確認を行う |
| `OPENAI_EXECUTOR_API_KEY` | サンドボックスのエグゼキューター (`CODEX_API_KEY` として) | この実行環境を OpenAI に接続する |

このレシピのデフォルトは CoreWeave 認証です。Forge の APIキーを使用するには、
`--sandbox-auth wandb` を渡します。このレシピでは、Forge 認証に `WANDB_API_KEY` という環境変数名を厳密に使用する必要があり、`FORGE_API_KEY` は読み取りません。必須となるのは選択したサンドボックス用の認証情報のみですが、
どちらのモードでも OpenAI キーは 2 つとも必要です。アプリケーションは選択された
モードを記録するため、クリーンアップ時にも同じプロバイダーの認証情報が使用されます。

OpenAI のアプリケーションキーには、`api.agents.read`、`api.agents.write`、
`api.responses.write` が必要です。これとは別に、環境キーを
[**Agents > Environments > Keys**](https://platform.openai.com/agents?tab=environments\&environment_view=keys) で作成してください。
このキーの組織、project、およびユーザーまたはサービスアカウントの所有者は、セッションと同じである必要があります。
無関係な権限は **None** に設定してください。

このレシピでは、制限付きのエグゼキューターキーを SDK の `environment_variables`
引数で渡します。シークレットストアは設定しません。

アップロードするのはタスクの入力だけにしてください。アプリケーションの認証情報、ローカルの設定、
および検証ツールはサンドボックスの外に置きます。詳しくは
[OpenAI の認証手順](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted#authentication)を参照してください。

<Warning>
  エージェントが生成したコードはエグゼキューターキーを読み取れます。そのコードが OpenAI を通じて
  アクセスできる範囲を限定するため、キーの権限は必要最小限に絞ってください。
</Warning>

<h2 id="connect-an-agent-session">
  エージェントセッションを接続する
</h2>

実行可能なレシピでは、OpenAI と CoreWeave の SDK を使用して次のステップを実装しています。

1. セルフホストの Agents API セッションを作成し、そのセッション ID と環境
   ID を保存します。エグゼキューターを起動する際は、返された `remote_url` をそのまま使用します。
2. 最大ライフタイムを明示的に指定し、Python
   と Node の両方を含む CoreWeave サンドボックスを作成します。
3. 返された環境 ID と、変更を加えていないリモート URL を指定して `codex exec-server` を起動します。制限付きのエグゼキューターキーのみを `CODEX_API_KEY` として注入します。
4. 合成された入力とタスクの指示をアップロードし、環境との
   接続を確認します。タスクを送信し、その結果を確認します。
5. クリーンアップの前に、生成されたアーティファクトと API アクティビティレコードを取得します。

この一連の手順が完了すると、エージェントの出力ファイルとセッションのアクティビティ
レコードをローカルで確認できます。

次の設定の抜粋では、セッション作成時に組み込みの委譲を有効にしています。
レシピでは、これらの辞書を `client.beta.agents.sessions.create()` に渡します。

```python theme={"system"}
agent = {
    "model": "gpt-6-astra",
    "instructions": "Follow TASK.md. Delegate the three independent analyses, then synthesize their findings.",
    "multi_agent": {"enabled": True, "max_concurrent_subagents": 3},
}
environment = {
    "type": "self_hosted",
    "workspace_directory": "/workspace/project",
}
```

この設定では、コーディネーターを除き、最大 3 つのサブエージェントを同時に実行できます。指示では委譲を求めていますが、設定だけでは、モデルが実際に委譲を使用したことの証明にはなりません。

このレシピでは、API 経由で完了したスクリプトのコマンドを、ターン ID とサブエージェント ID に基づいて紐付けます。
明示的に 0 以外の終了コードを返したコマンドは、実行成功の証拠としてカウントされません。終了コードが省略されている場合、検証ツールはそれを unknown として報告します。
省略可能な `--require-exit-codes` チェックを使用すると、すべてのスペシャリストについて、数値の終了コード 0 による証拠が必須になります。`started_at` と `completed_at` の区間が重なっている場合は、サブエージェントのターンが同時に実行されたことを示します。ただし、これらのタイムスタンプの精度は秒単位であるため、
シェルプロセスが同時に実行されたことや、逐次実行より高速化されたことの証明にはなりません。

<h2 id="run-the-example">
  例を実行する
</h2>

[レシピのセットアップと実行の手順](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/openai-agents-api)に従ってください。
このレシピには、独自の合成データ、タスク仕様、
アプリケーション、および独立した検証ツールが含まれています。
ダウンロードしたレポートは、検証ツールの検出結果と照らし合わせて確認してください。

セッションが存在している間は、
[**OpenAI Logs > Agents**](https://platform.openai.com/logs?api=agents) でもセッションのターンとツール呼び出しを確認できます。
該当する組織と project を選択してください。この例では
チャット UI は提供しておらず、ChatGPT アプリや Codex アプリとのセッションの継続にも対応していません。

既存のコマンドラインインターフェース (CLI) ワークフローについては、
[OpenAI Agents API in cws-agent](https://github.com/coreweave/cws-agent/blob/main/docs/openai-agents.md) を参照してください。
このレシピは SDK を直接使用するため、この CLI は不要です。

<h2 id="session-sandbox-and-file-lifetimes">
  Session、サンドボックス、ファイルの有効期間
</h2>

何を保持するかを決める際は、会話、コンピュート、ワークスペースファイルをそれぞれ個別に管理してください。

| リソース | 保持する方法 | 終了する要因 |
| - | - | - |
| API の会話 | 同じ OpenAI セッション ID を再利用する | API セッションの明示的な削除 (プロバイダーのデータ保持ポリシーに準拠) |
| 実行中のサンドボックス | CoreWeave のコンピュートを稼働させ続ける | 明示的な停止、最大ライフタイムへの到達、またはインフラストラクチャーの障害 |
| ワークスペースファイル | サンドボックスを維持する、またはファイルやスナップショットを保存する | コピーを保存しないままコンピュートが失われる |

コンピュートの有効期間は明示的に選択してください。このレシピでは最大ライフタイムを 20 分に設定しています。最大ライフタイムは上限であり、プロンプトのたびにリセットされる非アクティブタイマーではありません。

エグゼキューターを実行中の同じサンドボックスに再接続した場合、そのワークスペースは保持されます。一方、同じ環境 ID で代わりのコンピュートを起動しても、ファイルはリストアされません。
コンピュートを停止する前に、アーティファクトをダウンロードするか、CoreWeave の永続化機能を使用してください。
このレシピはアーティファクトをダウンロードしてからリソースを削除します。自動復旧やスナップショットからのリストアは実装していません。

サンドボックスを停止しても、API の会話は削除されません。また、会話を削除してもサンドボックスは停止しません。両方のクリーンアップ操作を実行し、失敗した場合はそれぞれ報告してください。

<h2 id="handle-failures">
  障害に対処する
</h2>

障害を調査する際は、次のガイダンスを参考にしてください。

* **エグゼキューター が接続しない:** 環境キーの所有者、アウトバウンドのネットワーク
  アクセス、エグゼキューター の互換性、および OpenAI から返されたリモート URL が正確かどうかを確認します。
* **OpenAI が使用量または請求の上限を報告する:** 再試行する前に、OpenAI の組織と
  project の請求制限を確認します。エグゼキューター が接続できても、それだけでモデルのターンを
  実行できるとは限りません。
* **ストリームが切断される、またはクライアントがタイムアウトする:** 入力を再試行する前に、セッションの状態と保存済みの
  イベントを確認します。タイムアウトが発生しても、クラウド上の処理自体はキャンセルされません。
* **委譲や処理の並行実行が確認できない:** 保存済みのアクティビティの記録を確認します。
  report の内容が正しいというだけでは、マルチエージェントの run が並列実行された証拠としては不十分です。
* **OpenAI の環境が期限切れになる:** 再試行する前に環境の状態を確認します。レシピは
  即座に失敗せず、処理の期限まで待機する場合があります。
* **サンドボックスが期限切れになる:** 可能であれば、保存済みのアーティファクトを復元します。代替の
  サンドボックスを使用するには、ファイル復元ポリシーを明示的に指定する必要があります。
* **アプリケーションが中断される:** レシピで保存されたリソースジャーナルと
  クリーンアップコマンドを使用します。サンドボックスの最大有効期間はあくまでフォールバックであり、
  API セッションを削除する代わりにはなりません。

セッションを保持するアプリケーションでは、受信する処理と調整しながらシャットダウンしてください。
アイドルイベントが発生したというだけでは、安全にシャットダウンできるとは判断できません。webhook 駆動のプロビジョニングは
別のデプロイメントパターンです。詳しくは、OpenAI の
[サンドボックスのライフサイクルガイド](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle)を参照してください。