Agent 连接沙箱的两种架构模式：放在沙箱内，还是把沙箱当工具

标题：Agent 连接沙箱的两种模式

摘要：感谢来自 Witan Labs 的 Nuno Campos、来自 E2B 的 Tomas Beran 与 Mikayel Harutyunyan、来自 Runloop 的 Jonathan Wall，以及来自 Zo Computer 的 Ben Guo 的审阅与反馈。

TL;DR：

越来越多 Agent 需要一个工作空间：一台可以运行代码、安装包并访问文件的“电脑”。沙箱正是为此提供能力。
Agent 与沙箱集成主要有两种架构模式：
- 模式 1（Agent IN Sandbox）：Agent 运行在沙箱内部，你通过网络与它通信。

正文： 感谢来自 Witan Labs 的 Nuno Campos、来自 E2B 的 Tomas Beran 与 Mikayel Harutyunyan、来自 Runloop 的 Jonathan Wall，以及来自 Zo Computer 的 Ben Guo 的审阅与反馈。

TL;DR：

越来越多 Agent 需要一个工作空间：一台可以运行代码、安装包并访问文件的“电脑”。沙箱提供了这种能力。
Agent 与沙箱集成有两种架构模式：
- 模式 1（Agent IN Sandbox）：Agent 运行在沙箱内部，你通过网络与其通信。优势：与本地开发高度一致，Agent 与环境紧耦合。
- 模式 2（Sandbox as Tool）：Agent 运行在本地/你的服务器上，通过远程调用沙箱执行。优势：便于更新 Agent 逻辑、API key 不进入沙箱、关注点分离更清晰。
deepagents 通过简单配置同时支持这两种模式。

越来越多 Agent 需要一个工作空间——也就是一台能运行代码、安装依赖并访问文件的计算机。这个工作空间必须是隔离的，确保 Agent 无法直接接触你的凭据、文件或网络。沙箱通过在 Agent 环境与宿主系统之间建立边界来实现这种隔离。对于构建这类 Agent 的团队来说，问题已经不是“要不要用沙箱”，而是“如何把沙箱集成进 Agent 架构”。

常见做法主要有两类，取决于 Agent 运行在沙箱内还是沙箱外。两种模式各有优劣与取舍。

说明：本文聚焦于给 Agent 提供完整“电脑”能力的沙箱——例如 Docker 容器或 VM 这类完整执行环境。不讨论进程级沙箱（如 bubblewrap）或语言级沙箱（如 Pyodide）。

模式 1：Agent 运行在沙箱内（IN Sandbox）

在这种模式下，Agent 运行在沙箱内部，你通过网络和它通信。

实际落地通常是这样：

你先构建一个预装 Agent 框架的 Docker 或 VM 镜像，在沙箱内运行它，然后从外部连接并发送消息。Agent 会暴露一个 API 端点（通常是 HTTP 或 WebSocket），你的应用跨越沙箱边界与其交互。

优势：

这种模式与本地开发非常接近——如果你在本地终端如何运行 deepagents，在沙箱里基本就怎么运行。Agent 拥有直接文件系统访问能力，也能修改自身环境。当 Agent 与执行环境高度耦合时，这尤其有用，比如 Agent 需要与特定库深度交互，或维护复杂环境状态。

权衡：

跨沙箱边界通信需要额外基础设施。有些厂商会在 SDK 层处理好——例如 OpenCode 这类 Agent 会在沙箱内跑一个服务，而 E2B 这类厂商可将其通过整洁 API 暴露出来。如果你的提供方不支持这一层，你就需要自己搭 WebSocket 或 HTTP 通信层，包括会话管理与错误处理。

为了让 Agent 发起推理调用，API key 往往必须放进沙箱里。一旦沙箱被攻破（无论是隔离技术漏洞，还是通过 prompt injection 窃取凭据），就会带来潜在安全风险。说明：我们看到 E2B、Runloop 等提供方正在推进 secret vault 能力，这能缓解该问题。

此外，更新通常需要重建容器镜像并重新部署，这会拉长开发迭代周期。

另一个缺点是：沙箱必须先恢复（resume）后 Agent 才能激活，往往需要额外逻辑来处理。

对担心 Agent IP 保护的人来说，如果 Agent 跑在沙箱内，整个 Agent 代码与 prompts 更容易被整体外流。

Witan Labs 的 Nuno Campos 还指出了另一类安全风险：“我认为 Agent in sandbox 的另一个缺点是：你的 Agent 的任何部分实际上都很难拥有比 bash 工具更高的权限。比如你想做一个既有 bash 工具、又有 web search/web fetch 工具的 Agent，那么所有 LLM 生成代码都可能进行无限制 web fetch（这是很大的安全风险）。而如果采用 sandbox as tool，你可以很容易做到：某些工具权限高于你授予 LLM 生成代码的权限。这样安全边界围绕的是 bash 工具，而不是整个 Agent（对很多 Agent 来说非常有价值）。”

模式 2：把沙箱当工具（Sandbox as Tool）

在这种模式下，Agent 运行在你的机器或服务器上；当需要执行代码时，再通过 API 调用远程沙箱。

实际落地通常是这样：

你的 Agent 在本地（或服务器）运行，当它生成需要执行的代码时，就调用沙箱提供方的 API（如 E2B、Modal、Daytona、Runloop）。通信细节由提供方 SDK 处理。对 Agent 而言，沙箱只是另一个工具。

优势：

你可以即时更新 Agent 代码，无需重建容器镜像，开发迭代更快。API key 保持在沙箱之外，进入隔离环境的只有执行过程。这样还能实现更清晰的关注点分离：Agent 状态（对话历史、推理链、记忆）保留在 Agent 运行侧，与沙箱解耦。这意味着沙箱故障不会丢失 Agent 状态，而且你可以切换沙箱后端而不影响 Agent 核心逻辑。

E2B 的 Tomas Beran 还补充了两个优势：

支持在多个远程沙箱中并行执行任务
仅在执行代码时为沙箱付费，而不是为整个进程运行时持续付费

Ben Guo 也补充了将 Agent runtime 与 sandbox runtime 分离的价值：“我们选择模式 2，除了你提到的原因，也是为了面向未来：当把 agent harness 放在 GPU 机器上更合理时，我们已经准备好了——整体来看，持久化沙箱与推理 harness 的环境需求大概率会持续分化。”

权衡：

主要缺点是网络延迟。每次执行调用都要跨越网络边界。对于包含大量小粒度执行的负载，延迟会不断累积。

许多沙箱提供方提供有状态会话：在同一会话内，变量、文件和已安装依赖可跨调用持久化。这能在一定程度上缓解延迟问题，减少来回往返次数。

如何在两种模式间做选择

以下场景更适合模式 1：

Agent 与执行环境高度耦合（例如需要持续访问特定库或复杂环境状态）
你希望生产环境尽量贴近本地开发体验
你的提供方 SDK 已帮你处理好通信层

以下场景更适合模式 2：

你需要在开发期快速迭代 Agent 逻辑
你希望 API key 留在沙箱外
你更看重 Agent 状态与执行环境之间的清晰分层

实现示例

为了让这两种模式更具体，下面用 deepagents 举例。它是一个内置沙箱支持的开源 Agent 框架。其他 Agent 框架同样适用类似模式。

模式 1：Agent IN Sandbox

模式 1 下，先构建一个预装 Agent 的镜像：

code

FROM python:3.11
RUN pip install deepagents-cli

然后在沙箱中运行。完整实现还需要额外基础设施来打通你的应用与沙箱内 Agent 的通信（WebSocket 或 HTTP 服务、会话管理、错误处理）。这超出本文范围，后续我们会发文深入展开。

模式 2：Sandbox as Tool

code

from daytona import Daytona
from langchain_anthropic import ChatAnthropic

from deepagents import create_deep_agent
from langchain_daytona import DaytonaSandbox

# Can also do this with E2B, Runloop, Modal
sandbox = Daytona().create()
backend = DaytonaSandbox(sandbox=sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-20250514"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Run a small python script",
            }
        ]
    }
)

sandbox.stop()

这段代码运行时，大致流程如下：

Agent 在你的本地机器上进行规划
生成用于解决问题的 Python 代码
调用 Runloop API，在远程沙箱中执行代码
沙箱返回执行结果
Agent 读取输出并在本地继续推理

结语

出于安全考虑，Agent 需要在隔离环境中执行代码。主流架构有两种：让 Agent 在沙箱内运行（更贴近本地开发、环境强耦合），或让 Agent 在外部运行并把沙箱当工具调用（更新更快、API key 更安全）。应根据你的实际需求在收益与代价之间做选择。

deepagents 通过简单配置同时支持两种模式。可以试用一下，看看哪种模式最适合你的业务场景。