サンドボックスクライアント

このページでは、サンドボックスの作業をどこで実行するかを選びます。ほとんどの場合、SandboxAgent の定義は同じままで、sandbox 実行オプション内のサンドボックスクライアントとクライアント固有のオプションだけが変わります。

ベータ機能

サンドボックスエージェントはベータ版です。API の詳細、デフォルト値、サポートされる機能は 一般提供前に変更される可能性があり、より高度な機能も 今後追加される予定です。

判断ガイド

目的	まず使うもの	理由
macOS または Linux で最速のローカル反復開発	UnixLocalSandboxClient	追加のサービス依存が不要で、シンプルなローカルファイルシステムのワークフローを使えます
基本的なコンテナ分離	DockerSandboxClient	特定のイメージを使って Docker 内で作業を実行します
ホスト型実行または本番相当の分離	ホスト型サンドボックスクライアント	ワークスペースの境界をプロバイダー管理の環境に移せます

ローカルクライアント

ほとんどのユーザーは、まず次の 2 つのサンドボックスクライアントのいずれかから始めてください。

クライアント	インストール	選ぶ場面
UnixLocalSandboxClient	なし	macOS または Linux で最速のローカル反復開発が可能です。ローカル開発の良いデフォルトです
DockerSandboxClient	ローカルで Docker CLI が利用可能	コンテナ分離や、ローカルでの同等性のために特定のイメージが必要な場合です

Unix ローカルは、ローカルファイルシステムを対象に開発を始めるもっとも簡単な方法です。より強い環境分離や本番相当の同等性が必要になったら、Docker やホスト型プロバイダーに移行してください。

Unix ローカルから Docker に切り替えるには、エージェント定義はそのままにして、クライアントだけを変更します。

Docker を使う

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { DockerSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.5',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const result = await run(agent, 'Inspect the workspace.', {
  sandbox: {
    client: new DockerSandboxClient({ image: 'node:22-bookworm-slim' }),
  },
});

console.log(result.finalOutput);

通常、同じエージェントをどちらのローカルクライアントでも実行できます。

ローカルクライアントを切り替える

import {
  DockerSandboxClient,
  UnixLocalSandboxClient,
} from '@openai/agents/sandbox/local';

const client = process.env.USE_DOCKER
  ? new DockerSandboxClient({ image: 'node:22-bookworm-slim' })
  : new UnixLocalSandboxClient();

セッション所有権

ライフサイクルには 2 つのスタイルがあります。

スタイル	渡すもの	セッションを閉じる主体	使う場面
SDK 管理	sandbox: { client }	ランナー	サンドボックスが 1 回の実行だけ生きていればよい場合
開発者管理	sandbox: { session }	あなたのコード	実行後にファイルを確認したい、同じライブセッションを再利用したい、または複数回の実行を調整したい場合

自分でセッションを作成した場合は、自分で閉じてください。

サンドボックスセッションのライフサイクルを管理する

import { run } from '@openai/agents';
import { Manifest, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.5',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const client = new UnixLocalSandboxClient();
const session = await client.create({ manifest });

try {
  await run(agent, 'First pass.', { sandbox: { session } });
  await run(agent, 'Follow-up pass.', { sandbox: { session } });
} finally {
  await session.close?.();
}

再開とスナップショット

サンドボックスの状態と会話の状態は別です。

• SDK の会話状態は result.history、SDK の Session、conversationId、または previousResponseId に保存されます
• サンドボックスの状態は、ライブサンドボックスセッション、シリアライズされた sessionState、RunState のサンドボックスペイロード、またはスナップショットに保存されます

sessionState は、サンドボックスクライアントを通じて同じバックエンドセッションに再接続したい場合に使います。スナップショットは、保存済みワークスペース内容を初期状態として新しいセッションを作りたい場合に使います。

サンドボックス状態をシリアライズして再開する

import { Manifest } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const client = new UnixLocalSandboxClient({
  snapshot: { type: 'local', baseDir: '/tmp/my-sandbox-snapshots' },
});

const session = await client.create({ manifest });
const state = await client.serializeSessionState?.(session.state);
await session.close?.();

if (state) {
  const restored = await client.resume?.(
    await client.deserializeSessionState!(state),
  );
  await restored?.close?.();
}

RunState は、より大きなワークフローを一時停止または再開するときに、ランナー管理のサンドボックス状態も保持できます。サンドボックスのライフサイクルをシリアライズされた実行の外側で管理する場合は、明示的な sessionState を使ってください。

マニフェスト実体化

マニフェストエントリーは、エージェント実行前に準備されます。実体化の並行性は、実行単位またはクライアント作成呼び出し単位で調整できます。

マニフェスト実体化の並行性を調整する

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Repository inspector',
  model: 'gpt-5.5',
  instructions: 'Inspect the repository before answering.',
});

await run(agent, 'Inspect the repo.', {
  sandbox: {
    client: new UnixLocalSandboxClient(),
    concurrencyLimits: {
      manifestEntries: 4,
      localDirFiles: 16,
    },
  },
});

manifestEntries は、トップレベルエントリー作業の並列数を制限します。localDirFiles は、localDir() エントリー内のファイルコピー並行数を制限します。

マウントとリモートストレージ

マウントエントリーは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどのように接続するかを記述します。組み込みのマウントエントリーと汎用戦略は @openai/agents/sandbox からインポートしてください。

一般的なマウントオプション:

• mountPath: ストレージがサンドボックス内のどこに現れるか。相対パスはマニフェストルート配下で解決され、絶対パスはそのまま使われます
• readOnly: サンドボックスがマウントしたストレージへ書き戻してはいけない場合に設定します
• mountStrategy: マウントエントリーとサンドボックスバックエンドの両方に一致する戦略を使います

マウントは一時的なワークスペースエントリーとして扱われます。スナップショットや永続化のフローでは、マウントされたリモートストレージを保存済みワークスペースへコピーする代わりに、マウントパスを切り離すかスキップします。

汎用のローカル / コンテナ戦略:

戦略またはパターン	使う場面	注記
inContainerMountStrategy(...)	サンドボックスイメージで rclone、mount-s3、blobfuse2 などのマウントコマンドを実行できる場合	汎用戦略として利用可能ですが、サポートはバックエンドに依存します
dockerVolumeMountStrategy(...)	コンテナ起動前に Docker がボリュームドライバー対応マウントを接続すべき場合	Docker 専用です
localBindMountStrategy()	ローカルバックエンドが絶対ローカルパスをワークスペースに bind マウントすべき場合	許可されている場合、ローカルワークスペース実体化でサポートされます

バックエンドサポートは意図的に明示的です。

バックエンド	マウントに関する注記
UnixLocalSandboxClient	ローカルワークスペースモデルを通じて、ローカル bind 形式のマウントをサポートします
DockerSandboxClient	Docker がストレージを接続できる場合、ローカル bind マウントと Docker ボリューム形式の戦略をサポートします
ホスト型プロバイダー	プロバイダー固有の戦略は各プロバイダー実装に含まれます。サポートされるマウントと必要なセットアップは、そのプロバイダーのドキュメントを確認してください

すべてのバックエンドでマウントエントリーが動作すると想定しないでください。クライアントがマニフェストメタデータ、識別情報、またはマウント動作を強制できない場合、その部分を黙って無視するのではなく早期に失敗するべきです。

サポートされるホスト型プラットフォーム

ホスト型環境が必要な場合でも、通常は同じ SandboxAgent 定義をそのまま使え、sandbox 実行オプション内のサンドボックスクライアントだけが変わります。

ホスト型プロバイダー実装は @openai/agents-extensions のプロバイダーサブパスから利用できます。正確な環境変数、実行可能なコード例、ポート動作、PTY サポート、スナップショット動作、クリーンアップ動作は、各プロバイダーのドキュメントを確認してください。

@openai/agents-extensions をインストールし、そのパッケージレベルの peer 依存関係を満たしてください。各プロバイダーでは、プロバイダー SDK パッケージやバックエンド設定が別途必要な場合もあります。

クライアント	インポートパス	プロバイダー要件
BlaxelSandboxClient	@openai/agents-extensions/sandbox/blaxel	npm peer: @blaxel/core
CloudflareSandboxClient	@openai/agents-extensions/sandbox/cloudflare	Cloudflare Sandbox bridge Worker URL と Worker 認証
DaytonaSandboxClient	@openai/agents-extensions/sandbox/daytona	npm peer: @daytonaio/sdk
E2BSandboxClient	@openai/agents-extensions/sandbox/e2b	npm peer: e2b または @e2b/code-interpreter
ModalSandboxClient	@openai/agents-extensions/sandbox/modal	npm peer: modal
RunloopSandboxClient	@openai/agents-extensions/sandbox/runloop	npm peer: @runloop/api-client
VercelSandboxClient	@openai/agents-extensions/sandbox/vercel	npm peer: @vercel/sandbox

CloudflareSandboxClient は Cloudflare の npm SDK をインポートしません。代わりに、デプロイ済みの Cloudflare Sandbox bridge Worker と HTTP 経由で通信します。

ホスト型サンドボックスクライアントは、プロバイダー固有のマウント戦略を公開します。ストレージプロバイダーに最適なバックエンドとマウント戦略を選んでください。

バックエンド	マウントに関する注記
Docker	s3Mount()、gcsMount()、r2Mount()、azureBlobMount()、boxMount()、s3FilesMount() を、inContainerMountStrategy() や dockerVolumeMountStrategy() などのローカル戦略とともにサポートします
ModalSandboxClient	S3、R2、HMAC 認証された GCS のマウントエントリーで ModalCloudBucketMountStrategy によるクラウドバケットマウントをサポートします
CloudflareSandboxClient	S3、R2、HMAC 認証された GCS のマウントエントリーで CloudflareBucketMountStrategy による Cloudflare バケットマウントをサポートします
BlaxelSandboxClient	S3、R2、GCS のマウントエントリーで BlaxelCloudBucketMountStrategy によるクラウドバケットマウントをサポートします。また、BlaxelDriveMount と BlaxelDriveMountStrategy による永続的な Blaxel Drive もサポートします
DaytonaSandboxClient	S3、GCS、R2、Azure Blob、Box のマウントエントリーで DaytonaCloudBucketMountStrategy による rclone ベースのマウントをサポートします
E2BSandboxClient	S3、GCS、R2、Azure Blob、Box のマウントエントリーで E2BCloudBucketMountStrategy による rclone ベースのマウントをサポートします
RunloopSandboxClient	S3、GCS、R2、Azure Blob、Box のマウントエントリーで RunloopCloudBucketMountStrategy による rclone ベースのマウントをサポートします
VercelSandboxClient	現時点ではホスト型固有のマウント戦略は公開されていません。代わりに、マニフェストファイル、リポジトリ、スナップショット、またはその他のワークスペース入力を使ってください

以下の表は、各バックエンドがどのリモートストレージエントリーを直接マウントできるかをまとめたものです。

バックエンド	AWS S3	Cloudflare R2	GCS	Azure Blob Storage	Box	S3 Files
Docker	はい	はい	はい	はい	はい	はい
ModalSandboxClient	はい	はい	はい	いいえ	いいえ	いいえ
CloudflareSandboxClient	はい	はい	はい	いいえ	いいえ	いいえ
BlaxelSandboxClient	はい	はい	はい	いいえ	いいえ	いいえ
DaytonaSandboxClient	はい	はい	はい	はい	はい	いいえ
E2BSandboxClient	はい	はい	はい	はい	はい	いいえ
RunloopSandboxClient	はい	はい	はい	はい	はい	いいえ
VercelSandboxClient	いいえ	いいえ	いいえ	いいえ	いいえ	いいえ

公開ポート

サンドボックスクライアントは、バックエンドが対応している場合、resolveExposedPort(port) を通じてエンドポイントを公開できます。

クライアント	動作
UnixLocalSandboxClient	設定されたポートを 127.0.0.1 に解決します
DockerSandboxClient	設定されたコンテナポートを公開し、それらのホストエンドポイントを解決します

バックエンドに許可リストの強制をさせたい場合は、クライアントオプションでポートを宣言してください。

ポートを公開する

import { DockerSandboxClient } from '@openai/agents/sandbox/local';

const client = new DockerSandboxClient({
  image: 'node:22-bookworm-slim',
  exposedPorts: [3000],
});

機能サポートマトリクス

機能	Unix ローカル	Docker
exec_command	サポート	サポート
PTY write_stdin	サポート	サポート
apply_patch	サポート	ワークスペースファイル API 経由でサポート
view_image	サポート	ワークスペースファイル API 経由でサポート
コマンドの runAs	ホストがユーザーを解決して切り替えられる場合にサポート	コンテナ / ユーザー設定により制限されます
ローカルスナップショット	サポート	サポート
ローカル / Docker マウント	ローカル bind 形式をサポート	bind と Docker ボリューム形式をサポート

ローカル PTY サポートでは、SDK プロセス内で小さな Python 3 bridge を使います。この bridge は tty: true のセッションでのみ使われます。これは、Node.js が組み込みの PTY API を提供しておらず、SDK が対話的な stdin、シグナル処理、終了ステータス報告のために標準的な POSIX PTY 動作を必要とするためです。SDK コードを実行する環境に python3 をインストールするか、OPENAI_AGENTS_PYTHON に Python 3 実行ファイルを設定してください。これは、Docker サンドボックスイメージ内にインストールされている Python のバージョンとは別です。

ホスト型プロバイダーのサポートはプロバイダーごとに異なります。正確なオプション、環境変数、ポート動作、PTY サポート、スナップショット動作、クリーンアップ動作は、プロバイダー固有のドキュメントを確認してください。