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

OpenAI がホストするサンドボックス

コンピューティングリソースを管理せずに、コードを実行してダウンロード可能なファイルを作成できます。

OpenAI がホストするサンドボックスは、Python、Node.js、 コマンドラインツールを備えた Linux ワークスペースをエージェントに提供します。OpenAI がサンドボックスのプロビジョニングと接続を行い、アプリケーションが タスクの指定と結果の取得を行います。独自のイメージ、コンピューティングリソース、プライベートネットワークが必要な場合は、 セルフホスト型サンドボックスを選択してください。

サンドボックスの構成

environment.typeopenai_hosted に設定し、ワークロードに必要な設定だけを 追加します。作業ディレクトリは /workspace です。

  • packagespythonsystemnpm のリストを使って、Python パッケージ、システムパッケージ、グローバルの npm パッケージをインストールします。必要に応じて、pandas==2.2.3 のようにバージョンを固定してください。
  • setup_commands[{ "command": "mkdir -p reports" }] のように、エージェントの起動前にシェルコマンドを順番に実行します。各コマンドには任意で cwd を指定でき、デフォルトは /workspace です。
  • files:Files API の ID またはインラインの base64 コンテンツで入力ファイルを指定します
  • env:文字列値の環境変数を設定します。PATHCODEX_*OPENAI_API_KEY など、ランタイムで予約されている名前は拒否されます。
  • skillspluginscapability_directoriesスキルプラグインを追加します。
  • environment_template_id:複数のセッションで保存済みの構成を再利用します。省略した設定はテンプレートから継承されます。ネットワーク設定を上書きしても、テンプレートのポリシーで許可された範囲を広げることはできません。

パッケージと入力ファイルは、セットアップコマンドの実行前に準備されます。セットアップの終了ステータスがゼロ以外の場合、エージェントは起動しません。セットアップコマンドで、必要な依存関係やファイルを確認してください。テンプレートに保存されるのは構成であり、稼働中のワークスペースではありません。

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

network.access動作
enabled外部へのアクセスを許可します。テンプレートのポリシーを継承していない場合、これがデフォルトです。
disabled外部へのアクセスをブロックします。
restrictedallowed_domains に記載されたホストへのアクセスのみを許可します。

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

セットアップの成功確認

セッション作成のレスポンスは、セットアップが開始されたことを意味します。 セッションの environment.id を使って GET /v1/agents/environments/{environment_id} で情報を取得してください。 provisioning はセットアップの実行中、connected はセットアップの成功を意味します。 failed の場合は、agent.session.environment.failed イベントの environment.error を確認してください。 ライブファイルの追加や一覧取得は、connected になるまで待ってから行ってください。

ファイルと存続期間

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

アップロード、パスのルール、ライブファイル操作、ダウンロード、制限については、 ファイルとアーティファクトを参照してください。 セッションを削除する前に、必要な出力を保存してください。

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

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

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

料金

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

例:レポートの作成

102030 を含む 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:
    for event in stream:
        print(event.model_dump_json())

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

{ "total": 60 }

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

トラブルシューティング

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