智能体生成代码、与文件系统交互并运行 shell 命令。由于我们无法预测智能体可能执行的操作，因此其环境必须隔离，以防止其访问凭证、文件或网络。沙盒通过在智能体的执行环境与您的主机系统之间创建边界来提供这种隔离。
在 Deep Agents 中，沙盒是 后端，用于定义智能体操作的环境。与其他仅暴露文件操作的后端（State、Filesystem、Store）不同，沙盒后端还为智能体提供了一个 execute 工具来运行 shell 命令。配置沙盒后端后，智能体将获得：
- 所有标准文件系统工具（
ls、read_file、write_file、edit_file、glob、grep）
- 用于在沙盒中运行任意 shell 命令的
execute 工具
- 保护主机系统的安全边界
为何使用沙盒？
沙盒用于安全目的。
它们允许智能体执行任意代码、访问文件和使用网络，而不会危及您的凭证、本地文件或主机系统。
当智能体自主运行时，这种隔离至关重要。
沙盒特别适用于：
- 编码智能体：自主运行的智能体可以使用 shell、git、克隆仓库（许多提供商提供原生 git API，例如 Daytona 的 git 操作），并运行 Docker-in-Docker 以进行构建和测试管道
- 数据分析智能体——加载文件、安装数据分析库（pandas、numpy 等）、运行统计计算，并在安全、隔离的环境中创建输出（如 PowerPoint 演示文稿）
使用 Deep Agents CLI？ CLI 通过 --sandbox 标志内置沙盒支持。有关 CLI 特定设置、标志（--sandbox-id、--sandbox-setup）和示例，请参阅 使用远程沙盒。 基本用法
这些示例假设您已使用提供商的 SDK 创建了沙盒/开发盒，并已设置凭证。有关注册、身份验证和提供商特定生命周期的详细信息，请参阅 可用提供商。
import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { DenoSandbox } from "@langchain/deno";
// 创建并初始化沙箱
const sandbox = await DenoSandbox.create({
memoryMb: 1024,
lifetime: "10m",
});
try {
const agent = createDeepAgent({
model: new ChatAnthropic({ model: "claude-opus-4-6" }),
systemPrompt: "You are a JavaScript coding assistant with sandbox access.",
backend: sandbox,
});
const result = await agent.invoke({
messages: [
{
role: "user",
content:
"Create a simple HTTP server using Deno.serve and test it with curl",
},
],
});
} finally {
await sandbox.close();
}
可用提供商
未看到您的提供商？您可以实现自己的沙盒后端。请参阅 贡献沙盒集成。
生命周期和作用域
沙盒会消耗资源并产生成本，直到被关闭。您如何管理其生命周期取决于您的应用程序。
选择沙盒生命周期如何映射到您的应用程序资源。有关此决策的更多信息，请参阅 投入生产。
线程作用域（默认）
每个对话都有自己的沙盒。沙盒在首次运行时创建，并在同一对话线程的后续消息中重复使用。当线程被清理（或沙盒 TTL 过期）时，沙盒将被销毁。这是大多数智能体的正确默认设置。
示例：一个数据分析机器人，每个对话都从干净的环境开始。
助手作用域
给定 助手 的所有线程共享一个沙盒。沙盒 ID 存储在助手的配置中，因此每次对话都会返回到相同的环境。文件、安装的包和克隆的仓库在对话之间持久存在。当智能体维护一个长期运行的工作区时，请使用此模式。
示例：一个编码助手，在对话之间维护克隆的仓库和安装的依赖项。
助手作用域的沙盒会随时间累积文件、安装的包和其他沙盒内状态。使用您的沙盒提供商配置 TTL，使用快照定期重置，或实现清理逻辑以防止沙盒的磁盘和内存无限增长。线程作用域的沙盒通过在每次对话时从头开始来避免此问题。
基本生命周期
// 创建并初始化
const sandbox = await ModalSandbox.create(options);
// 使用沙盒（直接或通过智能体）
const result = await sandbox.execute("echo hello");
// 完成后清理
await sandbox.close();
每对话生命周期
在聊天应用程序中，对话通常由 thread_id 表示。
通常，每个 thread_id 应使用其自己唯一的沙盒。
在您的应用程序中或沙盒提供商允许将元数据附加到沙盒时，存储沙盒 ID 与 thread_id 之间的映射。
聊天应用程序的 TTL。 当用户可以在空闲时间后重新参与时，您通常不知道他们是否会返回或何时返回。在沙盒上配置生存时间（TTL）——例如，TTL 用于归档或 TTL 用于删除——以便提供商自动清理空闲的沙盒。许多沙盒提供商支持此功能。
import "dotenv/config";
import { randomUUID } from "node:crypto";
import { Daytona } from "@daytonaio/sdk";
import type { CreateSandboxFromSnapshotParams } from "@daytonaio/sdk";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
const client = new Daytona();
const threadId = randomUUID();
// 通过 thread_id 获取或创建沙盒
let sandbox;
try {
sandbox = await client.findOne({ labels: { thread_id: threadId } });
} catch {
const params: CreateSandboxFromSnapshotParams = {
labels: { thread_id: threadId },
// 添加 TTL，以便沙盒在空闲时被清理（分钟）
autoDeleteInterval: 3600,
};
sandbox = await client.create(params);
}
const backend = await DaytonaSandbox.fromId(sandbox.id);
const agent = createDeepAgent({
backend,
systemPrompt:
"You are a coding assistant with sandbox access. You can create and run code in the sandbox.",
});
try {
const result = await agent.invoke(
{
messages: [
{
role: "user",
content: "Create a hello world Python script and run it",
},
],
},
{
configurable: {
thread_id: threadId,
},
},
);
const lastMessage = result.messages[result.messages.length - 1];
console.log(
typeof lastMessage.content === "string"
? lastMessage.content
: String(lastMessage.content),
);
} catch (err) {
// 可选：在异常时主动删除沙盒
await client.delete(sandbox);
throw err;
}
集成模式
根据智能体运行的位置，有两种架构模式用于将智能体与沙盒集成。
智能体在沙盒中模式
智能体在沙盒内运行，您通过网络与其通信。您构建一个预装了智能体框架的 Docker 或 VM 镜像，在沙盒内运行它，并从外部连接以发送消息。
优点：
- ✅ 与本地开发非常相似。
- ✅ 智能体与环境紧密耦合。
权衡：
- 🔴 API 密钥必须位于沙盒内（安全风险）。
- 🔴 更新需要重建镜像。
- 🔴 需要用于通信的基础设施（WebSocket 或 HTTP 层）。
要在沙盒中运行智能体，请构建镜像并在其上安装 deepagents。
FROM python:3.11
RUN pip install deepagents-cli
沙盒作为工具模式
智能体在您的机器或服务器上运行。当需要执行代码时，它会调用沙盒工具（例如 execute、read_file 或 write_file），这些工具会调用提供商的 API 以在远程沙盒中运行操作。
优点：
- ✅ 无需重建镜像即可即时更新智能体代码。
- ✅ 智能体状态与执行之间的分离更清晰。
- API 密钥保留在沙盒外。
- 沙盒故障不会丢失智能体状态。
- 可选择在多个沙盒中并行运行任务。
- ✅ 仅支付执行时间的费用。
权衡：
import "dotenv/config";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
// 也可以使用 E2B、Runloop、Modal 实现
const sandbox = await DaytonaSandbox.create();
const agent = createDeepAgent({
backend: sandbox,
systemPrompt:
"You are a coding assistant with sandbox access. You can create and run code in the sandbox.",
});
try {
const result = await agent.invoke({
messages: [
{
role: "user",
content: "Create a hello world Python script and run it",
},
],
});
const lastMessage = result.messages[result.messages.length - 1];
console.log(
typeof lastMessage.content === "string"
? lastMessage.content
: String(lastMessage.content),
);
} catch (err) {
// 可选：在异常时主动删除沙盒
await sandbox.close();
throw err;
}
沙盒如何工作
隔离边界
所有沙盒提供商都保护您的主机系统免受智能体的文件系统和 shell 操作的影响。智能体无法读取您的本地文件、访问您机器上的环境变量或干扰其他进程。但是，沙盒本身不能防止：
- 上下文注入：控制智能体部分输入的攻击者可以指示其在沙盒内运行任意命令。沙盒是隔离的，但智能体在其中拥有完全控制权。
- 网络渗出：除非阻止网络访问，否则上下文注入的智能体可以通过 HTTP 或 DNS 将数据发送出沙盒。一些提供商支持阻止网络访问（例如，Modal 上的
blockNetwork: true）。
有关如何处理机密和缓解这些风险的信息，请参阅 安全注意事项。
execute 方法
沙盒后端具有简单的架构：提供商必须实现的唯一方法是 execute()，该方法运行 shell 命令并返回其输出。所有其他文件系统操作（read、write、edit、ls、glob、grep）都由 BaseSandbox 基类在 execute() 之上构建，该基类构造脚本并通过 execute() 在沙盒内运行它们。
这种设计意味着：
- 添加新提供商很简单。 实现
execute()——基类处理其他所有内容。
execute 工具是条件可用的。 在每次模型调用时，框架会检查后端是否实现了 SandboxBackendProtocol。如果不是，则工具将被过滤掉，智能体永远不会看到它。
当智能体调用 execute 工具时，它会提供一个 command 字符串，并返回组合的 stdout/stderr、退出代码，以及输出过大时的截断通知。
您也可以在应用程序代码中直接调用后端 execute() 方法。
例如：
4
[Command succeeded with exit code 0]
bash: foobar: command not found
[Command failed with exit code 127]
read_file 逐步访问它。这可以防止上下文窗口溢出。
两种文件访问平面
文件进出沙盒有两种不同的方式，了解何时使用每种方式非常重要：
智能体文件系统工具：read_file、write_file、edit_file、ls、glob、grep 和 execute 是 LLM 在执行期间调用的工具。这些工具通过沙盒内的 execute() 运行。智能体使用它们来读取代码、写入文件并运行命令作为其任务的一部分。
文件传输 API：您的应用程序代码调用的 uploadFiles() 和 downloadFiles() 方法。这些方法使用提供商的原生文件传输 API（而不是 shell 命令），旨在在您的主机环境和沙盒之间移动文件。使用这些方法来：
- 在智能体运行之前，用源代码、配置或数据填充沙盒
- 在智能体完成后检索工件（生成的代码、构建输出、报告）
- 预填充智能体将需要的依赖项
处理文件
填充沙盒
使用 uploadFiles() 在智能体运行之前填充沙盒。文件内容以 Uint8Array 形式提供：
const encoder = new TextEncoder();
const responses = await sandbox.uploadFiles([
["src/index.js", encoder.encode("console.log('Hello')")],
["package.json", encoder.encode('{"name": "my-app"}')],
]);
// 每个响应表示成功或失败
for (const res of responses) {
if (res.error) {
console.error(`Failed to upload ${res.path}: ${res.error}`);
}
}
检索工件
使用 downloadFiles() 在智能体完成后从沙盒检索文件：
const results = await sandbox.downloadFiles(["src/index.js", "output.txt"]);
const decoder = new TextDecoder();
for (const result of results) {
if (result.content) {
console.log(`${result.path}: ${decoder.decode(result.content)}`);
} else {
console.error(`Failed to download ${result.path}: ${result.error}`);
}
}
在沙盒内，智能体使用其自己的文件系统工具（read_file、write_file）：而不是 uploadFiles 或 downloadFiles。这些方法供您的应用程序代码在主机和沙盒之间的边界移动文件。
安全注意事项
沙盒将代码执行与您的主机系统隔离，但它们不能防止上下文注入。控制智能体部分输入的攻击者可以指示其读取文件、运行命令或从沙盒内渗出数据。这使得沙盒内的凭证尤其危险。
切勿将机密信息放入沙盒中。 API 密钥、令牌、数据库凭证和其他注入沙盒的机密信息（通过环境变量、挂载文件或 secrets 选项）可以被上下文注入的智能体读取和渗出。这适用于短期或限定范围的凭证——如果智能体可以访问它们，攻击者也可以。
安全处理机密信息
如果您的智能体需要调用经过身份验证的 API 或访问受保护的资源，您有两个选择：
-
将机密信息保留在沙盒外的工具中。 定义在您的主机环境（而非沙盒内）运行的工具，并在那里处理身份验证。智能体通过名称调用这些工具，但永远不会看到凭证。这是推荐的方法。
-
使用注入凭证的网络代理。 一些沙盒提供商支持代理，这些代理拦截沙盒发出的出站 HTTP 请求，并在转发之前附加凭证（例如
Authorization 标头）。智能体永远不会看到机密信息——它只是向 URL 发出普通请求。这种方法尚未在提供商中广泛可用。
如果必须将机密信息注入沙盒（不推荐），请采取以下预防措施：
- 为所有工具调用启用人机回环批准，而不仅仅是敏感工具
- 阻止或限制沙盒的网络访问以限制渗出路径
- 使用尽可能窄的凭证范围和尽可能短的生命周期
- 监控沙盒网络流量以查找意外的出站请求
即使有这些防护措施，这仍然是一种不安全的变通方法。足够有创意的上下文注入攻击可以绕过输出过滤和 HITL 审查。 一般最佳实践
- 在应用程序对其采取行动之前，审查沙盒输出
- 在不需要时阻止沙盒网络访问
- 使用中间件过滤或编辑工具输出中的敏感模式
- 将沙盒内生成的所有内容视为不受信任的输入
