← Создание агентов на Cloudflare / agents / tools

Sandbox

Agents могут использовать Sandbox чтобы выполнять код в изолированных контейнерных средах. Используйте Sandbox, если агенту нужны настоящая файловая система, доступ к shell-командам, языковые runtime, установка пакетов или долгоживущее состояние проекта, которое не должно выполняться внутри собственного Worker isolate агента.

Sandbox построен на Cloudflare Containers и предоставляет TypeScript API для выполнения команд, файловых операций, фоновых процессов и предварительного просмотра сервисов.

Используйте Sandbox для агентов, которым нужно:

• Запускайте ненадёжный или сгенерированный моделью код изолированно.
• Выполнять код на Python, Node.js, команды shell или менеджеры пакетов.
• Чтение, запись и управление файлами проекта.
• Запускайте тесты, линтеры, инструменты сборки или скрипты анализа данных.
• Поддерживайте рабочее пространство на протяжении нескольких ходов агента.

Привяжите Sandbox Durable Object к своему Worker, а затем обращайтесь к sandbox из методов агента с помощью 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,
		};
	}
}

Настройте контейнер Sandbox, привязку Durable Object и миграцию в wrangler.jsonc.

{
	"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 для файлов рабочего пространства, сгенерированного кода, установленных пакетов, логов и артефактов.

Для долгой работы в sandbox сочетайте Sandbox с устойчивое выполнение с fiber или Workflows чтобы агент мог восстановиться или сообщить о прогрессе, если работа продолжается дольше одного запроса.