在智能体（Agent）工程化实践中，如何平衡执行持久性与资源弹性一直是架构设计的关键命题。Vercel Labs 日前开源的 Open Agents 项目给出了一个清晰的三层架构答案：Web 层负责交互与认证，Agent 层运行在持久的 Workflow 之上，而沙箱层则承担独立的执行环境。这种「Agent 不等于沙箱」的核心理念，为云端智能体的可扩展性设计提供了可复用的工程模式。本文将从沙箱隔离、状态迁移、可扩展架构三个维度，深度解析这一开源模板的技术要点与落地参数。
一、核心架构决策：Agent 与沙箱的解耦
传统智能体方案中，Agent 逻辑与执行环境往往紧耦合 —— 模型调用、工具执行、状态管理全部在同一个运行时进程中完成。这种设计在原型阶段足够高效，但进入生产环境后会面临多重挑战：长时任务无法跨越请求边界、资源占用与请求生命周期绑定、沙箱实现与业务逻辑相互耦合难以独立演进。Vercel Open Agents 将这些问题视为架构层面的根本矛盾，并通过明确的分层设计予以解决。
该项目的三层架构为「Web → Agent Workflow → Sandbox VM」。Web 层处理认证、会话、聊天界面与流式输出；Agent 层以 Vercel Workflow SDK 为基础，运行持久的执行流；沙箱层则是独立的虚拟机环境，包含文件系统、Shell、Git、开发服务器与预览端口。关键在于，Agent 并不运行在沙箱内部 —— 它运行在沙箱之外，通过工具调用（文件读取、编辑、搜索、Shell 命令）与沙箱进行交互。这种「控制平面与执行平面分离」的架构，使 Agent 执行不再绑定到单个请求生命周期，沙箱可以独立休眠与恢复，模型提供商与沙箱实现也能各自独立演进，而虚拟机始终保持为纯粹的执行环境，而非演化为复杂的控制平面。
这一设计选择直接影响工程实践中的两个核心能力：其一，Workflow 可以在多个请求之间持久化执行状态，单次对话中的多个 Agent 轮次可以跨越大量已持久化的工作流步骤完成；其二，活动中的运行可以通过重新连接到现有 Workflow 的流进行恢复，实现真正的断点续传。
二、沙箱隔离机制与资源管理
沙箱是 Open Agents 执行层的核心抽象，项目使用 Vercel Sandbox 作为底层隔离技术。每个沙箱基于基础快照（Base Snapshot）创建，暴露常用开发端口（3000、5173、4321、8000），支持 inactivity 后自动休眠。这种设计解决了两个关键问题：环境一致性与资源成本。快照机制确保每次启动沙箱时都处于预配置的开发环境状态，避免了「配置漂移」导致的偶发问题；同时，无任务时自动休眠的能力显著降低了空闲资源的成本消耗。
在工具层面，沙箱对外暴露的能力包括文件操作（读取、编辑、搜索）、Shell 命令执行、任务调度、技能注册与 Web 访问。Agent 通过调用这些工具完成代码编写、仓库克隆、Branch 操作，最终可选择性地执行自动提交、推送与 PR 创建。这些工具的实现被封装在 packages/sandbox 包中，形成独立的沙箱抽象层。工程落地时需关注几个关键参数：快照基础 ID（可通过 VERCEL_SANDBOX_BASE_SNAPSHOT_ID 环境变量覆盖）、休眠阈值（项目默认在 inactivity 后触发，具体数值需根据实际负载调优）、端口暴露策略（当前固定支持四个端口，对于需要自定义服务的场景需评估扩展方案）。
沙箱隔离还带来了一个隐性收益：安全边界清晰。由于 Agent 运行在沙箱之外且通过工具接口交互，沙箱内部即使被恶意代码攻破，攻击面也严格限定在沙箱内部，无法直接访问宿主机的 Agent 控制流或数据库连接。项目在 GitHub App 集成层面进一步收紧了权限 —— 通过 installation-based 的 repo 访问控制，确保每个沙箱实例仅能操作用户授权的仓库范围。
三、状态迁移与持久化策略
云端智能体的状态管理比本地 Agent 更为复杂，原因在于执行过程可能跨越多个请求、甚至跨越沙箱的生命周期。Open Agents 采用了「Workflow 持久化 + 沙箱快照」的双层状态管理方案。Workflow 层负责 Agent 逻辑的执行状态 —— 每个 Agent 轮次可以跨多个已持久化的工作流步骤继续执行，失败的运行可以通过重新连接到流进行恢复。沙箱层则负责执行环境的状态 —— 基于快照的恢复机制使沙箱可以在休眠后恢复到之前的文件系统状态与进程状态。
这种设计的工程意义在于：Agent 开发者无需关心「任务做到一半网络断开怎么办」的问题。用户的聊天请求启动一个 Workflow Run 而非同步执行 Agent，Workflow 的状态由 Vercel 平台持久化管理。即使客户端断开，只要 Workflow 仍在运行，用户重新连接后即可获取流式输出并继续交互。同时，沙箱的快照机制为环境状态提供了物理级别的恢复能力 —— 无论是开发服务器进程、文件系统修改还是 Git 状态，都可以精确回滚到某个快照点。
在数据库层面，项目使用 PostgreSQL 存储持久化元数据（会话、工作流状态、GitHub 集成信息），可选配置 Redis/KV（通过 REDIS_URL 或 KV_URL 环境变量）用于技能元数据的缓存。当未配置 Redis 时，系统会回退到内存缓存，这对于轻量部署是合理的，但生产环境建议配置外部 KV 以确保多实例场景下的缓存一致性。
四、可扩展架构的工程参数
从可扩展性角度审视，Open Agents 的架构为多层级的扩展需求提供了基础设施。其一是模型可扩展：Agent 逻辑与沙箱实现分离意味着可以在不修改沙箱层的情况下切换底层模型提供商 —— 无论是 OpenAI、Anthropic 还是本地部署的开源模型，只需在 Workflow 层替换工具调用的实现。其二是执行层可扩展：沙箱的快照机制天然支持水平扩展，新增沙箱实例即可提升并行任务容量。其三是工作流可扩展：Vercel Workflow SDK 提供了多步骤编排能力，支持子 Agent、技能的动态注册与调度。
工程落地时，以下参数值得关注。最小运行时依赖明确为 POSTGRES_URL 与 JWE_SECRET，这两个是应用启动与加载服务器状态的硬性要求。若要启用完整的托管应用功能，还需配置 ENCRYPTION_KEY 以及 Vercel OAuth 凭据（NEXT_PUBLIC_VERCEL_APP_CLIENT_ID 与 VERCEL_APP_CLIENT_SECRET）。对于需要 GitHub 集成的场景，则需额外配置 GitHub App 的 Client ID、Client Secret、App ID、私钥与 Webhook Secret。生产部署建议使用 Neon 提供 PostgreSQL 托管实例，Upstash 提供 KV 缓存，两者在 Vercel 生态中均有开箱即用的集成方案。
会话共享是另一个值得注意的扩展功能 —— 项目支持通过只读链接分享会话，这为团队协作与代码审查提供了轻量级方案。语音输入则通过 ElevenLabs API 提供转录能力，可按需启用。
五、模式总结与实践建议
Vercel Open Agents 展示了一种面向云端智能体基础设施的架构范式，其核心贡献在于明确了「Agent 控制流」与「执行沙箱」的边界，并通过 Workflow 持久化与快照机制实现了跨越请求与生命周期的状态管理。对于计划构建类似系统的团队，可以提取以下可复用模式：控制平面与执行平面分离，使 Agent 逻辑不绑定到具体执行环境；基于快照的沙箱管理，兼顾环境一致性与资源成本；Workflow 层承接持久化逻辑，确保长时任务的可恢复性；工具抽象层解耦 Agent 与沙箱的具体实现，支持独立演进。
在实际引入时，建议优先评估任务执行时长与资源成本的权衡 —— 如果 Agent 任务多为短时交互，本地执行可能更高效；如果需要处理跨小时级的复杂编码任务或需要多用户并发使用，这一云端架构的投入产出比则更为合理。同时，由于项目明确标注为「reference app」而非生产级黑盒，团队在采用时需要评估自身对 GitHub 集成深度、OAuth 流程定制、多租户隔离等方面的具体需求，并据此进行二次开发。
资料来源：本文主要参考 Vercel Labs 官方开源项目 Open Agents 的架构文档与部署指南，详见 GitHub 仓库 vercel-labs/open-agents。