For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

OpenAI ホスト型サンドボックス

実行環境の管理を OpenAI に任せて、コードの実行やダウンロード可能なファイルの作成ができます。

OpenAI ホスト型サンドボックスでは、エージェントが Python、Node.js、コマンドラインツールを備えた Linux ワークスペースを利用できます。OpenAI がワークスペースを用意して接続し、アプリケーションはタスクを渡して結果を取得します。独自のイメージ、コンピューティングリソース、プライベートネットワークのいずれかが必要な場合は、セルフホスト型サンドボックスを選択してください。

ブラウザでウェブサイトを操作するタスクについては、コンピューターの使用を参照してください。

セッションの作成前にワークスペースを準備する方法については、サンドボックスの事前準備を参照してください。

サンドボックスの設定

セッション作成リクエストで environment.type を openai_hosted に設定します。ワークロードに必要な設定だけを追加してください。サンドボックスの作業ディレクトリは /workspace です。

タスクに必要なリソースとネットワークアクセスは、それぞれ container_size と network で指定します。環境テンプレートを使用する場合、省略した設定にはテンプレートの値が適用されます。

パッケージとファイルの準備

次の設定を使って、サンドボックスで依存パッケージや入力ファイルを利用できるようにします。

  • packages:Python パッケージ、システムパッケージ、グローバルにインストールする npm パッケージを、それぞれ python、system、npm のリストで指定してインストールします。必要に応じて、pandas==2.2.3 のようにバージョンを固定してください。
  • files:Files API のファイル ID またはインラインの base64 データで入力ファイルを渡します。

セットアップコマンドの実行

setup_commands を使うと、エージェントの起動前にシェルコマンドを指定した順序で実行できます。たとえば、[{ "command": "mkdir -p reports" }] はディレクトリを作成します。各コマンドの作業ディレクトリは cwd で個別に指定できます。デフォルトは /workspace です。

パッケージと入力ファイルの準備が完了してから、セットアップコマンドが実行されます。必要な依存パッケージやファイルがそろっているかどうかは、セットアップコマンドで確認できます。セットアップの終了ステータスが 0 以外の場合、エージェントは起動しません。

環境変数の設定

env を使って、文字列を値とする環境変数を設定します。エージェントが生成したコードからこれらの値を読み取れます。

シークレットにはボールトの認証情報を使用し、実際の値はサンドボックスの外部に保管してください。PATH、CODEX_*、OPENAI_API_KEY など、ランタイムが予約している名前は指定できません。

コンテナサイズの選択

セッション作成時に environment.container_size を設定して、サンドボックスで使用できる vCPU 数とメモリ容量を選択します。デフォルトは medium です。

サイズ vCPU メモリ
small 1 1 GB
medium 2 4 GB
large 4 16 GB

たとえば、POST /v1/agents/sessions リクエストに次の環境設定を含めると、small を選択できます。

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

返されたセッションの environment.container_size で、選択したサイズを確認できます。この設定は OpenAI ホスト型サンドボックスにのみ適用されます。

ネットワークアクセスの制御

network.access 動作
enabled 外部へのアクセスを許可します。テンプレートのポリシーを継承する場合を除き、これがデフォルトです。
disabled 外部へのアクセスをブロックします。
restricted allowed_domains に指定したホストへのアクセスだけを許可します。

制限モードでは、api.example.com のような完全一致のホスト名を 1~100 件指定できます。ワイルドカード、プロトコル、パス、ポートは含めないでください。サブドメインやリダイレクト先のホストは個別に指定する必要があります。ホスト型の stdio MCP サーバーを使用するには、現時点ではネットワークアクセスを enabled に設定する必要があります。stdio MCP の要件を参照してください。

スキルとプラグインの追加

skills、plugins、capability_directories を使って、スキルやプラグインを追加します。

セッション間での設定の再利用

environment_template_id を指定すると、保存済みの設定を再利用できます。省略した設定にはテンプレートの値が適用されます。ネットワーク設定を上書きしても、テンプレートのポリシーが許可するアクセス範囲を広げることはできません。テンプレートに保存されるのは設定だけで、実行中のワークスペースは保存されません。

セットアップ結果の確認

セッション作成リクエストに対するレスポンスは、セットアップが開始されたことを示します。ステータスを確認するには、GET /v1/agents/environments/{environment_id} を呼び出します。環境 ID にはセッションの environment.id を使用してください。

ステータス 対応
provisioning セットアップが完了するまで待ちます。
connected セットアップが成功しました。実行中のサンドボックスにファイルを追加したり、ファイルの一覧を取得したりできます。
failed エラーの内容は environment.error で確認します。このフィールドは agent.session.environment.failed イベントに含まれます。

実行中のサンドボックスへのファイルの追加やファイル一覧の取得は、ステータスが connected になってから行ってください。

ファイルと保持期間

セッションごとに独立したワークスペースがあります。サンドボックスが存在する間、ファイルはターンをまたいで保持されます。/workspace/outputs 配下のファイルは、ターンが完了すると変更不可のアーティファクトとして公開されます。公開されたコピーは、サンドボックスの有効期限が切れた後もダウンロードできます。

アップロード、パスの指定規則、実行中のサンドボックスでのファイル操作、ダウンロード、各種制限については、ファイルとアーティファクトを参照してください。必要な出力はセッションを削除する前に保存してください。

サンドボックスの有効期限

接続中のサンドボックスには、ターンとターンの間もキープアライブが送信されます。アクティビティとキープアライブがともに 1 時間途絶えると、サンドボックスが削除されることがあります。このタイムアウトは変更できません。

作業が終わったら、セッションを削除してサンドボックスのクリーンアップをリクエストしてください。セットアップやタスクの実行が完了する前に削除をリクエストして 409 が返された場合は、完了を待ってから、試行回数に上限を設けて再試行してください。イベントストリームを閉じてもタスクはキャンセルされません。

料金

OpenAI ホスト型サンドボックスには、標準のコンテナ料金が適用されます。モデルの利用料金は、選択したモデルの API 料金に基づいて別途請求されます。

例:レポートの作成

10、20、30 を含む CSV ファイルをエージェントに渡します。エージェントは Python で合計を計算し、結果を /workspace/outputs/summary.json に書き込みます。

アプリケーションを実行するターミナルで OPENAI_API_KEY を設定してください。設定方法はクイックスタートの前提条件を参照してください。このキーはサンドボックスの外部に保管してください。OpenAI SDK は、ベータ版の Agents API に対応したバージョンを使用してください。

summary.json の作成
from openai import OpenAI

client = OpenAI()
stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
    },
    input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
    stream=True,
)

with stream.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

files の base64 値には、入力用の CSV データが含まれています。このコードはセッションイベントを出力します。session.id は agent.session.created イベントから取得して保存してください。agent.session.turn.completed イベントを受信したら、アーティファクトの一覧を取得し、summary.json を見つけてダウンロードします。ファイルの内容は次のようになります。

{ "total": 60 }

ターンが完了しても、すべてのツールの実行が成功したとは限りません。タスクが失敗した場合や、完了前にストリームが終了した場合は、保存済みのセッション項目を確認してください。作業が終わったら、セッションを削除してください。

トラブルシューティング

問題 確認事項
セットアップに失敗する 環境のセットアップ失敗を通知するイベントを確認し、パッケージ、入力ファイル、セットアップコマンドのエラーを修正してから、別のセッションを作成してください。
サンドボックスからのリクエストがブロックされる network の設定と、リダイレクト先のホストを確認してください。
実行中のサンドボックスでファイル操作に失敗する サンドボックスのステータスが connected であることを確認してください。有効期限が切れている場合は、新しいセッションを作成して入力ファイルを再度渡してください。
ステータスまたはファイル一覧の取得リクエストで 5xx が返される 再試行の期限を設定し、待機時間を徐々に延ばしながら再試行してください。エラーが続く場合は、リクエスト ID を控えておいてください。