Agent 系列（九）：E2B 核心概念和架构解析

上一篇我简要介绍了 E2B 的一些背景及其作用，本文重点来拆解 E2B 中的一些概念和流程；笔者最近在实现 E2B 的 JAVA SDK ，会将学习过程及开发过程中的一些问题记录在本系列。

E2B 的核心抽象是 Sandbox，它是一个可通过 SDK/API 管理的隔离执行实例，用于运行 AI-generated code、处理文件、执行命令、访问受控网络资源，并把执行结果返回给上层 Agent Runtime。

在 AI Agent 架构中，E2B 位于 Agent Runtime 和底层计算资源之间；上层 Agent Runtime 负责规划任务、选择工具、组织上下文和处理用户交互；E2B 负责提供可创建、可连接、可暂停、可恢复、可销毁的沙箱执行环境；底层资源包括计算节点、隔离运行时、镜像或模板资源、文件存储、日志存储、网络策略和调度系统。

E2B 核心概念

官方文档对 E2B 的描述是：它提供隔离沙箱，让 Agent 可以安全执行代码、处理数据和运行工具，并通过 SDK 管理这些环境；下面先通过一张图来看下 E2B SandBox 的相关核心概念：

Sandbox

Sandbox 是 E2B 的运行时实例。一次 Agent 任务如果需要执行代码、运行命令、读写文件或启动进程，就需要一个执行现场。Sandbox 承担这个执行现场的角色。

一个 Sandbox 通常包含独立的文件系统、进程空间、环境变量、网络访问规则、执行日志和运行状态。上层应用通过 SDK/API 创建 Sandbox，然后向其中写入文件、执行命令、获取输出、读取结果文件，最后根据任务状态选择暂停、快照、继续运行或销毁实例。

Sandbox 的工程意义在于把不可信执行逻辑放进可管理边界内。模型生成的代码、用户提交的代码、临时脚本、自动化命令都可以进入 Sandbox 执行。宿主系统只暴露受控接口，不直接把真实服务器环境交给模型生成代码使用。

在 E2B 的对象模型中，Sandbox 有自己的身份标识，例如 sandboxID；也有来源模板，例如 templateID；还会携带启动时间、结束时间、CPU、内存、磁盘、元数据、挂载卷等运行信息。这些字段说明 Sandbox 不是一次函数调用，而是一个具备生命周期和资源属性的运行对象。

Template 与 Tags

Template 定义 Sandbox 启动时使用的基础环境，它和 Sandbox 的关系接近 Docker Image 与 Container 的关系：Template 描述环境，Sandbox 是从环境启动出来的运行实例。

Agent 任务对运行环境有明确依赖；数据分析任务需要 Python 生态和数据处理库；代码类任务需要 Git、包管理器、编译工具和测试框架；浏览器任务需要浏览器运行时；前端生成任务需要 Node.js 和构建工具；把这些依赖固化在 Template 中，可以减少每次任务启动后的环境准备成本。

Tags 用于管理 Template 版本，它的作用接近 Docker 镜像标签，例如 data-analysis:v1、code-runner:latest。版本管理对生产系统很重要，Agent 执行结果需要可复现，环境升级需要可回滚，不同业务或租户可能绑定不同模板版本。Tags 让 Template 从一次性环境配置变成可治理的运行时资产。

E2B API 中围绕 Template 提供了 创建、更新、删除、查询、构建、查看构建状态、获取构建日志 等能力。围绕 Tags 提供 分配、删除和列出标签 的能力。这些接口构成沙箱环境管理的控制面。

Filesystem、Command 与 Process：任务执行的三个基本接口

Sandbox 执行任务时，最常用的三类能力是 文件、命令和进程。

Filesystem 负责沙箱内部文件空间。Agent Runtime 可以把用户上传的数据、项目文件、上下文材料写入沙箱，也可以从沙箱下载执行结果、图表、报告、补丁文件或日志文件。E2B 的文件能力包括目录创建、目录列举、文件上传、文件下载、移动、删除、状态查询和目录监听。目录监听用于捕捉文件系统变化，适合处理长任务或需要实时观察产物生成的场景。

Command 负责命令执行。官方文档中 Commands 是独立能力，支持运行命令、流式输出、后台命令等。对于 Agent 来说，命令执行是把计划转换成动作的直接路径。模型可以生成一段脚本或命令，上层系统先做权限和参数检查，然后交给 Sandbox 运行，并把 stdout、stderr、退出状态和产物文件返回给 Agent Runtime。

Process 是更底层的执行控制接口。你提供的资料中列出了启动进程、列出进程、连接进程、发送输入、关闭 stdin、发送信号等接口。Command 更面向“运行一个动作”，Process 更面向“控制运行中的进程”。当任务需要交互式终端、长时间运行服务、流式日志、发送输入或终止失控进程时，Process 这层能力就会出现。

这三类接口共同构成一次沙箱执行链路：先通过 Filesystem 准备输入，再通过 Command/Process 执行动作，最后通过 Filesystem 和日志接口收集输出。

Lifecycle、Persistence 与 Snapshot

Sandbox 是有生命周期的运行实例，E2B API 提供 创建、连接、删除、暂停、恢复、设置超时、刷新超时 等操作；生命周期管理解决两个问题：资源回收和长任务保持。短任务可以创建后立即执行，完成后销毁。长任务可能需要等待用户确认、保留中间文件、继续运行后台进程，或者在后续请求中恢复上下文。Pause Sandbox、Connect to Sandbox、Refresh Sandbox、Set Sandbox Timeout 这些接口用于控制运行时长和可连接状态，详见：https://e2b.dev/docs/api-reference/sandboxes/。

Persistence 和 Snapshot 处理更长期的状态保存。Snapshot 可以把某个 Sandbox 的当前状态保存下来，再基于这个状态创建新的 Sandbox；从执行系统角度看，Snapshot 解决的是环境复用、任务恢复和状态复制问题；一个任务如果已经安装依赖、拉取代码、生成中间文件，直接从快照恢复会比重新构建环境更有效。

Volume 提供另一类持久化数据管理方式；官方文档把 Volumes 作为独立章节，包含卷管理、挂载、读写、上传下载和卷间迁移。Snapshot 更偏运行状态保存，Volume 更偏跨 Sandbox 或跨任务的数据持久化；两者共同让 Sandbox 能承载多步任务，而不是只运行一次临时代码。

Network、Secured Access 与 MCP Gateway：外部能力接入边界

Sandbox 需要网络能力，但网络能力必须受控。E2B 文档中有 Internet Access、Sandbox Public URL、Restricting Public Access、Proxy Tunneling、Custom Domain、Secured Access 等网络相关能力；它们解决的是沙箱如何访问外部资源，以及外部如何访问沙箱内服务的问题。

对 Agent 任务来说，网络访问常见于下载依赖、访问 API、抓取网页、调用外部工具、启动临时 Web 服务等场景；网络策略需要能表达允许访问、限制访问、暴露端口、代理转发和访问控制；没有网络边界，沙箱执行层会把不可信代码和外部系统直接连通，风险会进入业务网络和数据系统。

MCP Gateway 是另一类外部能力接入方式。官方文档中 MCP Gateway 包含可用服务器、自定义模板、自定义服务器和相关示例。MCP 的作用是把工具、资源和上下文服务以协议方式暴露给模型或 Agent 系统。E2B 侧提供 MCP Gateway，意味着沙箱执行环境可以承载或连接 MCP Server，让 Agent 在隔离环境中调用工具。

这里的关系可以这样理解：Network 控制网络层访问，Secured Access 控制访问安全，MCP Gateway 把工具接入变成标准化协议接口。它们共同决定 Sandbox 如何与外部系统交互。

E2B 架构分层

从系统实现角度看，E2B 可以按五层理解。

接入层包括 Python SDK、TypeScript SDK、REST API 和 CLI。这一层面向开发者和上层 Agent Runtime，提供创建沙箱、执行命令、读写文件、管理模板、查询日志和指标等接口。应用不直接操作底层节点，而是通过这一层提交控制请求。

控制层负责认证、配额、Sandbox 管理、Template 管理、调度路由、网络策略、元数据、审计日志和生命周期控制。Team 是控制层里的资源隔离边界；API Key、模板、运行中的沙箱、额度、并发限制和账单都可以归到 Team 维度(相当于租户)。

执行层是 Sandbox Runtime 集群。这里运行多个 Sandbox 实例，承载命令执行、进程管理、文件操作、网络访问和内部代理服务。你提供的资料中提到 Envd，它运行在 Sandbox 实例中，用于外部系统和沙箱实例通信，提供健康检查、状态指标和环境变量等能力。

状态层包括持久化状态、Snapshot、Volume、文件存储、日志存储和元数据。任务执行不只产生 stdout，还会产生文件、缓存、构建产物、运行日志、快照和指标。状态层决定沙箱任务能否恢复、复现、迁移和排查。

基础设施层包括计算节点、隔离运行时、存储系统、网络系统、镜像仓库、模板资源和调度组件。这里涉及底层技术，例如虚拟机、MicroVM、容器、文件系统快照、网络隔离、资源限制和镜像构建。不同实现方案可以选择不同隔离技术。你提供的资料把 E2B 描述为基于 Firecracker 的 MicroVM，Modal 则被描述为使用 gVisor。这些属于沙箱执行层的底层隔离路径。

一条完整任务链路

Agent Runtime 收到任务后，先根据任务类型选择 Template。如果是数据分析任务，可以选择包含 Python 数据分析依赖的模板；如果是代码任务，可以选择包含 Git、编译器和测试工具的模板。随后通过 SDK/API 创建 Sandbox，得到 sandboxID。

创建完成后，Agent Runtime 通过 Filesystem 把输入文件、上下文材料或项目代码写入沙箱。接着通过 Command 执行脚本或命令。命令执行过程中，系统可以流式读取输出，也可以通过 Process 连接运行中的进程、发送输入或发送终止信号。

如果任务需要访问外部资源，Sandbox 通过受控 Network 规则访问互联网、API 或内部服务。如果任务需要标准化工具能力，可以通过 MCP Gateway 接入工具。执行完成后，Agent Runtime 读取生成文件、日志和指标，将结果回传给上层。

如果任务需要保留状态，可以使用 Persistence、Snapshot 或 Volume 保存现场。任务结束时，通过 Lifecycle 策略选择暂停、刷新超时、继续等待、创建快照或销毁 Sandbox。

这条链路把 Sandbox、Template、Filesystem、Command、Network、MCP Gateway、Persistence、Snapshot、Volume 和 Lifecycle 放在同一个执行模型里。E2B 的系统位置也由此明确：它把隔离运行时、文件系统、命令执行、网络访问、状态保存和工具接入封装成面向 Agent Runtime 的沙箱执行层。

8、参考资料

E2B 官方文档 E2B API Reference：Sandboxes