コンセプト

最新のエージェントは、ファイルシステム内の実際のファイルを操作できるときに最も効果を発揮します。 サンドボックスエージェント は、専用ツールと 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 クライアントとホステッドクライアントは、より強力な環境分離を提供します。これは、セッションで説明している SDK の対話型 Session インターフェースとは異なります。

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

構成要素の関係

サンドボックス実行では、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。Runner はエージェントを準備し、稼働中のサンドボックスセッションに関連付け、後続の実行に備えて状態を保存できます。

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

Runnerinstructions の準備と機能ツールの関連付け

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

保存済み状態後で再開するか、新しいワークスペースを初期化

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

ライフサイクルは、次の 3 つのフェーズで考えます。

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

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

利用に適したケース

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

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

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

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

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

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

主要な構成要素

レイヤー	SDK の主な構成要素	回答する問い
エージェント定義	`SandboxAgent`、`Manifest`、各機能	どのエージェントを実行し、どのような新規セッション用ワークスペース要件から開始するか？
サンドボックス実行	`sandbox` 実行オプション、サンドボックスクライアント、稼働中のサンドボックスセッション	この実行はどのように稼働中のサンドボックスセッションを取得し、どこで作業を実行するか？
保存済みサンドボックス状態	`RunState` のサンドボックスペイロード、`sessionState`、スナップショット	このワークフローはどのように以前のサンドボックス作業へ再接続し、保存済みの内容から新しいサンドボックスセッションを初期化するか？

SDK の主な構成要素は、次のように各レイヤーに対応します。

構成要素	管理対象	確認する問い
`SandboxAgent`	エージェント定義	このエージェントは何を行い、どのデフォルト設定を引き継ぐべきか？
`Manifest`	新規セッション用ワークスペースのファイルとフォルダー	実行開始時にファイルシステム上にどのファイルとフォルダーが存在すべきか？
`Capability`	サンドボックスネイティブの動作	どのツール、instructions の断片、またはランタイム動作をこのエージェントに追加すべきか？
`sandbox` 実行オプション	実行ごとのサンドボックスクライアントとサンドボックスセッションの取得元	この実行ではサンドボックスセッションを注入、再開、または作成すべきか？
`RunState`	Runner が管理する保存済みサンドボックス状態	以前の Runner 管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継ぐか？
`sandbox.sessionState`	明示的にシリアライズされたサンドボックスセッション状態	`RunState` の外部ですでにシリアライズしたサンドボックス状態から再開するか？
`sandbox.snapshot`	新しいサンドボックスセッション用に保存されたワークスペース内容	新しいサンドボックスセッションを、保存済みのファイルと成果物から開始するか？

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

Manifest または Manifest の初期化オブジェクトを使用して、新規セッション用ワークスペースの要件を定義します。
SandboxAgent を使用してエージェントを定義します。
組み込みまたはカスタムの機能を追加します。
各実行がサンドボックスセッションを取得する方法を、run(agent, input, { sandbox: ... }) または new Runner({ sandbox: ... }) で決定します。

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

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

sandbox 実行オプションからサンドボックスセッションを解決します。
実行に使用する有効なワークスペース入力を決定します。
各機能が、生成された Manifest を処理できるようにします。
最終的な instructions を固定の順序で構築します。まず SDK のデフォルトのサンドボックスプロンプト、または明示的に上書きした場合は baseInstructions、次に instructions、各機能の instructions 断片、リモートマウントのポリシーテキスト、レンダリングされたファイルシステムツリーの順です。
機能ツールを稼働中のサンドボックスセッションに関連付け、準備済みのエージェントを通常の run() および Runner API を通じて実行します。

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

`SandboxAgent` のオプション

通常の Agent フィールドに加えて、次のサンドボックス固有のオプションがあります。

オプション	最適な用途
`defaultManifest`	Runner が作成する新しいサンドボックスセッションのデフォルトワークスペース。
`instructions`	SDK のサンドボックスプロンプトの後に追加される、ロール、ワークフロー、成功基準。
`baseInstructions`	SDK のサンドボックスプロンプトを置き換える高度なエスケープハッチ。
`capabilities`	このエージェントに付随させるサンドボックスネイティブのツールと動作。
`runAs`	shell コマンド、ファイル読み取り、パッチなど、モデル向けのサンドボックスツールで使用するユーザー ID。

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

`defaultManifest`

defaultManifest は、Runner がこのエージェント用に新しいサンドボックスセッションを作成するときに使用するデフォルトワークスペースです。Manifest インスタンス、または new 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 のサンドボックス基本プロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを維持しながら、独自のロール、ワークフロー、成功基準を追加できます。

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

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

ユーザーの一時的なタスクを instructions にコピーすること、Manifest に含めるべき長い参考資料を埋め込むこと、組み込み機能がすでに注入するツールドキュメントを繰り返すこと、モデルが実行時に必要としないローカルインストール手順を混在させることは避けてください。

`capabilities`

各機能は、サンドボックスネイティブの動作を SandboxAgent に追加します。実行開始前にワークスペースを調整し、サンドボックス固有の instructions を追加し、稼働中のサンドボックスセッションに関連付けられるツールを公開し、そのエージェントのモデル動作または入力処理を調整できます。

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

機能	追加する場合	注記
`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 リポジトリのクローン、リモートストレージマウントの接続、環境変数の設定、ユーザーまたはグループの定義、ワークスペース外の特定の絶対パスへのアクセス許可を行えます。

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

Manifest エントリのパスは、ワークスペースからの相対パスです。絶対パスを指定したり、.. を使用してワークスペース外へ移動したりすることはできません。これにより、ローカル、Docker、ホステッドクライアント間でワークスペース要件の移植性が維持されます。

作業開始前にエージェントが必要とする内容には、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 は、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 を渡します。
エージェントが既存のワークスペースを使用します。
セッションを確認して再利用し、最後に自分で終了します。

サンドボックスを 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.6-sol',
  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.6-sol',
  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`	新規セッション用ワークスペースを一時的に上書きする場合。	`Manifest` または Manifest の初期化オブジェクトを受け取ります。省略した場合は `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.6-sol',
  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 を使用し、プロバイダー管理の実行が必要な場合はホステッドプロバイダーを使用します。コード例とプロバイダーのオプションについては、サンドボックスクライアントを参照してください。

ワークスペースの上書き

エージェント定義はそのまま維持し、sandbox: { client, manifest } で新規セッション用の Manifest だけを置き換えます。同じエージェントのロールを、エージェントを再構築することなく異なるリポジトリ、パケット、タスクバンドルに対して実行する場合に使用します。

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

明示的なライフサイクル制御、実行後の確認、または出力のコピーが必要な場合は、稼働中のサンドボックスセッションを注入します。その実行では sandbox: { session } を使用し、アプリケーションコード内でセッションを終了します。

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

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

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

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

Git からのスキル読み込み

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

ツールとしての公開

ツールエージェントには、独自のサンドボックス境界を割り当てることも、親の実行で稼働中のサンドボックスを再利用させることもできます。高速な読み取り専用の探索エージェントには再利用が便利です。別のサンドボックスを作成、準備、スナップショット化するコストをかけずに、親が使用しているものとまったく同じワークスペースを確認できます。

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

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

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

メモリ

後続のサンドボックスエージェントの実行で以前の実行から学習させる場合は、memory() 機能を使用します。メモリは、SDK の対話型 Session メモリとは別のものです。学習内容をサンドボックスワークスペース内のファイルへ要約し、後続の実行でそれらのファイルを読み取れるようにします。

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

構成パターン

単一エージェントのパターンを理解した後は、より大きなシステムのどこにサンドボックス境界を配置するかを検討します。

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

ハンドオフ：ドキュメント量の多い作業を、サンドボックスを使用しない受付エージェントからサンドボックス内のレビューエージェントへ引き継ぎます。
Agents as tools：複数のサンドボックスエージェントをツールとして公開します。通常は、各 asTool(...) 呼び出しでサンドボックス実行設定を渡し、各ツールに独自のサンドボックス境界を割り当てます。
MCP と通常の関数ツール：サンドボックス機能は、mcpServers および通常のツールと併用できます。
エージェントの実行：サンドボックス実行でも、通常の run() および Runner API を使用します。

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

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

コンセプト

構成要素の関係

利用に適したケース

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

主要な構成要素

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

SandboxAgent のオプション

defaultManifest

instructions と baseInstructions

capabilities

コンセプト

Manifest

権限

SnapshotSpec

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

sandbox 実行オプション

サンドボックスの取得元

新規セッションの入力

実体化の制御

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

一般的なパターン

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

ワークスペースの上書き

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

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

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

Git からのスキル読み込み

ツールとしての公開

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

メモリ

構成パターン

関連資料

`SandboxAgent` のオプション

`defaultManifest`

`instructions` と `baseInstructions`

`capabilities`

`sandbox` 実行オプション