Workflow SDK 5:为生产环境而生
Workflow SDK 最初发布时的目标很简单:写普通的异步 JavaScript,其余交给 SDK 处理——它会让你的代码在崩溃、部署和长时间等待中持续运行。
workflows/welcome-user.ts1import { sleep } from "workflow";2
3export async function welcomeUser(email) {4 "use workflow";5
6 const user = await createUser(email);7 await sendWelcomeEmail(user);8
9 // 等待期间即使发生崩溃或部署也能存活10 await sleep("3d");11 await sendCheckInEmail(user);12}一个基础的持久化 workflow
去年,我们正式发布了这个功能,并带着 Vercel 一贯的顶级开发者体验。随后我们持续观察客户用它构建了什么。
在超过 40 亿次 step 执行和 7 亿次 run 之后,两种清晰的使用模式浮现出来。
第一种是自动化:传统的工作流场景,比如数据迁移、订单处理、后台任务编排、订阅管理,以及 ETL 和数据管道。
第二种是 agent 和 harness:Agent 运行成本高、耗时长,天然也需要持久化能力。
随着这些工作负载不断成熟,Workflow 也在同步演进。我们的优先级始终是安全性、可靠性和性能。
下面介绍 Workflow SDK 5 如何在这三方面做到更好。
Copy link to heading更安全的 workflow
Workflow 的事件日志会保存 step 的入参和返回值,以便 run 在崩溃或部署后能够恢复。这些数据可能包含敏感的客户信息、模型上下文、凭证以及工具调用结果。持久化这类数据必须有强有力的保护。
Workflow SDK 会对每个 payload 进行端到端加密,在数据离开你的代码之前就完成加密。Workflow 和 step 的输入输出、hook payload 以及流式数据都使用 AES-256-GCM 加密,且每次 run 使用独立密钥。启用加密后,任何 Workflow SDK 后端(包括 Vercel)都只能看到并存储密文。明文只会在你的部署环境或经过授权的可观测性工具中解密。
Copy link to heading在 Vercel 上零配置加密
在 Vercel 上,加密功能无需额外配置,也无需修改代码。每次运行使用的密钥源自限定于创建该次运行的 deployment 范围的密钥,因此某次运行只能解密自身的数据。你的工作流代码无需改动:
workflows/onboard-customer.ts1export async function onboardCustomer(2 customer: Customer,3) {4 "use workflow";5
6 // 客户记录被加密存储7 // 在事件日志中8 const account = await createAccount(customer);9 await sendWelcomeEmail(account.email);10 return account.id;11}12
13async function createAccount(14 customer: Customer,15) {16 "use step";17
18 // ...在此处解密后传入,19 // 位于你的 deployment 内部20 return db.accounts.create(customer);21}在不改变应用逻辑的前提下,Workflow 和 step 的 payload 均已加密。
由于 Vercel 默认管理密钥,可观测性得以维持。名称、耗时和状态始终可见;当你需要查看 payload 时,可在 dashboard 或 CLI 中解密。解密操作在你的浏览器或终端执行,遵循与项目环境变量相同的权限策略,且所有请求都会记录在团队的审计日志中。
# Payloads 显示为 🔒 Encryptednpx workflow inspect run <run-id>
# 若具备访问权限,可在本地解密npx workflow inspect run <run-id> --decrypt检查加密 payload,并在具备授权访问的情况下本地解密。
Copy link to heading在自托管 Worlds 上进行加密
加密在 SDK 中实现,因此也可在自托管 Worlds 上保护 payload,防止其到达存储、队列或流之前泄露。
自定义 World 启用加密的方式是实现 getEncryptionKeyForRun() 并集成你的密钥管理。每次调用时,为同一次运行返回相同的 32 字节密钥,以便 SDK 能够加密新 payload 并在 replay 期间解密它们:
1import type { World } from "@workflow/world";2
3type RunKeyProvider =4 World["getEncryptionKeyForRun"];5
6export const getEncryptionKeyForRun:7 RunKeyProvider = async (run) => {8 const runId =9 typeof run === "string" ? run : run.runId;10
11 // 每次:同一个 run 返回相同的 32 字节密钥,12 // 这样重放时才能解密13 return keyStore.getRunKey(runId);14 };在自定义 World 中为每个 run 提供稳定的 32 字节加密密钥。
复制标题链接v5 的更多安全改进
跨 run 写入也做了封印处理。当代码恢复其他 run 的 hook、在其他 deployment 中启动 run,或写入从其他 run 转发过来的 stream 时,载荷会用目标 run 的公钥加密。写入方可以为该 run 加密,但读不到它已有的载荷。
你还可以限制敏感数据的存储时长。将 payload retention 设置为 experimental_retention: 0 后,run 一完成或失败,输入、输出和 stream 内容就会立即删除。run 的元数据在可观测性面板中仍然可见。
复制标题链接重新设计的 trace 查看器
重新设计的 trace 查看器让 run 更容易浏览,支持 span 搜索、缩放、小地图,以及开发时的本地检查。
Run 属性是 v5 的新功能。它可以为 run 附加可搜索的上下文信息(比如订单 ID),然后据此查找 run。属性是明文存储的,所以不要放敏感信息。
复制标题链接覆盖每个区域的 Workflow
在 Workflow SDK 4 中,所有 run 都位于 iad1。即使项目部署到多个区域,每个 run 的事件日志、队列和 stream 也只存在一个区域里,其他区域的 step 记录进度时都得发起跨区域请求。
在 v5 中,我们将 Workflow 基础设施部署到了每个 Vercel Function 区域。每次运行都有自己所在的区域:其状态、队列分派和数据流都从运行发起的区域提供,避免了热路径上的跨区域往返。
默认情况下,运行会在启动它的函数所在区域开始。部署到多个区域后,每次运行都会保持在触发它的用户附近,无需额外配置:
app/api/checkout/route.ts1import { start } from "workflow/api";2import { processOrder } from "@/workflows/process-order";3
4export async function POST(request: Request) {5 const order = await request.json();6
7 // 在提供此请求的区域中运行8 const run = await start(9 processOrder,10 [order],11 );12 return Response.json({ runId: run.runId });13}在各自请求所在的区域启动订单工作流。
若要将运行放在其他位置,请向 start() 传递 region 参数。这样可以让工作流在数据库所在地运行,或者将客户数据保留在其必须所在的区域:
1// 将此客户的运行数据保留在法兰克福2const run = await start(3 processOrder,4 [order],5 { region: "fra1" },6);将订单工作流数据存储到法兰克福。
region 选项决定运行数据存储的位置。你的步骤运行在你应用部署的区域,因此若希望它们在该区域执行,请也将应用部署到那里。现有的 v4 运行仍保留在 iad1。
复制标题链接基础设施可靠性
区域隔离还能提高可靠性。某一区域的中断不会阻碍健康区域中新运行的启动。对于配置了 Vercel Function 故障转移 的项目,步骤可以在备用区域执行,同时继续使用该运行原本所属的主区域来管理状态。该状态会固定在主区域,不会在故障转移过程中迁移。
借助匿名遥测数据以及与众多客户的紧密合作,我们发现并修复了 Workflow 运行时中的数十个罕见 bug 和竞态条件。Workflow SDK 还能从更多类型的间歇性网络错误中自动恢复。 因此在 Workflow SDK 5 中,我们几乎没有观察到任何因平台或运行时 bug 导致的运行失败或卡住的情况。Copy link to headingAgent 就绪的性能
在 Workflow SDK 4 中,每次步骤调用都要经过一次队列跳转来启动步骤,再经过一次来继续工作流。这对慢速后台自动化任务来说还可以接受,但会给开发者如今构建的 AI 工作负载带来额外延迟。
Agent 循环和 harness 可能包含数千个顺序事件、高吞吐量的 token 流、工具链和动态子 Agent。在这种规模下,每个步骤周边的网络和 CPU 开销就成了瓶颈。
在 Workflow SDK 5 中,我们重写了引擎的很大一部分,以尽量减少额外的队列跳转、不必要的网络请求和 CPU 开销。在所有测量的工作负载中,延迟和开销改善了 1.6 倍到 25 倍,同时保持了相同的开发者体验,也没有引入重大的破坏性变更。
下面的基准测试比较了 Vercel 上的 v5.2.0 和 v4.8.12。选择一项指标来查看 v5 与 v4 的对比,然后播放或拖动进度条查看讲解,了解每项基准测试的具体内容。
Workflow SDK 5 包含数百项性能优化来实现这一目标。以下是这些数字背后的一些主要改动:
更少的队列跳转
在 v4 中,每个步骤都要通过队列交还执行权。在 v5 中,一次调用可以内联执行多个步骤(包括并行步骤),直到遇到等待、hook 或临近超时才让出执行权。
运行时还避免了不必要的持久化往返,并将步骤创建合并到执行过程中。更少的队列和网络请求意味着更少的 CPU 开销和更低的运行时开销。在一个五步基准测试中,p75 步骤间开销从 618 ms 降到了 109 ms。
增量重放
在一个 1,020 步的基准测试中,v4 的 p75 开销会随着事件日志的增长而增加:重放完整事件历史所需的时间与其大小成正比。在最后采样的区间里,开销达到了 1,748 ms,而在 v5.2.0 上仅为 70 ms。完成全部 1,020 步的中位时间从 21.0 分钟降到了 3.0 分钟。
WebSocket 流式传输
持久化机制不应导致流式响应落后于其生产者。在 Vercel World 上,v5.2.0 采用 WebSocket 处理写入