コンセプト

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

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

SandboxAgent は Agent を拡張するため、引き続き Agent です。 instructions、 tools、 handoffs、 mcpServers、 modelSettings、出力型、ガードレール、フックなど、通常のエージェントのインターフェイスを維持し、通常の run() と Runner API を通じて実行されます。変わるのは実行境界です。

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

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

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

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

構成要素の関係

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

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

Runner指示を準備し、機能ツールをバインド

サンドボックスセッションコマンドが実行され、ファイルが変更されるワークスペース

保存済み状態後で再開、または新しいワークスペースを初期化

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

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

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

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

利用シーン

サンドボックスエージェントは、ワークスペース中心のワークフローに適しています。例:

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

ファイルや稼働中のファイルシステムへのアクセスが不要な場合は、引き続き Agent を使用してください。 shell アクセスがたまに使う機能にすぎない場合は hosted shell を追加します。ワークスペース境界そのものが機能の一部である場合は、サンドボックスエージェントを使用してください。

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

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

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

コア要素

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

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

要素	担うもの	問うべき質問
`SandboxAgent`	エージェント定義	このエージェントは何をすべきか、どのデフォルトを一緒に持たせるべきか
`Manifest`	新規セッションのワークスペースファイルとフォルダ	実行開始時にファイルシステム上にどのファイルとフォルダが存在すべきか
`Capability`	サンドボックスネイティブな動作	このエージェントにどのツール、指示フラグメント、ランタイム動作を付与すべきか
`sandbox` 実行オプション	実行ごとのサンドボックスクライアントとサンドボックスセッションのソース	この実行はサンドボックスセッションを注入、再開、または作成すべきか
`RunState`	ランナー管理の保存済みサンドボックス状態	以前のランナー管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継ぐのか
`sandbox.sessionState`	明示的にシリアライズされたサンドボックスセッション状態	`RunState` の外で既にシリアライズしたサンドボックス状態から再開したいのか
`sandbox.snapshot`	新規サンドボックスセッション用の保存済みワークスペース内容	新しいサンドボックスセッションを保存済みファイルと成果物から開始すべきか

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

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

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

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

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

サンドボックス化によってターンの意味は変わりません。ターンは引き続きモデルの 1 ステップであり、単一の shell コマンドやサンドボックスアクションではありません。サンドボックス側の操作とターンの間に固定された 1:1 の対応はありません。実践的なルールとして、サンドボックス作業が行われた後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、別のターンが消費されます。

`SandboxAgent` オプション

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

オプション	最適な用途
`defaultManifest`	ランナーが作成する新規サンドボックスセッションのデフォルトワークスペース
`instructions`	SDK サンドボックスプロンプトの後に追加される、追加の役割、ワークフロー、成功基準
`baseInstructions`	SDK サンドボックスプロンプトを置き換える高度なエスケープハッチ
`capabilities`	このエージェントと一緒に持たせるべきサンドボックスネイティブなツールと動作
`runAs`	shell コマンド、ファイル読み取り、パッチなど、モデルに公開されるサンドボックスツールのユーザー ID

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

`defaultManifest`

defaultManifest は、ランナーがこのエージェント用に新しいサンドボックスセッションを作成する際に使用するデフォルトワークスペースです。 Manifest インスタンス、または new Manifest(...) に渡すものと同じ init オブジェクトを渡します。エージェントが通常開始すべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使用します。

これはデフォルトにすぎません。実行は 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 では、これらの指示は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保持したまま、独自の役割、ワークフロー、成功基準を追加できます。

SDK のサンドボックスベースプロンプトを置き換えたい場合にのみ、 baseInstructions を使用します。ほとんどのエージェントでは設定すべきではありません。

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

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

`capabilities`

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

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

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

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

コンセプト

Manifest

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

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

Manifest エントリのパスはワークスペース相対です。絶対パスにしたり、 .. でワークスペースから抜けたりすることはできません。これにより、ローカル、 Docker、 hosted クライアント間でワークスペースの取り決めを移植可能に保てます。

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

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

ローカルでのマテリアライズでは、 localFile() と localDir() のソースパスはローカルソースベースディレクトリ内に収まっている必要があります。デフォルトのベースは Node プロセスの現在の作業ディレクトリであり、ローカルサンドボックスクライアントはエントリをマテリアライズする際にクライアント固有のベースを提供する場合があります。別の絶対ホストディレクトリからソースを取得する必要がある場合は、必要最小限の Manifest.extraPathGrants エントリを追加します。

extraPathGrants は、ローカルの遅延スキル探索にも使用されます。ソースベースディレクトリの外を指す localDirLazySkillSource() は、 manifest がそのディレクトリを許可していない限り無視されます。共有スキル、データセット、参照リポジトリなどの入力バンドルには、 readOnly: true を推奨します。

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

const appRoot = dirname(fileURLToPath(import.meta.url));
const repoDir = join(appRoot, 'repo');
const sharedSkillsDir = '/opt/company/agent-skills';

const manifest = new Manifest({
  extraPathGrants: [
    {
      path: sharedSkillsDir,
      readOnly: true,
      description: 'Shared skill bundle.',
    },
  ],
  entries: {
    repo: localDir({ src: repoDir }),
  },
});

const skillCapability = skills({
  lazyFrom: localDirLazySkillSource({
    src: sharedSkillsDir,
  }),
});

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

Permissions

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

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

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

SnapshotSpec

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

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

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

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

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

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

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

session を作成します。
実行に sandbox.session を渡します。
エージェントは既存のワークスペースを使用します。
検査し、再利用してから、自分で session をクローズします。

サンドボックスが 1 回の実行の間だけ存在すればよい場合は、 SDK 所有のライフサイクルを使用します。 client、任意の manifest、任意の snapshot、クライアントの options を渡します。ランナーはサンドボックスを作成または再開し、エージェントを実行し、スナップショットに裏付けられたワークスペース状態を永続化し、クライアントに 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 を渡すと、ランナーはそのライブサンドボックスを使用しますが、あなたの代わりにクローズはしません。

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 実行オプションには、サンドボックスセッションの取得元と、新規セッションをどのように初期化するかを決める実行ごとのオプションが含まれます。

サンドボックスソース

これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、または作成すべきかを決めます。

オプション	使用する場合	メモ
`client`	ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合	ライブサンドボックス `session` を提供しない限り必須です。
`session`	既にライブサンドボックスセッションを自分で作成している場合	呼び出し元がライフサイクルを所有します。ランナーはそのライブサンドボックスセッションを再利用します。
`sessionState`	シリアライズされたサンドボックスセッション状態はあるが、ライブサンドボックスセッションオブジェクトはない場合	`client` が必要です。ランナーはその明示的な状態から所有セッションとして再開します。

新規セッション入力

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

オプション	使用する場合	メモ
`manifest`	新規セッションのワークスペースを単発で上書きしたい場合	`Manifest` または manifest init オブジェクトを受け取ります。省略時は `agent.defaultManifest` にフォールバックします。
`snapshot`	新規サンドボックスセッションをスナップショットから初期化すべき場合	再開に似たフローやリモートスナップショットクライアントに便利です。
`options`	サンドボックスクライアントに作成時オプションが必要な場合	Docker イメージ、プロバイダーのタイムアウト、同様のクライアント固有設定で一般的です。

concurrencyLimits は、サンドボックスのマテリアライズ作業をどれだけ並列に実行できるかを制御します。大規模な manifest やローカルディレクトリのコピーでより厳密なリソース制御が必要な場合は、 manifestEntries と localDirFiles を使用します。

マテリアライズ制御

マテリアライズ制御は意図的に実行ごとに設定します。同じ 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({
        src: 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 を使用し、プロバイダー管理の実行が必要な場合は hosted プロバイダーを使用します。例とプロバイダーオプションについては、サンドボックスクライアントを参照してください。

ワークスペースのオーバーライド

エージェント定義は同じままにして、 sandbox: { client, manifest } で新規セッションの manifest だけを差し替えます。エージェントの役割は同じまま、異なるリポジトリ、パケット、タスクバンドルに対して実行したい場合に使用します。

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

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

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

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

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

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

Git からのスキル読み込み

skills({ from: gitRepo(...) }) で、ローカルスキルソースをリポジトリベースのソースに差し替えます。スキルバンドルが独自のリリースサイクルを持つ場合や、複数のサンドボックスで共有すべき場合に使用します。

ツールとしての公開

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

一方でツールエージェントに実際の分離が必要な場合は、 sandboxAgent.asTool(...) 経由で独自の runConfig を与えます。ツールエージェントが自由に変更したり、信頼できないコマンドを実行したり、異なるバックエンドやイメージを使用したりすべき場合は、別のサンドボックスを使用します。

ローカルツールおよび MCP との組み合わせ

同じエージェントで通常のツールを使用しながら、サンドボックスワークスペースを維持できます。サンドボックス機能は、 tools、 mcpServers、ハンドオフ、モデル設定、出力設定と共存できます。

メモリ

今後のサンドボックスエージェント実行が過去の実行から学習できるようにするには、 memory() 機能を使用します。メモリは SDK の会話用 Session メモリとは別のものです。教訓をサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読み取れるようにします。

設定、読み取り/生成動作、マルチターン会話、レイアウト分離については、エージェントメモリを参照してください。

構成パターン

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

サンドボックスエージェントは、引き続き SDK の他の部分と組み合わせられます。

ハンドオフ: ドキュメント量の多い作業を、サンドボックスを使わない intake エージェントからサンドボックスレビュアーに渡します。
Agents as tools: 複数のサンドボックスエージェントをツールとして公開します。通常は各 asTool(...) 呼び出しでサンドボックス実行設定を渡し、各ツールに独自のサンドボックス境界を持たせます。
MCP と通常の関数ツール: サンドボックス機能は、 mcpServers や通常のツールと共存できます。
エージェントの実行: サンドボックス実行でも、通常の run() と Runner API を使用します。

ハンドオフでは、トップレベルの実行とトップレベルのターンループは引き続き 1 つです。アクティブなエージェントは変わりますが、実行が入れ子になるわけではありません。

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

コンセプト

構成要素の関係

利用シーン

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

コア要素

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

SandboxAgent オプション

defaultManifest

instructions と baseInstructions

capabilities

コンセプト

Manifest

Permissions

SnapshotSpec

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

sandbox 実行オプション

サンドボックスソース

新規セッション入力

マテリアライズ制御

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

一般的なパターン

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

ワークスペースのオーバーライド

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

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

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

Git からのスキル読み込み

ツールとしての公開

ローカルツールおよび MCP との組み合わせ

メモリ

構成パターン

関連情報

`SandboxAgent` オプション

`defaultManifest`

`instructions` と `baseInstructions`

`capabilities`

`sandbox` 実行オプション