沙箱是什么
沙箱是 Deep Agents 的一种后端——在隔离环境中提供文件系统 + Shell 执行
在 Deep Agents 中，沙箱就是后端（backends）。与其他后端（State、Filesystem、Store）不同，沙箱后端多了一个 execute 工具，让 Agent 可以在沙箱内运行任意 Shell 命令。
| 能力 | 说明 | 对比其他后端 |
|---|---|---|
| 文件系统工具 | ls、read_file、write_file、edit_file、glob、grep |
所有后端都有 |
| execute 工具 | 运行任意 Shell 命令，返回 stdout/stderr | 沙箱独有 |
| 安全边界 | 隔离容器保护宿主机系统 | 沙箱独有 |
| 文件传输 | uploadFiles() / downloadFiles() |
沙箱后端支持 |
架构示意（Agent ↔ 沙箱通信协议）：Agent（LLM ↔ Tools）通过 backend protocol 与沙箱通信；沙箱内部提供文件系统（Filesystem）、Shell（Bash）和依赖管理（Dependencies）服务。这一协议是沙箱后端与 Agent 之间的标准通信接口。
import { createDeepAgent } from "deepagents";
import { DenoSandbox } from "@langchain/deno";
import { ChatAnthropic } from "@langchain/anthropic";
// 创建并初始化沙箱容器
const sandbox = await DenoSandbox.create({
memoryMb: 1024, // 分配 1GB 内存
lifetime: "10m", // 容器最大存活时间 10 分钟
});
try {
const agent = createDeepAgent({
model: new ChatAnthropic({ model: "claude-opus-4-6" }),
systemPrompt: "You are a JavaScript coding assistant.",
backend: sandbox, // 沙箱作为后端，Agent 可使用 execute + 文件系统工具
});
const result = await agent.invoke({
messages: [{ role: "user", content: "Create a HTTP server and test it" }],
});
} finally {
await sandbox.close(); // 必须关闭！否则持续计费
}
常见误区：沙箱后端会持续消耗资源并产生费用。必须在不再需要时调用
sandbox.close()，否则会一直计费。推荐使用 try/finally 确保清理。
使用 Deep Agents Code？Deep Agents Code 通过
--sandbox 标志内置了沙箱支持。有关具体设置、标志（--sandbox-id、--sandbox-setup）和示例，请参阅使用远程沙箱。
集成模式
两种架构模式——Agent 在沙箱内运行，或沙箱作为远程工具
Agent 在沙箱内运行
Agent 本身部署在沙箱容器里，你通过网络与其通信。
- 与本地开发体验高度一致
- Agent 与环境紧密耦合
权衡：
- API 密钥必须存在于沙箱内（安全风险）
- 更新代码需要重新构建镜像
- 需要额外的通信基础设施
FROM python:3.11
RUN pip install deepagents-code沙箱作为工具
Agent 在你的机器上运行，需要执行代码时调用沙箱工具。
- 无需重建镜像即可更新 Agent 代码
- API 密钥保留在沙箱外部
- 可跨多个沙箱并行运行任务
权衡：
- 每次执行调用有网络延迟
// 沙箱作为工具模式（本文档推荐）
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
const sandbox = await DaytonaSandbox.create(); // 创建新的沙箱容器
const agent = createDeepAgent({
backend: sandbox, // 沙箱作为后端，Agent 可执行任意 Shell 命令
systemPrompt: "You are a coding assistant with sandbox access.",
});
try {
const result = await agent.invoke({
messages: [
{ role: "user", content: "Create a hello world Python script and run it" },
],
});
} catch (err) {
await sandbox.close(); // 异常时主动清理，避免资源泄漏
throw err;
}
如何选择：需要快速迭代 Agent 逻辑、把密钥留在沙箱外——选"沙箱作为工具"。需要生产环境与本地开发一致——选"Agent 在沙箱内运行"。本文档所有示例使用"沙箱作为工具"模式。
工作原理
沙箱后端只需实现一个 execute() 方法——其他文件操作都构建在它之上
架构极其简洁：提供商唯一需要实现的方法是 execute()，它运行一条 Shell 命令并返回输出。所有文件系统操作（read、write、edit、ls、glob、grep）都由 BaseSandbox 基类通过构造脚本调用 execute() 实现。
架构示意（execute 方法体系）：Agent 工具（ls、read_file 等）和 execute 工具暴露给 Agent 调用；BaseSandbox 基类通过 execute() 方法实现所有文件系统操作；Provider SDK 位于最底层，负责实际执行 Shell 命令。这意味着：添加新提供商只需实现 execute() 方法；execute 工具按条件可用——不实现 SandboxBackendProtocol 的后端不会暴露 execute 工具。
| 层面 | 方法 | 谁调用 | 用途 |
|---|---|---|---|
| Agent 工具 | ls、read_file、write_file 等 |
LLM 在执行期间调用 | 读取代码、写入文件、搜索内容 |
| execute 工具 | execute |
LLM 在执行期间调用 | 运行 Shell 命令 |
| 底层方法 | execute() |
BaseSandbox 基类 | 所有工具的底层执行 |
| 文件传输 | uploadFiles() / downloadFiles() |
你的应用代码 | 宿主机与沙箱之间移动文件 |
// execute() 的返回格式
// 成功：
// "4\n[Command succeeded with exit code 0]"
// 失败：
// "bash: foobar: command not found\n[Command failed with exit code 127]"
// 输出过大时自动截断，Agent 会被指示用 read_file 增量读取添加新提供商很简单
只需实现 execute() 方法。基类 BaseSandbox 会自动提供所有文件系统工具的实现。
execute 工具按条件可用
每次模型调用时，harness 会检查后端是否实现了 SandboxBackendProtocol。如果没有，execute 工具会被过滤掉，Agent 永远看不到它。
