エージェントは Sandbox を使い、隔離されたコンテナ環境でコードを実行できます。エージェントに本物のファイルシステム、シェルコマンド、言語ランタイム、パッケージのインストール、またはエージェント自身の Worker isolate 内では動かしたくない長寿命のプロジェクト状態が必要なときに Sandbox を使います。
Sandbox は Cloudflare Containers の上に構築されており、コマンド実行、ファイル操作、バックグラウンドプロセス、サービスプレビュー向けの TypeScript API を提供します。
次のようなエージェントには Sandbox を使います。
- 信頼できないコードやモデルが生成したコードを隔離して実行する。
- Python、Node.js、シェルコマンド、パッケージマネージャーを実行する。
- プロジェクトファイルの読み書きと管理をする。
- テスト、リンター、ビルドツール、データ分析スクリプトを実行する。
- 複数ターンにわたってワークスペースを維持する。
Sandbox Durable Object を Worker にバインドし、エージェントのメソッドから getSandbox() でサンドボックスにアクセスします。
import { Agent, callable } from "agents";
import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
export class CodeAgent extends Agent {
@callable()
async runPython(code) {
const sandbox = getSandbox(this.env.Sandbox, this.name);
await sandbox.writeFile("/workspace/script.py", code);
const result = await sandbox.exec("python3 /workspace/script.py");
this.setState({ lastOutput: result.stdout });
return {
success: result.success,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.exitCode,
};
}
}import { Agent, callable } from "agents";
import { getSandbox } from "@cloudflare/sandbox";
import type { Sandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";
type Env = {
Sandbox: DurableObjectNamespace<Sandbox>;
};
export class CodeAgent extends Agent<Env, { lastOutput?: string }> {
@callable()
async runPython(code: string) {
const sandbox = getSandbox(this.env.Sandbox, this.name);
await sandbox.writeFile("/workspace/script.py", code);
const result = await sandbox.exec("python3 /workspace/script.py");
this.setState({ lastOutput: result.stdout });
return {
success: result.success,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.exitCode,
};
}
}wrangler.jsonc で Sandbox コンテナ、Durable Object バインディング、マイグレーションを設定します。
{
"containers": [
{
"class_name": "Sandbox",
"image": "./Dockerfile",
"instance_type": "lite",
"max_instances": 1
}
],
"durable_objects": {
"bindings": [
{
"name": "Sandbox",
"class_name": "Sandbox"
}
]
},
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": ["Sandbox"]
}
]
}[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"
instance_type = "lite"
max_instances = 1
[[durable_objects.bindings]]
name = "Sandbox"
class_name = "Sandbox"
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "Sandbox" ]ユーザーに見せる進捗や小さなメタデータはエージェントの状態に置きます。ワークスペースのファイル、生成コード、パッケージのインストール、ログ、成果物はサンドボックスのファイルシステムに置きます。
長時間かかるサンドボックス作業では、Sandbox を fibers による耐久実行 または Workflows と組み合わせます。作業が 1 リクエストの寿命を超えても、エージェントが復旧したり進捗を報告したりできます。
Sandbox SDK
コマンド、ファイル、セッション、デプロイの完全な Sandbox ドキュメントです。
コマンドの実行
サンドボックス環境でシェルコマンドを実行します。
ファイルの管理
サンドボックスのファイルを読み書き、アップロード、ダウンロードします。