当我们谈论云端代理（Cloud Agent）的工程化部署时，一个核心问题始终存在：代理逻辑的执行环境与代码运行的环境应该如何组织？许多早期方案倾向于将代理直接嵌入虚拟机内部，让代理进程在沙箱中直接运行代码。然而，这种紧密耦合的设计往往导致生命周期管理复杂化、状态恢复困难，以及代理逻辑与执行环境之间的强耦合。Vercel Labs 发布的 open-agents 项目提供了一种不同的思路：通过明确分离代理运行时与沙箱执行层，构建一个可观测、可恢复、易于扩展的云代理架构。
三层架构概览
open-agents 项目采用经典的三层结构设计，从上到下依次是 Web 层、代理工作流层和沙箱虚拟机层。Web 层负责处理身份认证、会话管理、聊天界面以及流式响应输出；代理工作流层运行在 Vercel 的 Durable Workflow 基础设施之上，负责多步骤任务的编排与状态持久化；沙箱层则是隔离的虚拟机环境，提供文件系统、Shell 访问、Git 操作、开发服务器以及预览端口等能力。这种分层设计的核心理念在于每一层都可以独立演进，代理逻辑的迭代不必牵动底层执行环境的变更，反之亦然。
值得注意的是，项目的官方文档中明确指出「The agent is not the sandbox」这一关键架构决策。代理并不运行在虚拟机内部，而是作为外部协调者，通过文件读取、编辑、搜索、Shell 命令等工具与沙箱进行交互。这种设计选择带来了几个显著的工程优势：代理的执行不再受限于单个 HTTP 请求的生命周期，可以跨越多个持久化的工作流步骤继续运行；沙箱可以独立进行休眠和恢复，不依赖于代理进程的状态；模型提供商和沙箱实现可以独立迭代，无需彼此兼容；虚拟机保持纯粹的执行环境定位，不承担控制平面职责。
运行时模型与 Durable Workflow
在运行时层面，open-agents 利用 Vercel 的 Workflow SDK 实现持久化多步骤编排。当用户发送聊天请求时，系统不会立即执行代理逻辑，而是启动一个工作流运行（workflow run）。每个代理回合（turn）可以跨越多个持久化的工作流步骤，这意味着即使是耗时的代码生成任务，也可以被拆分为多个步骤执行，中途任何时刻都可以暂停和恢复。官方文档特别提到，活跃的运行可以通过重新连接到现有工作流的流来恢复，这意味着用户切换设备或网络中断后，代理任务能够无缝衔接。
这种 durable execution 模式与传统的无服务器函数调用有本质区别。传统方案中，函数执行受限于超时约束，长时间运行的任务必须手动拆分为多个异步调用并自行管理状态。而 Durable Workflow 抽象了这一复杂性，提供了内置的重试机制、状态持久化和中断恢复能力。代理开发者可以专注于业务逻辑的实现，将可靠性保证交给平台层处理。对于构建背景编码代理（background coding agents）这类需要长时间交互的任务来说，这种模式尤为合适。
沙箱隔离与生命周期管理
沙箱层是 open-agents 架构中另一个重要的工程决策点。每个沙箱都是独立的虚拟机实例，通过快照机制实现快速启动和状态恢复。项目默认暴露四个端口：3000（Next.js 默认）、5173（Vite 开发服务器）、4321（Astro）以及 8000（通用 Python/Node 服务），这覆盖了主流前端框架的调试需求。沙箱在空闲一段时间后会自动进入休眠状态，需要时再通过快照恢复，这种设计显著降低了长时间运行代理的资源成本。
从集成角度看，项目已实现与 GitHub 的深度整合。用户可以授权代理直接克隆代码仓库、在分支上工作、执行提交和创建 Pull Request。整个流程可以在无需用户本地环境参与的情况下完成，代理在云端完成代码修改后自动推送结果。这种端到端的自动化能力依赖于代理层与沙箱层的清晰职责划分：代理负责决策和协调，沙箱负责执行和状态管理。
部署参数与最小化配置
对于希望部署这套系统的开发者而言，理解环境变量配置是第一步。最小化运行只需要两个核心变量：POSTGRES_URL 用于持久化工作流状态和会话数据，JWE_SECRET 用于会话令牌加密。如果需要完整的用户登录功能，还需添加 ENCRYPTION_KEY、VERCEL_APP_CLIENT_ID 和 VERCEL_APP_CLIENT_SECRET 来启用 Vercel OAuth 认证。要实现 GitHub 仓库操作能力，则需要配置 GitHub App 的相关凭证，包括 APP_ID、CLIENT_ID、CLIENT_SECRET、PRIVATE_KEY 和 WEBHOOK_SECRET 等。
可选配置中，REDIS_URL 或 KV_URL 用于技能元数据的缓存（未配置时会降级为内存缓存），ELEVENLABS_API_KEY 支持语音输入转文字功能。项目推荐使用 Neon 作为 PostgreSQL 提供商，Upstash KV 作为 Redis 替代方案，两者都可以在 Vercel 平台上一键集成。部署流程本身非常标准化：Fork 仓库、创建数据库、生成密钥、导入 Vercel 项目、配置环境变量、部署，整个过程可以在数分钟内完成。
工程价值的思考
open-agents 项目的架构设计代表了一种务实的云代理工程化路径。它没有试图重新发明代理协议，也没有追求通用性而牺牲可用性，而是基于 Vercel 平台的能力边界，提供了一个可直接 fork 和定制的生产级参考实现。Agent 与 Sandbox 的分离是整个架构的核心洞察，这种设计让代理逻辑可以像普通业务代码一样开发和版本管理，而执行环境的可靠性则由平台层统一保障。对于需要在云端构建自动化编码、数据处理或多步骤任务系统的团队而言，这种架构提供了可操作的工程范式。
参考资料
- Vercel Labs open-agents 官方仓库：https://github.com/vercel-labs/open-agents
- Vercel 官方博客：Anyone can build agents, but it takes a platform to run them