Appearance
Sandboxes 与隔离执行
当 Agent 可以执行 shell、安装依赖或运行用户代码时，filesystem 权限已经不够。Sandbox 的目标是 把任意代码执行限制在可销毁环境中，保护宿主文件、凭据和网络边界。
Sandbox 只能降低爆炸半径，不能让不可信代码变成可信代码。允许外网或注入密钥的 sandbox 仍可能发生数据外传。
SandboxBackend 带来什么
具备 sandbox 接口的 backend 除文件工具外，还能向 Agent 暴露 execute。命令结果通常包含 stdout、stderr 与 exit code；过长输出可以写入文件，再让 Agent 用 read_file 分段查看。
前端类比
可以把 remote sandbox 类比为短生命周期的隔离构建容器，而不是浏览器 iframe。iframe 主要隔离 页面能力；Deep Agents sandbox 必须同时治理进程、文件系统、网络、资源配额与凭据。
Deep Agents 原生语义：sandbox 是 filesystem backend 的执行扩展。Deep Agents 负责把 execute 提供给模型并接收结果；真正的隔离强度由 provider、容器或虚拟机策略决定。
Remote sandbox 的生命周期
下面展示官方 LangSmith Sandbox 集成的基本形状。它会创建外部资源，因此必须放在 finally 中 回收；本仓库不会执行该示例。
python
import os
from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langsmith.sandbox import SandboxClient
client = SandboxClient()
sandbox = client.create_sandbox()
try:
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
backend=LangSmithSandbox(sandbox=sandbox),
system_prompt="只在 sandbox 中创建文件和执行验证命令。",
)
# result = agent.invoke(...)
finally:
client.delete_sandbox(sandbox.name)不同 provider 的创建、认证、停止和销毁方法不同。选择 provider 前至少核对：
- 是容器、microVM 还是远程开发环境。
- 默认是否允许公网、DNS 与内网访问。
- 密钥如何代理，是否会进入环境变量或文件系统。
- CPU、内存、磁盘、进程数、命令时长和总生命周期限制。
- 销毁后 artifact 与日志的保留政策。
LocalShellBackend 不是 sandbox
Python 提供 LocalShellBackend 便于可信本地调试：
python
from deepagents.backends import LocalShellBackend
backend = LocalShellBackend()
result = backend.execute("python --version")
print(result.output)这段代码直接在宿主运行命令。它不应接收不可信网页、用户 prompt、仓库 issue 或外部文件作为 指令来源，也不应在含生产凭据的进程中使用。
最小安全边界
| 边界 | 最低要求 |
|---|---|
| 文件 | 独立临时卷、只挂载所需输入、输出单独导出 |
| 网络 | 默认关闭；需要时只开放明确域名与端口 |
| 凭据 | 不放进 sandbox；通过外部受限工具或代理代办 |
| 资源 | CPU、内存、磁盘、进程、输出和执行时间上限 |
| 生命周期 | 每任务创建、可靠销毁、超时自动回收 |
| 审计 | 记录命令、exit code、artifact 与调用 thread |
| 输入输出 | 把 sandbox 输出继续视为不可信数据 |
Permissions 与 HITL 的关系
Deep Agents permissions 当前只约束内置 filesystem 工具，不自动覆盖 execute。HITL 可以在 模型产生普通工具调用时暂停审批，但审批不是隔离层：
- 审批人可能看不懂混淆命令。
- 一个已批准命令可以下载并执行后续内容。
- interpreter 内的程序化调用不一定经过相同的 tool-call 路径。
因此顺序应是先建立 sandbox 和网络边界，再按风险增加 permissions 与 HITL。
Python 与 TypeScript
两个 SDK 都能连接官方支持的 sandbox integrations，但 provider 包、构造器和生命周期方法并不 完全相同。TypeScript 还需要区分 server/Node 入口与 browser 入口；远程 sandbox 凭据和 Node-only 客户端不应被打进浏览器 bundle。