Vercel Workflow SDK：为 TypeScript 而生的韧性工作流运行时

图1：Workflow SDK 官方 Logo

想象这样一个场景：你正在开发一个 AI 客服 Agent，它需要在用户提出问题后，先查询知识库、再调用内部 API、最后生成个性化回复——这中间任何一步失败，整个流程就要重来。传统的 async/await 写法几乎无法优雅地处理这种「可中断、可恢复」的工作流。

Vercel Workflow SDK 正是为了解决这个问题而诞生的。它是 Vercel 官方推出的 TypeScript 工作流运行时，专门为构建具备持久性（Durable）、可靠性（Reliable） 和可观测性（Observable） 的异步应用和 AI Agent 而设计。

背景故事：Vercel 的下一代运行时野心

Workflow SDK 并非凭空诞生——它是 Vercel 在 Edge Functions 和 Serverless 领域的深度积累与 AI Agent 浪潮碰撞后的产物。2024年底至2025年初，AI Agent 从概念走向落地，开发者猛然发现：传统 Serverless 的「请求-响应」模型根本无法支持 Agent 的多步骤、长周期、需暂停等待外部事件的工作模式。

Vercel 迅速捕捉到这一需求，由工程团队 Adrian Lam、Dillon Mulroy、Gal Schlezinger、JJ Kasper 等核心贡献者主导，联合开源社区共同打造了 Workflow SDK。初始版本代号 5.0.0-beta，表明这是一个经过长期内部打磨后才公开的成熟项目。

核心原理：状态持久化与Replay机制

Workflow SDK 的核心设计哲学，可以用「checkpoint-and-replay」来概括：

Step（步骤）模型：每个工作流由多个 Step 组成，每个 Step 执行完后，其结果会被序列化（serialize） 并持久化到存储后端（World）。当工作流因网络中断、进程重启等原因中断时，运行时可以从最近的 Step 断点恢复，而不是从头开始——这是「Durable Execution」的核心能力。

World 抽象层：这是 Workflow SDK 最精妙的设计之一。@workflow/world 定义了一套统一的接口抽象，涵盖了工作流的存储（Storage）、队列（Queue）、认证（Auth）和流式传输（Streaming）。具体实现则由不同的 World 包提供：

• @workflow/world-local：文件系统后端，适合本地开发，自动检测开发服务器端口用于队列传输，next dev 和 next start 默认使用它。
• @workflow/world-vercel：Vercel 平台生产后端，与 Vercel 基础设施深度集成，支持自动扩缩容。
• @workflow/world-postgres：PostgreSQL 后端，适合需要强一致性数据持久化的场景。

Sleep 与暂停：工作流可以调用 sleep() 主动暂停，等待外部事件（如 webhook、定时任务、人工审批）。暂停期间不消耗计算资源，被唤醒后可从暂停点继续执行。

架构设计：28个子包的Monorepo

Workflow SDK 采用 pnpm workspace + Turborepo 管理的 Monorepo 架构，共包含 28 个子包，按职责可分为以下几类：

运行时核心（@workflow/core）：包含工作流执行引擎、事件日志、序列化/反序列化、Sleep/暂停逻辑、重试与超时处理、遥测（Telemetry）集成。这是整个 SDK 的心脏，通过 step.ts、runtime.ts、workflow.ts 等核心文件实现。

AI Agent 集成（@workflow/ai）：与 Vercel AI SDK（@ai-sdk/provider）深度集成，提供 workflow-chat-transport 等传输层组件，让 AI Agent 的对话流可以无缝接入工作流引擎。支持 AI SDK 的流式响应、工具调用（Tool Use）和多轮对话。

框架适配器：项目提供了对主流 Web 框架的官方适配，覆盖 Next.js（@workflow/next）、Astro（@workflow/astro）、SvelteKit（@workflow/sveltekit）、Nuxt（@workflow/nuxt）、Nitro（@workflow/nitro）、NestJS（@workflow/nest）。这意味着无论你用哪个框架，都能以一致的方式使用 Workflow SDK。

基础设施集成：包含 Vite 插件（@workflow/vite）、Rollup 插件（@workflow/rollup）、SWC 编译器插件（@workflow/swc-plugin-workflow）、TypeScript 插件（@workflow/typescript-plugin）。这些插件在构建阶段为工作流代码提供编译时优化和类型检查。

CLI 工具（@workflow/cli）：命令行工具，支持工作流的初始化、调试、部署等操作。

开发文档站点（packages/web、docs）：基于 React Router + TypeScript 的官方文档站点，托管于 workflow-sdk.dev。

技术细节一览

上手体验：本地开发与生产部署

本地开发极为顺滑：安装 workflow 包后，在 Next.js 项目中只需几行代码就能定义一个工作流。由于 @workflow/world-local 默认作为本地后端，工作流数据以 JSON 文件存储在磁盘，队列使用内存传输——无需配置任何外部服务，pnpm dev 即可运行完整的工作流。

生产部署需要 Vercel 平台或自建 World 后端（PostgreSQL）。Workflow SDK 本身没有打包成 Docker 镜像，需要通过 Vercel CLI 或框架适配器部署到 Vercel Edge/Serverless 平台。官方强烈推荐使用 Vercel 平台以获得最佳体验。

局限与挑战

厂商锁定（Vendor Lock-in）：生产级后端 world-vercel 与 Vercel 基础设施深度耦合。切换到自托管方案（world-postgres）需要额外的运维工作，且部分高级特性可能缺失。

beta 状态：核心包版本号仍带有 5.0.0-beta.26，API 尚未稳定，生产环境使用需承担一定风险。

学习曲线：Durable Execution 的编程模型与传统的请求-响应模型差异显著，开发者需要理解 Step、Replay、Sleep 等核心概念，初期上手有一定门槛。

文档成熟度：虽然 workflow-sdk.dev 提供了文档站点，但部分高级特性（如加密工作流、自定义 World 后端）的文档仍然偏少。

行业意义

Workflow SDK 的出现，标志着 Vercel 正在将** Durable Execution** 这一过去属于 Temporal 等专业工作流引擎的能力，以轻量化的方式带入 TypeScript/Node.js 生态。随着 AI Agent 场景的爆发，这类能够「优雅处理失败与中断」的运行时将成为刚需。

从 GitHub 数据看，项目目前已积累 2,185 stars，拥有 227 个 open issues，说明社区活跃度较高且项目仍在快速迭代中。它的出现也让 Vercel 在 AI Agent 基础设施赛道中占据了有利位置——与其竞品相比，Workflow SDK 的 TypeScript 原生设计和 Vercel 平台的深度集成是核心差异化优势。

未来，随着 SDK 脱离 beta、文档完善以及更多 World 后端实现（如 SQLite、MongoDB），Workflow SDK 有潜力成为 Node.js 生态中构建 Durable AI Agent 的首选框架。