コンセプト

現代のエージェントは、ファイルシステム内の実際のファイルを扱えるときに最も効果を発揮します。 Sandbox Agents は、特殊なツールやシェルコマンドを使って、大規模なドキュメント集合の検索と操作、ファイル編集、成果物の生成、コマンド実行を行えます。サンドボックスは、エージェントがユーザーに代わって作業できる永続的なワークスペースをモデルに提供します。 Agents SDK の Sandbox Agents は、サンドボックス環境と組み合わせたエージェントの実行を支援し、適切なファイルをファイルシステム上に簡単に配置しつつ、サンドボックスをオーケストレーションして大規模にタスクを開始、停止、再開しやすくします。

ワークスペースは、エージェントが必要とするデータを中心に定義します。開始元として、 GitHub リポジトリ、ローカルのファイルやディレクトリ、合成タスクファイル、 S3 や Azure Blob Storage のようなリモートファイルシステム、その他ユーザーが提供するサンドボックス入力を使えます。

SandboxAgent は Agent を拡張しているため、依然として Agent です。 instructions、tools、handoffs、mcpServers、modelSettings、出力型、ガードレール、フックといった通常のエージェントの表面を保ちつつ、通常の run() および Runner API を通じて実行されます。変わるのは実行境界です。

SandboxAgent はエージェント自体を定義します。通常のエージェント設定に加え、 defaultManifest、baseInstructions、runAs などのサンドボックス固有のデフォルトや、ファイルシステムツール、シェルアクセス、スキル、メモリ、 compaction などの機能を含みます
Manifest は、新しいサンドボックスワークスペースの望ましい初期内容とレイアウトを宣言します。ファイル、リポジトリ、マウント、環境が含まれます
サンドボックスセッションは、コマンドが実行され、ファイルが変更される実行中のライブ実行環境です
sandbox 実行オプションは、その実行がどのようにサンドボックスセッションを取得するかを決定します。たとえば直接注入する、シリアライズされたサンドボックスセッション状態から再接続する、あるいはサンドボックスクライアント経由で新しいサンドボックスセッションを作成する、といった方法です
保存済みのサンドボックス状態やスナップショットを使うと、後続の実行で以前の作業に再接続したり、保存済みの内容から新しいサンドボックスセッションを初期化したりできます

Manifest は、新しいサンドボックスワークスペースの初期内容を定義します。すべてのライブサンドボックスにおける現在のファイルを記述するものではありません。再利用されたセッション、シリアライズされたセッション状態、スナップショットはいずれも、実行時にワークスペースを提供または変更できるためです。

このページでは、「サンドボックスセッション」はサンドボックスクライアントが管理するライブ実行環境を意味します。正確な境界はクライアントによって異なります。 Unix ローカルセッションはホスト上のローカルワークスペースで実行され、 Docker やホスト型クライアントはより強い環境分離を提供します。これはセッションで説明されている SDK の会話型 Session インターフェースとは異なります。

外側のランタイムは、承認、トレーシング、ハンドオフ、再開のための記録管理を引き続き所有します。サンドボックスセッションは、コマンド、ファイル変更、環境分離を所有します。この分割はモデルの中核です。

構成要素の関係

サンドボックス実行では、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。 runner はエージェントを準備し、ライブのサンドボックスセッションに結び付け、後続の実行のために状態を保存できます。

SandboxAgentエージェントとサンドボックスのデフォルト

Runnerinstructions を準備し、機能ツールをバインド

Sandbox sessionコマンドが実行され、ファイルが変更されるワークスペース

Saved state後で再開したり、新しいワークスペースの初期化に使ったりできます

サンドボックス固有のデフォルトは SandboxAgent に保持されます。実行ごとのサンドボックスセッション選択は sandbox 実行オプションに保持されます。

ライフサイクルは 3 つのフェーズで考えるとよいです。

SandboxAgent、Manifest、機能を使って、エージェントと初期ワークスペース内容を定義する
run() または Runner に sandbox 実行オプションを渡して、サンドボックスセッションを注入、再開、または作成して実行する
runner 管理の RunState、明示的なサンドボックス sessionState、または保存済みワークスペーススナップショットから後で続行する

シェルアクセスがときどき使うツールの 1 つにすぎない場合は、ツールガイドの hosted shell から始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合は、 sandbox agents を使ってください。

利用場面

sandbox agents は、たとえば次のようなワークスペース中心のワークフローに適しています。

コーディングとデバッグ: GitHub リポジトリの issue レポートに対する自動修正をオーケストレーションし、対象を絞ったテストを実行する
ドキュメント処理と編集: ユーザーの財務書類から情報を抽出し、記入済みの納税フォーム草案を作成する
ファイルに基づくレビューや分析: オンボーディング資料、生成されたレポート、成果物バンドルを確認してから回答する
分離されたマルチエージェントパターン: 各レビュアーやコーディング用サブエージェントに独自のワークスペースを与える
複数段階のワークスペースタスク: 1 回の実行でバグを修正し、後で回帰テストを追加する、あるいはスナップショットやサンドボックスセッション状態から再開する

ファイルや生きたファイルシステムへのアクセスが不要であれば、引き続き Agent を使ってください。シェルアクセスがたまに必要な機能にすぎないなら hosted shell を追加し、ワークスペース境界そのものが機能の一部なら sandbox agents を使います。

サンドボックスクライアントの選択

ローカル開発では UnixLocalSandboxClient から始めてください。コンテナ分離やイメージの同一性が必要なら DockerSandboxClient に移行します。プロバイダー管理の実行が必要ならホスト型プロバイダーに移行します。

多くの場合、 SandboxAgent の定義はそのままで、変更するのは sandbox 実行オプション内のサンドボックスクライアントとそのオプションだけです。ローカル、 Docker 、ホスト型、リモートマウントの各オプションについてはサンドボックスクライアントを参照してください。

コア要素

レイヤー	主な SDK 要素	答える問い
エージェント定義	`SandboxAgent`、`Manifest`、機能	どのエージェントが実行され、新しいセッションのワークスペース契約は何から始まるべきか
サンドボックス実行	`sandbox` 実行オプション、サンドボックスクライアント、ライブのサンドボックスセッション	この実行はどのようにライブのサンドボックスセッションを取得し、作業はどこで実行されるか
保存済みサンドボックス状態	`RunState` のサンドボックスペイロード、`sessionState`、スナップショット	このワークフローは以前のサンドボックス作業にどう再接続するか、または保存済み内容から新しいサンドボックスセッションをどう初期化するか

主な SDK 要素は、これらのレイヤーに次のように対応します。

要素	所有するもの	問うべきこと
`SandboxAgent`	エージェント定義	このエージェントは何をすべきか、どのデフォルトを一緒に持ち運ぶべきか
`Manifest`	新しいセッションのワークスペース内のファイルとフォルダー	実行開始時にファイルシステム上に存在すべきファイルやフォルダーは何か
`Capability`	サンドボックスネイティブな振る舞い	どのツール、 instruction 断片、または実行時動作をこのエージェントに追加すべきか
`sandbox` 実行オプション	実行ごとのサンドボックスクライアントとサンドボックスセッションの取得元	この実行ではサンドボックスセッションを注入、再開、作成のどれにすべきか
`RunState`	runner 管理の保存済みサンドボックス状態	以前の runner 管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継いでいるか
`sandbox.sessionState`	明示的にシリアライズされたサンドボックスセッション状態	`RunState` の外で既にシリアライズしたサンドボックス状態から再開したいか
`sandbox.snapshot`	新しいサンドボックスセッション用の保存済みワークスペース内容	保存済みのファイルや成果物から新しいサンドボックスセッションを始めるべきか

実践的な設計順序は次のとおりです。

Manifest で新しいセッションのワークスペース契約を定義する
SandboxAgent でエージェントを定義する
組み込みまたはカスタムの機能を追加する
run(agent, input, { sandbox: ... }) または new Runner({ sandbox: ... }) で、各実行がどのようにサンドボックスセッションを取得するかを決める

サンドボックス実行の準備方法

実行時に、 runner はその定義を具体的なサンドボックス対応実行に変換します。

sandbox 実行オプションからサンドボックスセッションを解決します
実行に対する有効なワークスペース入力を決定します
機能に、結果として得られた manifest を処理させます
固定順序で最終的な instructions を構築します。 SDK のデフォルトサンドボックスプロンプト、または明示的に上書きした場合は baseInstructions、次に instructions、次に機能の instruction 断片、次にリモートマウントポリシーのテキスト、最後にレンダリングされたファイルシステムツリーです
機能ツールをライブのサンドボックスセッションにバインドし、通常の run() および Runner API を通して準備済みエージェントを実行します

サンドボックス化は 1 ターンの意味を変えません。ターンは依然としてモデルのステップであり、単一のシェルコマンドやサンドボックス操作ではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。実務上の目安としては、サンドボックス作業の後にエージェントランタイムがさらにモデル応答を必要とする場合にのみ、次のターンが消費されます。

`SandboxAgent` のオプション

通常の Agent フィールドに加わる、サンドボックス固有のオプションは次のとおりです。

オプション	最適な用途
`defaultManifest`	runner が作成する新しいサンドボックスセッション向けのデフォルトワークスペース
`instructions`	SDK のサンドボックスプロンプトの後に追加される、役割、ワークフロー、成功条件
`baseInstructions`	SDK のサンドボックスプロンプトを置き換えるための高度な escape hatch
`capabilities`	このエージェントと一緒に持ち運ばれるべきサンドボックスネイティブなツールと動作
`runAs`	シェルコマンド、ファイル読み取り、パッチなど、モデル向けサンドボックスツールにおけるユーザー ID

サンドボックスクライアントの選択、サンドボックスセッションの再利用、 manifest の上書き、スナップショットの選択は、エージェントではなく sandbox 実行オプションに属します。

`defaultManifest`

defaultManifest は、 runner がこのエージェント用に新しいサンドボックスセッションを作成する際に使うデフォルトの Manifest です。エージェントが通常最初に持っているべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使います。

これはあくまでデフォルトです。実行時に sandbox.manifest で上書きできますし、再利用または再開されたサンドボックスセッションは既存のワークスペース状態を保持します。

import { file, gitRepo, Manifest } from '@openai/agents/sandbox';

const manifest = new Manifest({
  root: '/workspace',
  entries: {
    'task.md': file({
      content: 'Fix the failing test and summarize the change.',
    }),
    repo: gitRepo({
      repo: 'openai/openai-agents-js',
      ref: 'main',
    }),
  },
  environment: {
    NODE_ENV: 'test',
  },
});

`instructions` と `baseInstructions`

instructions は、異なるプロンプトでも維持したい短いルールに使います。 SandboxAgent では、これらの instructions は SDK のサンドボックス基本プロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを維持しつつ、独自の役割、ワークフロー、成功条件を追加できます。

baseInstructions は、 SDK のサンドボックス基本プロンプトを置き換えたい場合にのみ使ってください。ほとんどのエージェントでは設定不要です。

置く場所	用途	例
`instructions`	エージェントに対する安定した役割、ワークフロールール、成功条件	「オンボーディング資料を確認してからハンドオフする」「最終ファイルを `output/` に書き込む」
`baseInstructions`	SDK のサンドボックス基本プロンプトの完全な置き換え	低レベルのカスタムサンドボックスラッパープロンプト
ユーザープロンプト	この実行だけの単発リクエスト	「このワークスペースを要約してください」
manifest 内のワークスペースファイル	より長いタスク仕様、リポジトリローカル instructions、または限定された参照資料	`repo/task.md`、ドキュメントバンドル、サンプル資料

ユーザーの単発タスクを instructions にコピーしたり、 manifest に置くべき長い参照資料を埋め込んだり、組み込み機能が既に注入しているツールドキュメントを言い換えたり、実行時にモデルが不要なローカルインストールメモを混ぜたりするのは避けてください。

`capabilities`

機能は、サンドボックスネイティブな振る舞いを SandboxAgent に追加します。実行開始前にワークスペースを整えたり、サンドボックス固有の instructions を追加したり、ライブのサンドボックスセッションにバインドされるツールを公開したり、そのエージェントのモデル動作や入力処理を調整したりできます。

組み込み機能には次のものがあります。

Capability	追加する場面	補足
`shell()`	エージェントにシェルアクセスが必要なとき	`exec_command` を追加し、サンドボックスクライアントが PTY 対話をサポートする場合は `write_stdin` も追加します
`filesystem()`	エージェントがファイルを編集したり、ローカル画像を確認したりする必要があるとき	`apply_patch` と `view_image` を追加します。パスはワークスペースルート相対です
`skills()`	サンドボックス内でのスキル探索と materialization が必要なとき	サンドボックスローカルな `SKILL.md` スキルについては、 `.agents` や `.agents/skills` を手動でマウントするよりこちらを推奨します
`memory()`	後続の実行でメモリアーティファクトを読み取ったり生成したりしたいとき	`shell()` が必要です。ライブ更新には `filesystem()` も必要です
`compaction()`	長時間のフローで compaction 項目の後にコンテキスト圧縮が必要なとき	モデルのサンプリングと入力処理を調整します

デフォルトでは、 SandboxAgent.capabilities は Capabilities.default() を使い、これには filesystem()、shell()、compaction() が含まれます。 capabilities: [...] を渡すと、そのリストがデフォルトを置き換えるため、必要なデフォルト機能は明示的に含めてください。

コンセプト

Manifest

Manifest は、新しいサンドボックスセッションのワークスペースを記述します。ワークスペースの root を設定し、ファイルやディレクトリを宣言し、ローカルファイルをコピーし、 Git リポジトリをクローンし、リモートストレージマウントを接続し、環境変数を設定し、ユーザーやグループを定義し、ワークスペース外の特定の絶対パスへのアクセスを許可できます。

Manifest の環境値は、デフォルトで永続化されます。 API キー、アクセストークン、その他サンドボックス状態と一緒に保存すべきでない短命な認証情報には、{ value: "...", ephemeral: true } のような一時的エントリを使ってください。

Manifest エントリのパスはワークスペース相対です。絶対パスにはできず、.. を使ってワークスペース外に出ることもできません。これにより、ワークスペース契約はローカル、 Docker 、ホスト型クライアント間で移植可能に保たれます。

manifest エントリは、作業開始前にエージェントが必要とする素材に使います。

Manifest エントリ	用途
`file()`, `dir()`	小さな合成入力、補助ファイル、出力ディレクトリ
`localFile()`, `localDir()`	サンドボックス内に materialize すべきホストファイルまたはディレクトリ
`gitRepo()`	ワークスペースに取得すべきリポジトリ
`s3Mount()`, `gcsMount()`, `r2Mount()`, `azureBlobMount()`, `s3FilesMount()` などのマウント	サンドボックス内に現れるべき外部ストレージ

マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどう接続するかを記述します。マウントオプションとプロバイダー対応については、サンドボックスクライアントを参照してください。

権限

Permissions は、 manifest エントリに対するファイルシステム権限を制御します。これはサンドボックスが materialize するファイルに関するものであり、モデル権限、承認ポリシー、 API 認証情報のことではありません。

ユーザーは、作業を実行できるサンドボックス内の ID です。その ID をサンドボックス内に存在させたい場合は manifest にユーザーを追加し、シェルコマンド、ファイル読み取り、パッチのようなモデル向けサンドボックスツールをそのユーザーとして実行したい場合は SandboxAgent.runAs を設定します。

ファイルレベルの共有ルールも必要であれば、ユーザーを manifest のグループおよびエントリの group メタデータと組み合わせてください。 runAs ユーザーは誰がサンドボックスネイティブな操作を実行するかを制御し、 Permissions はサンドボックスがワークスペースを materialize した後にそのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。

SnapshotSpec

SnapshotSpec は、新しいサンドボックスセッションに対して、保存済みワークスペース内容をどこから復元し、どこへ永続化し直すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、 sessionState は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。

ローカルの永続スナップショットにはローカルスナップショットを使い、アプリがリモートスナップショットクライアントを提供する場合はリモートスナップショットを使います。マウントされたパスや一時パスは、永続ワークスペース内容としてスナップショットにはコピーされません。

サンドボックスのライフサイクル

ライフサイクルモードは 2 つあります。 SDK 所有 と 開発者所有 です。

SDK 所有Runner がライブのサンドボックスを所有します。

sandbox.client を渡します。
Runner がサンドボックスセッションを作成または再開します。
エージェントが実行され、スナップショット対応のワークスペース状態を永続化できます。
Runner が runner 所有のリソースを閉じます。

開発者所有アプリケーションがライブのサンドボックスを所有します。

session を作成します。
実行に sandbox.session を渡します。
エージェントは既存のワークスペースを使います。
自分で確認、再利用し、その後セッションを閉じます。

サンドボックスが 1 回の実行の間だけ生きていればよいなら、 SDK 所有ライフサイクルを使います。 client、任意の manifest、任意の snapshot、クライアント options を渡すと、 runner がサンドボックスを作成または再開し、エージェントを実行し、スナップショット対応のワークスペース状態を永続化し、クライアントが runner 所有リソースをクリーンアップできるようにします。

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } 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 UnixLocalSandboxClient(),
  },
});

console.log(result.finalOutput);

サンドボックスを事前に作成したい、複数の実行で 1 つのライブサンドボックスを再利用したい、実行後にファイルを確認したい、自分で作成したサンドボックス上でストリーミングしたい、あるいはクリーンアップのタイミングを正確に決めたい場合は、開発者所有ライフサイクルを使います。 session を渡すと、 runner はそのライブサンドボックスを使いますが、代わりに閉じてはくれません。

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 task.', { sandbox: { session } });
  await run(agent, 'Follow-up task.', { sandbox: { session } });
} finally {
  await session.close?.();
}

`sandbox` 実行オプション

sandbox 実行オプションには、サンドボックスセッションの取得元と、新しいセッションの初期化方法を決める実行ごとのオプションが入ります。

サンドボックスの取得元

これらのオプションは、 runner がサンドボックスセッションを再利用、再開、作成のどれにするかを決定します。

オプション	使う場面	補足
`client`	runner にサンドボックスセッションの作成、再開、クリーンアップを任せたいとき	ライブのサンドボックス `session` を渡さない限り必須です
`session`	既に自分でライブのサンドボックスセッションを作成したとき	ライフサイクルは呼び出し側が所有し、 runner はそのライブのサンドボックスセッションを再利用します
`sessionState`	サンドボックスセッション状態はシリアライズ済みだが、ライブのサンドボックスセッションオブジェクトはないとき	`client` が必要です。 runner はその明示的状態から所有セッションとして再開します

新しいセッションの入力

これらのオプションは、 runner が新しいサンドボックスセッションを作成する場合にのみ関係します。

オプション	使う場面	補足
`manifest`	その場限りの新規セッション用ワークスペース上書きをしたいとき	省略時は `agent.defaultManifest` にフォールバックします
`snapshot`	新しいサンドボックスセッションをスナップショットから初期化したいとき	再開に近いフローやリモートスナップショットクライアントに便利です
`options`	サンドボックスクライアントに作成時オプションが必要なとき	Docker イメージ、プロバイダーのタイムアウトなど、クライアント固有の設定でよく使います

concurrencyLimits は、どれだけのサンドボックス materialization 作業を並列実行するかを制御します。大きな manifest やローカルディレクトリコピーでリソースをより厳密に制御したい場合は、manifestEntries と localDirFiles を使ってください。

Materialization の制御

materialization の制御は意図的に実行ごとです。同じ SandboxAgent でも、大きなローカルディレクトリコピーでは保守的な制限、小さな manifest では緩い制限を使えるよう、 sandbox 実行オプションの近くに置いてください。

manifest にファイル、ディレクトリ、リポジトリ、マウントのような独立したエントリが多い場合は concurrencyLimits.manifestEntries を使います。 localDir() エントリに多数のファイルが含まれ、ローカルコピーの負荷を抑えたい場合は concurrencyLimits.localDirFiles を使います。

完全な例: コーディングタスク

このコーディングスタイルの例は、よいデフォルトの出発点です。

import { run } from '@openai/agents';
import {
  Capabilities,
  Manifest,
  SandboxAgent,
  localDir,
  skills,
} from '@openai/agents/sandbox';
import {
  UnixLocalSandboxClient,
  localDirLazySkillSource,
} from '@openai/agents/sandbox/local';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const exampleDir = dirname(fileURLToPath(import.meta.url));
const hostRepoDir = join(exampleDir, 'repo');
const hostSkillsDir = join(exampleDir, 'skills');

const manifest = new Manifest({
  entries: {
    repo: localDir({ src: hostRepoDir }),
  },
});

const agent = new SandboxAgent({
  name: 'Sandbox engineer',
  model: 'gpt-5.5',
  instructions:
    'Read `repo/task.md` before editing files. Load the `$invoice-total-fixer` skill before changing code. Stay grounded in the repository, preserve existing behavior, and mention the exact verification command you ran. If you edit files with apply_patch, paths are relative to the sandbox workspace root.',
  defaultManifest: manifest,
  capabilities: [
    ...Capabilities.default(),
    skills({
      lazyFrom: localDirLazySkillSource(hostSkillsDir),
    }),
  ],
});

const result = await run(
  agent,
  'Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.',
  {
    sandbox: {
      client: new UnixLocalSandboxClient(),
    },
  },
);

console.log(result.finalOutput);

一般的なパターン

まずは上の完全な例から始めてください。多くの場合、同じ SandboxAgent をそのまま使い、変更するのはサンドボックスクライアント、サンドボックスセッションの取得元、またはワークスペースの取得元だけです。

サンドボックスクライアントの切り替え

エージェント定義はそのままにし、実行設定だけを変更します。コンテナ分離やイメージの同一性が必要なら Docker を使い、プロバイダー管理の実行が必要ならホスト型プロバイダーを使います。例やプロバイダーオプションについてはサンドボックスクライアントを参照してください。

ワークスペースの上書き

エージェント定義はそのままにし、新しいセッション用 manifest だけを sandbox: { client, manifest } で差し替えます。同じエージェントの役割を、エージェントを作り直さずに異なるリポジトリ、資料、タスクバンドルに対して実行したいときに使います。

サンドボックスセッションの注入

明示的なライフサイクル制御、実行後の確認、出力のコピーが必要な場合は、ライブのサンドボックスセッションを注入します。その実行では sandbox: { session } を使い、セッションのクローズはアプリケーションコードで行ってください。

セッション状態からの再開

既に RunState の外でサンドボックス状態をシリアライズしているなら、sandbox: { client, sessionState } で runner にその状態から再接続させます。サンドボックス状態が自前のストレージやジョブシステムにあり、Runner から直接再開したい場合に使います。

スナップショットから開始

sandbox: { client, snapshot } を使って、保存済みのファイルや成果物から新しいサンドボックスを初期化します。新しい実行を agent.defaultManifest だけでなく、保存済みワークスペース内容から開始したい場合に使います。

Git からスキルを読み込む

skills({ from: gitRepo(...) }) を使って、ローカルのスキル取得元をリポジトリベースのものに差し替えます。スキルバンドルに独自のリリースサイクルがある場合や、サンドボックス間で共有したい場合に使います。

ツールとして公開

ツールエージェントは、独自のサンドボックス境界を持つことも、親実行のライブサンドボックスを再利用することもできます。再利用は、高速な読み取り専用の探索エージェントに便利です。別のサンドボックスを作成、 hydrate 、スナップショット化するコストを払わずに、親が使っている正確なワークスペースを確認できます。

一方、ツールエージェントに本当の分離が必要な場合は、sandboxAgent.asTool(...) を通じて独自の runConfig を与えます。自由に変更させたい、信頼できないコマンドを実行させたい、または別のバックエンドやイメージを使いたい場合は、別のサンドボックスを使ってください。

ローカルツールや MCP と組み合わせる

サンドボックスワークスペースを保ったまま、同じエージェントで通常のツールも使えます。サンドボックス機能は tools、mcpServers、ハンドオフ、モデル設定、出力設定と共存できます。

エージェントメモリ

将来の sandbox-agent 実行が以前の実行から学習すべき場合は、memory() 機能を使います。メモリは SDK の会話型 Session メモリとは別です。サンドボックスワークスペース内のファイルに学びを要約し、後続の実行でそれらのファイルを読み取れるようにします。

セットアップ、読み取り / 生成の動作、複数ターンの会話、レイアウト分離についてはエージェントメモリを参照してください。

合成パターン

単一エージェントのパターンが明確になったら、次の設計上の問いは、より大きなシステムのどこにサンドボックス境界を置くかです。

sandbox agents は引き続き SDK の他の部分と合成できます。

ハンドオフ: サンドボックスを使わない受付エージェントから、文書中心の作業をサンドボックスレビュアーへ引き渡す
Agents as tools: 複数のサンドボックスエージェントをツールとして公開する。通常は各 asTool(...) 呼び出しにサンドボックス実行設定を渡し、各ツールが独自のサンドボックス境界を持つようにします
MCP 連携と通常の関数ツール: サンドボックス機能は mcpServers や通常のツールと共存できます
エージェントの実行: サンドボックス実行も通常の run() と Runner API を使います

ハンドオフでは、依然として 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。

asTool(...) では、関係は異なります。外側のオーケストレーターは 1 つの外側ターンを使ってツール呼び出しを決定し、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行には、独自のターンループ、maxTurns、承認、通常は独自のサンドボックス実行設定があります。外側のオーケストレーターから見ると、それらの作業はすべて 1 回のツール呼び出しの背後にあるため、ネストされたターンは外側実行のターンカウンターを増やしません。

参考情報

クイックスタート: 1 つの sandbox agent を動かす
サンドボックスクライアント: ローカル、 Docker 、ホスト型、マウントの各オプションを選ぶ
エージェントメモリ: 以前のサンドボックス実行から得た学びを保持し再利用する

コンセプト

構成要素の関係

利用場面

サンドボックスクライアントの選択

コア要素

サンドボックス実行の準備方法

SandboxAgent のオプション

defaultManifest

instructions と baseInstructions

capabilities

コンセプト

Manifest

権限

SnapshotSpec

サンドボックスのライフサイクル

sandbox 実行オプション

サンドボックスの取得元

新しいセッションの入力

Materialization の制御

完全な例: コーディングタスク

一般的なパターン

サンドボックスクライアントの切り替え

ワークスペースの上書き

サンドボックスセッションの注入

セッション状態からの再開

スナップショットから開始

Git からスキルを読み込む

ツールとして公開

ローカルツールや MCP と組み合わせる

エージェントメモリ

合成パターン

参考情報

`SandboxAgent` のオプション

`defaultManifest`

`instructions` と `baseInstructions`

`capabilities`

`sandbox` 実行オプション