第 28 章

Code：远程沙箱

在 LangSmith、Daytona、Modal、Runloop、AgentCore、Vercel 或 E2B 沙箱中安全运行 Deep Agents Code 的工具执行

让 Agent 的代码操作运行在隔离的远程环境中，而不是你的本机

为什么需要它

你已经知道沙箱很重要——但每次都要自己搭建容器，是不是太麻烦了？

自己管理沙箱的痛点

  • 要自己搭建 Docker 容器、管理生命周期——运维负担重
  • 每次运行都要创建/销毁环境，耗时且易出错
  • 文件怎么放进沙箱？怎么拿出来？没有标准流程
  • 多台机器并行跑？资源调度靠自己
  • 凭据管理混乱，安全隐患多

远程沙箱的解法

  • 一行命令指定沙箱提供商，零配置创建
  • 工具调用自动路由到远程，透明执行
  • 设置脚本自动化环境初始化，文件一键部署
  • 云端弹性扩缩容，无需操心资源
  • 每个提供商自带凭据管理，安全合规
问题核心：Deep Agents Code 采用"沙箱即工具"（sandbox-as-tool）模式——dcode 进程（LLM 循环、内存、工具调度）在你的本机运行，而 Agent 的工具调用（read_file、write_file、execute 等）指向远程沙箱，而非你的本地文件系统。

架构模式

沙箱即工具（Sandbox-as-Tool）——本机决策，远程执行

本机运行

  • LLM 循环——推理和决策
  • 内存管理——上下文和记忆
  • 工具调度——决定调用哪个工具
  • 事件流——进度和结果推送

远程沙箱运行

  • read_file——读取文件
  • write_file——写入文件
  • execute——执行命令
  • list_files——浏览目录
  • 其他所有文件/Shell 操作

文件传输

  • 使用设置脚本初始化沙箱环境
  • 通过提供商的文件传输 API 操作文件
  • 本地环境变量自动展开到脚本中
  • 密钥存在本地 .env 文件中
# 架构示意：本机与远程沙箱的分工
#
# ┌──────────────────┐          ┌──────────────────┐
# │   你的本机        │   工具   │   远程沙箱        │
# │                  │ ───────→ │                  │
# │  dcode 进程      │  调用    │  文件系统        │
# │  LLM 推理        │          │  Shell 环境      │
# │  状态管理        │ ←─────── │  代码执行        │
# │                  │   结果   │  依赖包          │
# └──────────────────┘          └──────────────────┘
#
关键区别：这不是把整个 Agent 都搬到远程。本机仍然负责"思考"，远程只负责"动手"。这样你既保留了本地调试的便利，又获得了远程执行的隔离安全。

"大脑"和"手脚"的比喻只是为了帮助你理解分工。实际上计算机的运作方式是：dcode 进程在本机运行 LLM 推理和工具调度逻辑，而文件读写、Shell 执行等具体操作通过 API 调用发送到远程沙箱执行，结果再返回给本机处理。

图：沙箱即工具架构模式

七大提供商

Deep Agents Code 支持七种远程沙箱提供商——按需选择

LangSmith

LangChain 官方托管沙箱。

  • 安装时默认包含，零额外依赖
  • 与 LangSmith 可观测性深度集成
  • 适合快速原型和测试

默认包含

Daytona

开源开发环境平台。

  • 自托管或云托管均可
  • 完整 IDE 级别的开发环境
  • 适合需要自定义环境的团队

langchain-daytona

Modal

Serverless 云计算平台。

  • 弹性扩缩容，按需付费
  • GPU 支持和并行执行
  • 适合计算密集型任务

langchain-modal

Runloop

专为 AI Agent 设计的沙箱。

  • 快速启动，毫秒级创建
  • 内建代码执行优化
  • 适合高频工具调用场景

langchain-runloop

AgentCore

AWS 托管的代码解释器。

  • 原生 AWS 集成
  • 企业级安全和合规
  • 适合 AWS 生态用户

langchain-agentcore

Vercel

Vercel 托管的远程沙箱。

  • 与 Vercel 平台原生集成
  • 云端弹性环境
  • 适合前端与全栈工作流

--sandbox vercel

E2B

开源的代码沙箱平台。

  • 专为 AI Agent 设计的隔离环境
  • 快速启动、按需创建
  • 第三方包通过 dcode --install 安装

--sandbox e2b

安装依赖

第一步：安装对应提供商的扩展依赖

根据你选择的沙箱提供商，安装对应的扩展包。官方推荐两种方式：会话内用 /install（或命令行 dcode --install），或用 extras 语法一次性装好。LangSmith 默认包含，无需额外安装。

# LangSmith —— 默认包含，无需额外安装
uv tool install deepagents-code

# Daytona —— 推荐方式
dcode --install daytona            # 命令行（或会话内输入 /install daytona）
# 或使用 extras 语法
uv tool install 'deepagents-code[daytona]'

# Modal
dcode --install modal              # 或 /install modal
uv tool install 'deepagents-code[modal]'

# Runloop
dcode --install runloop            # 或 /install runloop
uv tool install 'deepagents-code[runloop]'

# AgentCore
dcode --install agentcore          # 或 /install agentcore
uv tool install 'deepagents-code[agentcore]'

# Vercel
dcode --install vercel             # 或 /install vercel
uv tool install 'deepagents-code[vercel]'

# E2B —— 第三方包通过 --package 安装
dcode --install e2b --package      # 或 /install e2b
uv tool install 'deepagents-code[e2b]'

选择提供商的考虑因素

  • 快速试用？→ LangSmith，零配置
  • 自建环境？→ Daytona，完全可控
  • 计算密集？→ Modal，GPU + 并行
  • 高频调用？→ Runloop，毫秒启动
  • AWS 生态？→ AgentCore，原生集成
  • Vercel 平台？→ Vercel，原生集成
  • 开源沙箱？→ E2B，专为 AI 设计

注意

  • 可以同时安装多个提供商扩展
  • 运行时通过 --sandbox 标志选择使用哪个
  • 如果没安装对应扩展就指定了提供商，会报错提示
  • 建议先用 LangSmith 体验，确定需求后再切换

配置凭证

第二步：设置提供商所需的 API 密钥或认证信息

每个提供商的认证方式不同。设置对应的环境变量即可。

LangSmith

export LANGSMITH_API_KEY="your-key"

Daytona

export DAYTONA_API_KEY="your-key"

Modal

modal setup

Modal 使用交互式认证，运行 modal setup 按提示操作。

Runloop

export RUNLOOP_API_KEY="your-key"

Vercel

export VERCEL_TOKEN="your-token"
export VERCEL_PROJECT_ID="your-project-id"
export VERCEL_TEAM_ID="your-team-id"

E2B

export E2B_API_KEY="your-key"

AgentCore（需要三个必需环境变量）

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_REGION="us-west-2"

# 可选：仅在使用临时凭证时设置
# export AWS_SESSION_TOKEN="session-token"

AgentCore 使用 AWS 标准认证，必需三个环境变量；AWS_SESSION_TOKEN 仅在使用临时（STS）凭证时才需要设置。

最佳实践：将密钥存储在本地 .env 文件中，不要直接写在 shell 配置里。设置脚本也会通过本地环境变量展开 ${VAR} 引用来访问这些密钥。

启动沙箱

第三步：用 --sandbox 标志指定提供商，一行命令启动

安装好依赖、配置好凭证后，用 --sandbox 指定沙箱类型即可。

# 使用 LangSmith 沙箱
dcode --sandbox langsmith

# 使用 Daytona 沙箱
dcode --sandbox daytona

# 使用 Modal 沙箱
dcode --sandbox modal

# 使用 Runloop 沙箱
dcode --sandbox runloop

# 使用 AgentCore 沙箱
dcode --sandbox agentcore

# 使用 Vercel 沙箱
dcode --sandbox vercel

# 使用 E2B 沙箱
dcode --sandbox e2b

启动后发生了什么

  1. dcode 在本机启动 LLM 循环
  2. 连接到指定提供商创建一个新沙箱实例
  3. 如果有设置脚本，在沙箱内执行初始化
  4. Agent 的所有工具调用路由到远程沙箱
  5. 会话结束后沙箱自动清理（除非指定复用）

默认行为

  • 不指定 --sandbox → 工具调用指向本地文件系统
  • 指定 --sandbox → 自动创建全新沙箱
  • 指定 --sandbox-id → 复用已有沙箱
  • 沙箱创建/销毁由提供商自动管理
体验是无缝的：从使用者的角度看，Agent 的行为完全一样——只是代码不再在你本机执行，而是在一个隔离的远程环境中运行。
图：沙箱启动五步时序

标志一览

三个沙箱相关标志——覆盖创建、复用和初始化场景

标志描述示例
--sandbox TYPE 指定沙箱提供商：langsmith、daytona、modal、runloop、agentcore、vercel 或 e2b（默认：none） dcode --sandbox daytona
--sandbox-id ID 通过 ID 复用现有沙箱，而非创建新沙箱。跳过创建和清理步骤 dcode --sandbox runloop --sandbox-id dbx_abc123
--sandbox-setup PATH 沙箱创建后要在其内部运行的设置脚本路径 dcode --sandbox modal --sandbox-setup ./setup.sh

创建新沙箱

每次运行创建一个全新的沙箱环境，会话结束后自动销毁。

# 创建全新沙箱——每次运行独立隔离
dcode --sandbox daytona

复用已有沙箱

跳过创建和清理步骤，直接在已有沙箱中继续工作。适合调试或跨会话保持状态。

# 通过 ID 复用已有沙箱——保持之前的文件和状态
dcode --sandbox runloop --sandbox-id dbx_abc123

带初始化启动

创建沙箱后立即执行设置脚本，完成环境初始化。

# 创建沙箱后立即运行 setup 脚本进行环境初始化
dcode --sandbox modal --sandbox-setup ./setup.sh

设置脚本

用 --sandbox-setup 在沙箱创建后自动完成环境初始化

设置脚本是一个 shell 脚本，在沙箱创建后在其内部运行。常用于克隆仓库、安装依赖和配置环境变量。

#!/bin/bash
set -e  # 遇到错误立即停止，避免后续命令在异常状态下执行

# 使用 GitHub token 克隆仓库（${GITHUB_TOKEN} 由本地环境变量展开）
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# 将环境变量写入 .bashrc 使其在后续 Shell 会话中持久化
# 注意：heredoc 用 'EOF'（加引号）防止此处展开 ${}，保留原始引用
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc  # 立即加载，使变量在当前会话中生效

脚本做了什么

  1. 使用 GitHub Token 克隆目标仓库
  2. 进入工作目录
  3. 将环境变量写入 .bashrc 使其持久化
  4. source ~/.bashrc 使变量立即生效

变量展开机制

  • Deep Agents Code 使用你的本地环境变量来展开脚本中的 ${VAR} 引用
  • 密钥应存储在本地 .env 文件中
  • 脚本中引用的变量必须在本地环境中有定义
  • 展开发生在发送到沙箱之前
常见问题：
  • ${VAR} 没被展开？→ 检查本地环境变量是否存在：echo $GITHUB_TOKEN
  • 脚本执行失败？→ 在脚本开头加 set -e 让它在第一个错误处停止
  • 变量不持久？→ 写入 ~/.bashrc 并 source，否则只在当前 shell 会话生效

实战组合

三种常见的沙箱使用场景——从简单到高级

场景一：快速试用

只想快速体验远程沙箱，不需要复杂环境。

# 一行命令启用 LangSmith 沙箱——默认包含，无需额外安装
dcode --sandbox langsmith
  • 适合：探索性测试、教学演示
  • 优点：无需安装额外依赖
  • 缺点：环境是空的，无项目文件

场景二：项目开发

需要让 Agent 在你的项目代码中工作。

# 带设置脚本启动——沙箱创建后自动执行 ./setup.sh 完成环境初始化
dcode --sandbox daytona \
  --sandbox-setup ./setup.sh
  • 适合：日常开发、代码审查
  • 优点：沙箱自动克隆仓库、安装依赖
  • 脚本中可自定义任何初始化逻辑

场景三：持续调试

需要跨多次会话保持沙箱状态。

# 首次运行——创建新沙箱，注意记录输出中的 sandbox-id
dcode --sandbox runloop
# 输出中会显示 sandbox-id（如 dbx_abc123）

# 后续复用同一个沙箱——跳过创建和清理，保持状态连续
dcode --sandbox runloop \
  --sandbox-id dbx_abc123
  • 适合：长时间调试、增量开发
  • 跳过创建和清理，状态持续保留

安全注意

沙箱隔离了执行环境，但不等于绝对安全

核心风险：提示注入

沙箱隔离了代码执行环境，但 Agent 在面对不可信输入时仍然容易受到提示注入（prompt injection）的攻击。一个恶意的用户输入可能诱导 Agent 执行危险操作。

必须做的

  • 使用人在回路（human-in-the-loop）审批高风险操作
  • 使用短期有效的密钥，不要用长期 Token
  • 只使用可信的设置脚本，不要运行来源不明的脚本
  • 定期审查沙箱中的操作日志

绝对不要做的

  • 不要将长期有效的 API Key 硬编码在设置脚本中
  • 不要跳过人工审批直接执行不可信的 Agent 操作
  • 不要在沙箱中存储敏感数据后忘记清理
  • 不要用同一个沙箱处理不同安全级别的任务
安全是分层的：沙箱提供的是执行隔离——防止 Agent 的代码操作影响你的本机。但它不能防止 LLM 被恶意输入诱导。真正的安全需要沙箱 + 人工审批 + 密钥管理 + 审计日志的组合。

本章回顾

远程沙箱让 Deep Agents Code 的工具执行既安全又便捷

你学到了什么

  • 沙箱即工具模式：本机思考，远程执行
  • 七大提供商：LangSmith / Daytona / Modal / Runloop / AgentCore / Vercel / E2B
  • 三步上手：安装依赖 → 配置凭证 → --sandbox 启动
  • 三个关键标志：--sandbox、--sandbox-id、--sandbox-setup
  • 设置脚本的编写和变量展开机制
  • 安全注意事项：沙箱隔离 ≠ 绝对安全

关键命令速查

# 安装（推荐方式：dcode --install 或会话内 /install）
dcode --install daytona
# 或使用 extras 语法
uv tool install 'deepagents-code[daytona]'

# 配置
export DAYTONA_API_KEY="your-key"

# 启动（新建沙箱）
dcode --sandbox daytona

# 启动（复用沙箱）
dcode --sandbox daytona --sandbox-id xxx

# 启动（带初始化）
dcode --sandbox daytona --sandbox-setup ./setup.sh
核心结论：远程沙箱让 Deep Agents Code 的工具调用不再触碰你的本地文件系统。一行 --sandbox 标志，就从"在本机执行"切换到"在隔离环境执行"。选择适合你的提供商，写好设置脚本，就能让 Agent 在安全的环境中自由工作。