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

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

ベータ機能

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

判断ガイド

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

ローカルクライアント

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

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

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

Unix-local から 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()	ローカルバックエンドが絶対ローカルパスをワークスペースへバインドする必要がある場合。	許可されているローカルワークスペースの実体化でサポートされます。

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

バックエンド	マウントの備考
UnixLocalSandboxClient	ローカルワークスペースモデルを通じて、ローカルバインド形式のマウントをサポートします。
DockerSandboxClient	Docker がストレージを接続できる場合、ローカルバインドマウントと 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 ブリッジ 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 ブリッジ Worker と HTTP 経由で通信します。

VercelSandboxClient は各 PAT 認証情報フィールドを、作成ごとのオプション、コンストラクターオプション、続いて VERCEL_PROJECT_ID、VERCEL_TEAM_ID、VERCEL_TOKEN の優先順位で解決します。結果として得られる projectId、teamId、token がすべて空でない場合にのみ、認証情報を転送します。それ以外の場合は 3 つのフィールドすべてを省略し、プラットフォーム OIDC やローカルプロバイダー認証情報を含め、@vercel/sandbox に認証の解決を任せます。完全に解決された認証情報は、セッションをシリアライズして再開するときにも保持されます。シリアライズされた認証情報は完全な 3 つ組として扱われ、現在のオプションや環境変数とは混在されません。不完全なシリアライズ済み認証情報は、現在の設定をフォールバックとして解決する前に破棄されます。トークンはシリアライズされたセッション状態に残るため、その状態は安全に保存してください。

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

バックエンド	マウントの備考
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 Drives もサポートします。
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-local	Docker
exec_command	サポート	サポート
PTY write_stdin	サポート	サポート
apply_patch	サポート	ワークスペースファイル API 経由でサポート
view_image	サポート	ワークスペースファイル API 経由でサポート
コマンド用の runAs	ホストがユーザーを解決して切り替えられる場合にサポート	コンテナ/ユーザー設定により制限
ローカルスナップショット	サポート	サポート
ローカル/Docker マウント	ローカルバインド形式をサポート	バインドおよび Docker ボリューム形式をサポート

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

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