AI SDK WorkflowAgent 深度解析从 ai-sdk/workflow 变更日志看持久化 Agent 的能力演进【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读ai-sdk/workflow是 AI SDK 官方工作流集成包其核心WorkflowAgent是一个可跨工作流步骤维持状态、调用工具并优雅处理中断的持久化 Agent 类。本文以该包 CHANGELOG.md 为线索完整梳理从1.0.0-beta.0到2.0.28的能力演进脉络并对照 src/workflow-agent.ts、src/generate-video.ts 等源码展开实现级讲解。读完本文你将掌握WorkflowAgent的完整 API 面、工具审批安全模型、步骤控制与上下文传递机制、流式传输与重连方案以及如何在工作中正确取舍各类配置项。一、包定位与版本全景1.1 WorkflowAgent 是什么根据 README.mdWorkflowAgent是一个用于构建持久化durableAI Agent的类它可以跨工作流步骤维持状态、调用工具并在中断时优雅恢复。这意味着 Agent 的每一步LLM 调用、工具执行都可以作为可恢复的工作流步骤持久化进程崩溃或网络中断后可以从已完成的步骤继续而不是从头重放。1.2 版本演变主线从 CHANGELOG.md 可以清晰看到三条主线版本号体系1.0.0-beta.0→1.0.0首个稳定版→1.0.x系列 →2.0.0升级到 Workflow 5 并放弃 Workflow 4→2.0.x系列当前最新2.0.28依赖跟随ai从7.0.0-beta.89一路跟随到7.0.97ai-sdk/provider与ai-sdk/provider-utils同步升级能力演进从基础的工具调用、步骤循环逐步演进到结构化输出、工具审批签名、持久化视频生成、流式断线重连、沙箱执行等完整能力。从 package.json 可以看到运行前提engines.node 22peerDependencies要求workflow^5.0.0-beta.42与zod^3.25.76 || ^4.1.8。二、安装与最小可用示例按照 README.md 的安装方式npm install ai-sdk/workflow ai workflowbeta注意workflow运行时当前以beta标签发布这与 CHANGELOG 中2.0.0的 Major Changes 一致Applications must now install Workflow 5, which is currently available under thebetatag。一个最小的天气助手示例import { WorkflowAgent } from ai-sdk/workflow; import { z } from zod; const agent new WorkflowAgent({ model: anthropic/claude-opus, tools: { getWeather: { description: Get weather for a location, inputSchema: z.object({ location: z.string() }), execute: async ({ location }) { // Fetch weather data return { temperature: 72, condition: sunny }; }, }, }, system: You are a helpful weather assistant., }); const result await agent.stream({ messages: [{ role: user, content: What is the weather in SF? }], writable: new WritableStream({ write(chunk) { console.log(Chunk:, chunk); }, }), }); console.log(Final messages:, result.messages); console.log(Steps:, result.steps);其中writable接收原始的LanguageModelV4StreamPart数据块可以在不耦合UIMessageChunk格式的情况下把流实时转发到客户端详见 src/workflow-agent.ts 中WorkflowAgentStreamOptions.writable的说明。三、核心 API 面构造选项与流式调用3.1 构造选项 WorkflowAgentOptions在 src/workflow-agent.ts 中WorkflowAgentOptions定义了完整的构造参数关键字段包括字段说明model模型可以是兼容 Vercel AI Gateway 的字符串如anthropic/claude-opus也可以是LanguageModelV4实例tools工具集可被实现为工作流步骤以获得自动重试与持久化instructions/systemAgent 指令system已标记为deprecated推荐使用instructions支持SystemModelMessage以携带 provider 级选项如缓存toolChoice工具选择策略默认autostopWhen停止条件可为单个或数组数组时任一满足即停止activeTools限制模型可调用工具集合不改变结果中的工具调用/结果类型output结构化输出规格使用Output.object({ schema })或Output.text()repairToolCall修复解析失败工具调用的函数原experimental_repairToolCall已废弃别名experimental_download自定义 URL 下载函数experimental_sandbox传给工具执行的沙箱环境experimental_toolApprovalSecret工具审批 HMAC 签名密钥的环境变量引用runtimeContext/toolsContext共享运行时上下文与按工具隔离的上下文prepareCall/prepareStep调用前/步骤前的参数变换钩子onStart/onStepStart/onStepEnd/onEnd/onToolExecutionStart/onToolExecutionEnd生命周期回调allowSystemInMessages是否允许在prompt/messages中出现系统消息默认false值得注意的设计构造级默认值与流级覆盖。根据1.0.0-beta.5的变更记录stopWhen、activeTools、output、experimental_repairToolCall、experimental_download等都可以在构造函数上设置默认值stream()级别传入的值会覆盖构造默认值。3.2 生成参数 GenerationSettingsGenerationSettingssrc/workflow-agent.ts定义了可传给模型的所有生成参数与LanguageModelV4CallOptions直接映射maxOutputTokens最大输出 token 数temperature/topP温度与核采样官方建议二选一设置topKTop-K 采样仅建议高级场景使用presencePenalty/frequencyPenalty范围-1到10表示无惩罚stopSequences停止序列数组provider 可能限制数量seed随机种子模型支持时可获得确定性结果maxRetries可重试失败的最大次数默认 2设为0禁用重试abortSignal取消操作信号headers附加 HTTP 头仅对 HTTP provider 生效reasoning推理努力程度从1.0.6起由WorkflowAgent转发给模型调用providerOptions透传给 provider 的专属选项。3.3 stream() 调用参数WorkflowAgentStreamOptionssrc/workflow-agent.ts在构造默认值之上提供流级覆盖并额外包含prompt或messages二者只能选其一prompt支持字符串或消息数组writable接收原始流块的WritableStreamModelCallStreamPartincludeRawChunks是否包含 provider 原始 chunktype: raw用于访问尚未被 AI SDK 封装的 provider 新特性默认falseexperimental_transform流变换可多个按顺序应用且必须保持流结构output结构化输出规格例如import { Output } from ai-sdk/workflow; import { z } from zod; const result await agent.stream({ messages: [...], writable: getWritable(), output: Output.object({ schema: z.object({ sentiment: z.enum([positive, negative, neutral]), confidence: z.number(), }), }), }); console.log(result.output); // { sentiment: positive, confidence: 0.95 }stream()返回的结果对象在1.0.17起增加了totalUsage与finishReason字段与GenerateTextResult/StreamTextResult对齐也包含在onEnd事件载荷中。四、步骤循环与上下文传递4.1 prepareStep每步动态干预prepareStep回调在每个步骤开始前调用返回的PrepareStepResultsrc/workflow-agent.ts中所有字段均可选只返回你想覆盖的部分model覆盖本步模型system覆盖本步系统消息messages覆盖本步消息用于上下文管理或消息注入toolChoice覆盖工具选择策略activeTools限制本步可用工具2.0.18起prepareStep.activeTools被限制为仅包含已配置的工具名runtimeContext/toolsContext返回新值以更新后续步骤的上下文experimental_sandbox覆盖沙箱。回调入参PrepareStepInfo包含stepNumber从 0 开始、steps此前所有步骤结果、messages将发给模型的LanguageModelV4Prompt、initialInstructions、initialMessages以及当前runtimeContext/toolsContext。4.2 prepareCall循环启动前的整体变换prepareCall在 Agent 循环开始前只调用一次src/workflow-agent.ts用于基于运行时上下文变换model、tools、instructions、toolChoice、stopWhen、activeTools、telemetry、messages等参数。注意tools无法通过prepareCall覆盖因为工具在构造期就已绑定以保证类型安全源码注释明确说明了这一点。1.0.62起prepareCall返回的maxRetries与abortSignal覆盖也会被真正执行。4.3 runtimeContext 与 toolsContext 的分离1.0.0对应 canary.41 变更引入了一次重要重构context被拆分为runtimeContext与toolsContext并移除了旧的experimental_context选项runtimeContext共享的 Agent 状态贯穿prepareCall、prepareStep、步骤结果与onEnd回调通过从prepareStep返回新值来更新toolsContext按工具键控的映射每个工具在执行时只会收到属于自己的、经过校验的条目作为context当工具声明了contextSchema时会按 schema 校验。由于上下文可能跨越工作流与步骤边界源码注释明确要求context 中的值应当可序列化serializable。4.4 stopWhen 取代 maxSteps1.0.0版本移除了maxSteps选项改为stopWhen配合停止条件如isStepCount()使用。当stopWhen为数组时任一条件满足即停止生成。2.0.20进一步修复了停止条件中工具与运行时上下文类型的保留问题2.0.21起stopWhen相关类型推断更加稳定。五、工具审批安全模型工具审批是WorkflowAgent在2.0.x系列中最核心的安全能力其演进路径非常清晰5.1 签名审批2.0.162.0.16在ai核心中引入签名工具审批。通过experimental_toolApprovalSecret配置一个环境变量名注意是变量名而非变量值const agent new WorkflowAgent({ model, tools, experimental_toolApprovalSecret: { environmentVariable: TOOL_APPROVAL_SECRET, }, });关键设计源码注释明确只有环境变量名会跨工作流边界序列化密钥值只在签名与验证步骤内读取从不被序列化。签名过程调用ai/internal的signToolApproval验证调用verifyToolApprovalSignature。5.2 审批重放漏洞与修复1.0.0 与 canary.87CHANGELOG 用较长篇幅记录了一个安全漏洞及其修复commitbae5e2b审批重放路径approval-replay path会从客户端提供的 messages 数组中重建已批准的approved工具调用并直接执行而不重新校验输入是否符合工具的 schema也不重新应用审批策略。攻击者可以伪造一条带有已批准工具调用部分的 assistant 消息让服务端以攻击者选定的参数执行工具。修复后的重放路径现在在配置了experimental_toolApprovalSecret时校验 HMAC 签名依据工具的输入 schema重新校验工具调用输入重新解析审批策略后再执行。5.3 复用核心审批校验1.0.0 / canary.87 的 69d7128为了避免逻辑重复导致的漂移WorkflowAgent.stream不再内联复制核心收集逻辑而是改用共享的collectToolApprovals收集审批并通过validateApprovedToolApprovals统一重新校验输入 schema 重校验、HMAC 签名验证、审批策略重解析两者现在从ai/internal导出。5.4 provider 执行工具的审批转发1.0.0 / canary.100修复了一个逆方向的 bug此前WorkflowAgent在恢复时会剥离所有tool-approval-request/tool-approval-response部分导致 provider 执行型工具如经 OpenAI Responses API 调用的 MCP 工具永远收不到审批结果。修复后本地执行工具的审批仍会被消费并剥离而 provider 执行工具的审批会被保留并转发给 provider。5.5 审批相关的流与重试行为2.0.18被批准的工具保留其上下文与生命周期回调2.0.8当重校验后的工具输入无效时以模型可见的工具错误继续当前generateText/streamText/WorkflowAgent回合1.0.52当兄弟工具因客户端执行或审批而暂停时已完成工具的结果仍会流入流。六、结构化输出结构化输出能力在 CHANGELOG 中多次出现1.0.61WorkflowAgent.stream()将结构化输出的响应格式response format转发给模型流调用2.0.21在流结果中推断构造级的结构化输出1.0.0eb49d29构造级output默认值流级覆盖构造默认值。使用方式即Output.object({ schema })或Output.text()从ai-sdk/workflow主入口导出。OutputSpecification接口src/workflow-agent.ts包含name、responseFormat、parsePartialOutput、parseCompleteOutput四个成员其中parseCompleteOutput可以拿到response、usage、finishReason元数据。onEnd回调与流结果中的output字段只在指定了output规格时可用。七、工具执行的模型输出与错误语义7.1 toModelOutput 钩子1.0.0 / canary.84WorkflowAgent现在会尊重每个工具的toModelOutput钩子本地执行、provider 执行与已批准的工具结果都会经由该钩子路由与generateText、streamText、ToolLoopAgent保持一致。此前钩子被忽略结果一律序列化为text或json。实现上复用了ai/internal的共享工具结果模型输出辅助函数并采用共享的getErrorMessage行为处理工具错误结果。7.2 非法工具调用的错误保留1.0.0 / beta.27 的 a0ca584修复了把非法工具调用当作合成成功结果发出的问题非法的工具调用现在以错误形式保留而不是被伪装成成功。7.3 失败工具执行的流式错误2.0.18失败的本地工具执行会以工具错误tool error的形式流入流而非中断整个流程或静默吞掉。八、流式传输、UI 消息与断线重连8.1 流数据模型ModelCallStreamPartsrc/do-stream-step.ts是流块的联合类型Experimental_LanguageModelStreamPart加上tool-approval-request携带approvalId、toolCallId、可选signature和reset-step。doStreamStep负责执行单步模型调用其选项与GenerationSettings对应含timeoutAt绝对超时。8.2 WorkflowChatTransport持久化流重连workflow-chat-transport.ts 提供了WorkflowChatTransport用于在重连时恢复持久化流。其核心难点是orphan UI chunk孤儿数据块当以负的initialStartIndex重连时游标很容易落在某个 part 的中间导致客户端在收到text-delta/tool-input-delta/*-end时因为没看到对应的*-start而崩溃。createOrphanFilter的实现要点text-start/reasoning-start记录 part idtool-input-start、自包含的tool-input-available/tool-input-error记录 toolCallId引用未见起点的text-delta/text-end/reasoning-delta/reasoning-end、tool-input-delta、tool-approval-request、tool-output-available/tool-output-error/tool-output-denied会被丢弃并输出一次性警告reset-step会清空已见集合注释明确说明这是尽力而为的安全网若想完整保留消息服务端应把流回卷到步骤边界step boundary。相关修复包括1.0.6修复 UI 消息流 part 框架重复或交错的持久化流写入不再以Received text-delta for missing text part崩溃1.0.17的重连修复148babc2.0.1使用 UI 消息 chunk 索引恢复变换后的流4233a40。8.3 步骤边界的流规范化2.0.9修复当另一个合并的 UI 消息流完成某一步骤时保留正在进行的 text 与 reasoning 部分并使工作流流规范化与显式 part 结束 chunk 对齐。1.0.17的e660e45则精简了doStreamStep的步骤边界载荷只返回最小原始聚合在步骤外重建StepResult而不是把完整StepResult与逐 chunk 数组都序列化进持久化事件日志——这直接关系到持久化日志的体积与恢复速度。九、持久化视频生成2.0.11aed8ff3引入的持久化视频生成是该包最有特色的能力之一README与 src/generate-video.ts 提供了完整说明。9.1 使用方式import { experimental_generateVideo as generateVideo } from ai-sdk/workflow/video; export async function videoWorkflow(prompt: string) { use workflow; const result await generateVideo({ model: klingai/kling-v3.0-t2v, prompt, }); return result.videos; }注意子路径导入ai-sdk/workflow/video在 package.json 的exports中声明源码入口为 src/video.ts。9.2 实现机制experimental_generateVideosrc/generate-video.ts的执行流程校验模型要求模型为字符串走 Gateway或支持原生 webhookspecificationVersion v4且handleWebhookOption ! null否则抛出Workflow video generation requires a model with native webhook support.启动视频生成startVideoStep通过createWebhook()创建 webhook 并传入webhookUrl同时自动注入idempotency-key格式aisdk_workflow_video_stepId两个内部 step 均设置maxRetries 0挂起等待工作流在await webhook处挂起、不消耗计算资源直到 provider 回调 webhook URL查询状态getVideoStatusStep使用experimental_getVideoStatus获取结果错误时抛出非 completed 时抛错返回 provider 数据不下载托管 URL返回结果合并了 start 与 status 两个阶段的 warnings。正如 README 所述工作流可以在后续独立步骤中持久化、复制或处理每个返回的视频 URL而无需将视频字节序列化穿过工作流。十、中断、重试与超时语义绝对超时1.0.67修复WorkflowAgent超时处理在持久化模型调用步骤内部强制绝对截止时间并将超时路由到中止处理重试不叠加1.0.68遵循WorkflowAgent模型调用重试设置不叠加工作流步骤重试同时模型流错误部分在已解析结果上暴露原始值不再重试持久化模型步骤中止信号传播2.0.19c143af4将 Agent 的中止信号传播给本地工具执行1.0.0的f32c750简化了mergeAbortSignals步骤重试清理2.0.0的 d3cc3fe当模型调用步骤被重试时清除部分的 UI 消息 partonAbort 回调携带此前所有已完成步骤的StepResult[]。十一、生命周期回调事件形状1.0.00455f24将回调事件与ToolLoopAgent对齐onToolCallStart/onToolCallFinish增加stepNumberonStepStart增加steps此前步骤结果数组onToolCallFinish采用判别联合discriminated union模式success: true/falseonToolCallFinish增加durationMs。当前完整回调集均以WorkflowAgentOn*前缀命名见 src/workflow-agent.tsonStart流开始前一次onStepStart每个步骤前2.0.18起提供稳定版本取代experimental_onStepStartonStepEnd每步完成后旧名onStepFinish1.0.0起更名onToolExecutionStart/onToolExecutionEnd工具执行前后2.0.24起在具体工具集上保留按工具细化的类型并导出回调事件类型onEndLLM 响应与所有请求的工具执行完成后携带steps、messages、text、finishReason、usage/totalUsage、runtimeContext、toolsContext、outputonError、onAbort。工具执行结束事件src/workflow-agent.ts是判别联合success: true时携带outputsuccess: false时携带error。在具体工具集上每个联合成员会把工具调用与其对应的toolContext、输出类型关联起来TypeScript 可以直接窄化。十二、上下文、指令与其他细节12.1 Instructions 类型1.0.0引入Instructions类型d775a57instructions可以是字符串、SystemModelMessage或SystemModelMessage数组使用消息形式时可携带 provider 专属选项如缓存。1.0.39还支持动态工具描述与流级指令。12.2 系统消息注入防护1.0.0b402b95WorkflowAgent默认拒绝prompt/messages内的系统消息与generateText/streamText行为一致以防范提示注入仅当allowSystemInMessages: true时才允许。12.3 可序列化 Schema 与工具过滤1.0.21统一从zod/v4导入与项目规范一致1.0.0fbea042用ai的共享experimental_filterActiveTools替换重复的filterTools/filterToolSet2.0.19尊重空的activeTools列表即显式禁用全部工具1.0.32在工具调用的对话消息中保留 assistant 文本1.0.01e4b350 相关工具结果的模型输出统一走共享辅助函数。12.4 遥测与可观测性1.0.0experimental_telemetry转正为稳定telemetry1949571TelemetrySettings更名为TelemetryOptions1.0.0id属性用于遥测标识与ToolLoopAgentAPI 对齐bf6c17b1.0.0修复stepNumber在遥测事件上的值使按步骤维护状态的集成如ai-sdk/devtools能正确按步骤键控状态81e68da1.0.56在语言模型调用结束回调与遥测 span 上暴露 provider 元数据1.0.0334ae5d步骤性能指标增加明确的 effective / input / output / total token 吞吐字段请求会附带ai-sdk-agentuser-agent 段用于用量归属75763b0。12.5 包工程化1.0.20c29e0d7将包标记为 ESM修复此前require(ai-sdk/workflow)报MODULE_NOT_FOUND声明的 CJS 入口从未发布的问题1.0.66c661693workflow/vitest与已安装的 Workflow 运行时对齐修复集成测试脚手架。十三、从源码结构理解包的全貌src 目录清晰地映射了上述能力文件职责src/index.ts主入口导出WorkflowAgent、Output、全部选项/回调类型、WorkflowChatTransport、toUIMessageChunk、normalizeUIMessageStreamParts等src/workflow-agent.tsWorkflowAgent类与全部类型定义约 3300 行src/do-stream-step.ts单步模型调用执行、流块类型、provider 执行工具结果捕获src/workflow-chat-transport.ts持久化流的客户端传输与重连orphan chunk 过滤src/to-ui-message-chunk.ts模型调用流 → UI 消息 chunk 转换src/normalize-ui-message-stream.tsUI 消息流 part 规范化src/generate-video.ts持久化视频生成webhook 挂起/恢复src/serializable-schema.ts工具 schema 的可序列化处理src/resolve-tool-context.ts工具上下文解析src/add-tool-results-to-conversation.ts工具结果回填对话src/stream-text-iterator.ts流文本迭代器测试覆盖同样完整可作行为验证依据workflow-agent.test.ts核心行为与类型、workflow-agent-e2e.integration.test.ts端到端、workflow-agent-stream-error.test.ts流错误语义、workflow-chat-transport.test.ts与workflow-chat-transport.stream-repair.test.ts重连与流修复、generate-video.test.ts与generate-video.integration.test.ts视频生成、workflow-agent-file-source-retention.test.tsprovider 顺序的文件/来源保留、workflow-agent-response-format.test.ts结构化输出格式、workflow-smoke.integration.test.ts冒烟。示例工作流定义位于 src/test/如calculate-workflow.ts、video-generation-workflow.ts、retrying-model.ts、serializable-video-model.ts、mock.ts可作为编写自定义工作流的参考模板。十四、升级到 2.x 的注意事项CHANGELOG 中与破坏性变更直接相关的记录Workflow 运行时2.0.0要求workflow5beta 标签不再支持 Workflow 4peerDependencies为workflow^5.0.0-beta.42maxSteps已移除1.0.0改用stopWhen 停止条件如isStepCount()上下文重构1.0.0experimental_context已删除使用runtimeContext共享与toolsContext按工具回调更名1.0.0onStepFinish→onStepEndonFinish→onEndonToolCall*事件更名为onToolExecutionStart/onToolExecutionEndexperimental_onStart/experimental_onStepStart已由稳定版本取代WorkflowAgentOn*前缀命名规范0e462a7system弃用推荐使用instructionsNode 版本最低 22支持 22、24、26。结语从1.0.0-beta.0到2.0.28ai-sdk/workflow的 CHANGELOG 本身就是一部如何把 Agent 做到生产可用的实践手册审批重放漏洞的修复展示了客户端消息永远不可信、执行前必须重新校验的安全原则runtimeContext/toolsContext的拆分展示了持久化场景下共享状态与工具隔离状态的边界设计WorkflowChatTransport的孤儿 chunk 过滤展示了持久化流在任意位置重连时如何保证客户端不崩溃。结合 README.md 与 src 源码阅读本文提到的每个能力点即可在自己的项目中正确构建具备持久化、审批、结构化输出与视频生成能力的生产级 Agent。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AI SDK WorkflowAgent 深度解析：从 @ai-sdk/workflow 变更日志看持久化 Agent 的能力演进
AI SDK WorkflowAgent 深度解析从 ai-sdk/workflow 变更日志看持久化 Agent 的能力演进【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读ai-sdk/workflow是 AI SDK 官方工作流集成包其核心WorkflowAgent是一个可跨工作流步骤维持状态、调用工具并优雅处理中断的持久化 Agent 类。本文以该包 CHANGELOG.md 为线索完整梳理从1.0.0-beta.0到2.0.28的能力演进脉络并对照 src/workflow-agent.ts、src/generate-video.ts 等源码展开实现级讲解。读完本文你将掌握WorkflowAgent的完整 API 面、工具审批安全模型、步骤控制与上下文传递机制、流式传输与重连方案以及如何在工作中正确取舍各类配置项。一、包定位与版本全景1.1 WorkflowAgent 是什么根据 README.mdWorkflowAgent是一个用于构建持久化durableAI Agent的类它可以跨工作流步骤维持状态、调用工具并在中断时优雅恢复。这意味着 Agent 的每一步LLM 调用、工具执行都可以作为可恢复的工作流步骤持久化进程崩溃或网络中断后可以从已完成的步骤继续而不是从头重放。1.2 版本演变主线从 CHANGELOG.md 可以清晰看到三条主线版本号体系1.0.0-beta.0→1.0.0首个稳定版→1.0.x系列 →2.0.0升级到 Workflow 5 并放弃 Workflow 4→2.0.x系列当前最新2.0.28依赖跟随ai从7.0.0-beta.89一路跟随到7.0.97ai-sdk/provider与ai-sdk/provider-utils同步升级能力演进从基础的工具调用、步骤循环逐步演进到结构化输出、工具审批签名、持久化视频生成、流式断线重连、沙箱执行等完整能力。从 package.json 可以看到运行前提engines.node 22peerDependencies要求workflow^5.0.0-beta.42与zod^3.25.76 || ^4.1.8。二、安装与最小可用示例按照 README.md 的安装方式npm install ai-sdk/workflow ai workflowbeta注意workflow运行时当前以beta标签发布这与 CHANGELOG 中2.0.0的 Major Changes 一致Applications must now install Workflow 5, which is currently available under thebetatag。一个最小的天气助手示例import { WorkflowAgent } from ai-sdk/workflow; import { z } from zod; const agent new WorkflowAgent({ model: anthropic/claude-opus, tools: { getWeather: { description: Get weather for a location, inputSchema: z.object({ location: z.string() }), execute: async ({ location }) { // Fetch weather data return { temperature: 72, condition: sunny }; }, }, }, system: You are a helpful weather assistant., }); const result await agent.stream({ messages: [{ role: user, content: What is the weather in SF? }], writable: new WritableStream({ write(chunk) { console.log(Chunk:, chunk); }, }), }); console.log(Final messages:, result.messages); console.log(Steps:, result.steps);其中writable接收原始的LanguageModelV4StreamPart数据块可以在不耦合UIMessageChunk格式的情况下把流实时转发到客户端详见 src/workflow-agent.ts 中WorkflowAgentStreamOptions.writable的说明。三、核心 API 面构造选项与流式调用3.1 构造选项 WorkflowAgentOptions在 src/workflow-agent.ts 中WorkflowAgentOptions定义了完整的构造参数关键字段包括字段说明model模型可以是兼容 Vercel AI Gateway 的字符串如anthropic/claude-opus也可以是LanguageModelV4实例tools工具集可被实现为工作流步骤以获得自动重试与持久化instructions/systemAgent 指令system已标记为deprecated推荐使用instructions支持SystemModelMessage以携带 provider 级选项如缓存toolChoice工具选择策略默认autostopWhen停止条件可为单个或数组数组时任一满足即停止activeTools限制模型可调用工具集合不改变结果中的工具调用/结果类型output结构化输出规格使用Output.object({ schema })或Output.text()repairToolCall修复解析失败工具调用的函数原experimental_repairToolCall已废弃别名experimental_download自定义 URL 下载函数experimental_sandbox传给工具执行的沙箱环境experimental_toolApprovalSecret工具审批 HMAC 签名密钥的环境变量引用runtimeContext/toolsContext共享运行时上下文与按工具隔离的上下文prepareCall/prepareStep调用前/步骤前的参数变换钩子onStart/onStepStart/onStepEnd/onEnd/onToolExecutionStart/onToolExecutionEnd生命周期回调allowSystemInMessages是否允许在prompt/messages中出现系统消息默认false值得注意的设计构造级默认值与流级覆盖。根据1.0.0-beta.5的变更记录stopWhen、activeTools、output、experimental_repairToolCall、experimental_download等都可以在构造函数上设置默认值stream()级别传入的值会覆盖构造默认值。3.2 生成参数 GenerationSettingsGenerationSettingssrc/workflow-agent.ts定义了可传给模型的所有生成参数与LanguageModelV4CallOptions直接映射maxOutputTokens最大输出 token 数temperature/topP温度与核采样官方建议二选一设置topKTop-K 采样仅建议高级场景使用presencePenalty/frequencyPenalty范围-1到10表示无惩罚stopSequences停止序列数组provider 可能限制数量seed随机种子模型支持时可获得确定性结果maxRetries可重试失败的最大次数默认 2设为0禁用重试abortSignal取消操作信号headers附加 HTTP 头仅对 HTTP provider 生效reasoning推理努力程度从1.0.6起由WorkflowAgent转发给模型调用providerOptions透传给 provider 的专属选项。3.3 stream() 调用参数WorkflowAgentStreamOptionssrc/workflow-agent.ts在构造默认值之上提供流级覆盖并额外包含prompt或messages二者只能选其一prompt支持字符串或消息数组writable接收原始流块的WritableStreamModelCallStreamPartincludeRawChunks是否包含 provider 原始 chunktype: raw用于访问尚未被 AI SDK 封装的 provider 新特性默认falseexperimental_transform流变换可多个按顺序应用且必须保持流结构output结构化输出规格例如import { Output } from ai-sdk/workflow; import { z } from zod; const result await agent.stream({ messages: [...], writable: getWritable(), output: Output.object({ schema: z.object({ sentiment: z.enum([positive, negative, neutral]), confidence: z.number(), }), }), }); console.log(result.output); // { sentiment: positive, confidence: 0.95 }stream()返回的结果对象在1.0.17起增加了totalUsage与finishReason字段与GenerateTextResult/StreamTextResult对齐也包含在onEnd事件载荷中。四、步骤循环与上下文传递4.1 prepareStep每步动态干预prepareStep回调在每个步骤开始前调用返回的PrepareStepResultsrc/workflow-agent.ts中所有字段均可选只返回你想覆盖的部分model覆盖本步模型system覆盖本步系统消息messages覆盖本步消息用于上下文管理或消息注入toolChoice覆盖工具选择策略activeTools限制本步可用工具2.0.18起prepareStep.activeTools被限制为仅包含已配置的工具名runtimeContext/toolsContext返回新值以更新后续步骤的上下文experimental_sandbox覆盖沙箱。回调入参PrepareStepInfo包含stepNumber从 0 开始、steps此前所有步骤结果、messages将发给模型的LanguageModelV4Prompt、initialInstructions、initialMessages以及当前runtimeContext/toolsContext。4.2 prepareCall循环启动前的整体变换prepareCall在 Agent 循环开始前只调用一次src/workflow-agent.ts用于基于运行时上下文变换model、tools、instructions、toolChoice、stopWhen、activeTools、telemetry、messages等参数。注意tools无法通过prepareCall覆盖因为工具在构造期就已绑定以保证类型安全源码注释明确说明了这一点。1.0.62起prepareCall返回的maxRetries与abortSignal覆盖也会被真正执行。4.3 runtimeContext 与 toolsContext 的分离1.0.0对应 canary.41 变更引入了一次重要重构context被拆分为runtimeContext与toolsContext并移除了旧的experimental_context选项runtimeContext共享的 Agent 状态贯穿prepareCall、prepareStep、步骤结果与onEnd回调通过从prepareStep返回新值来更新toolsContext按工具键控的映射每个工具在执行时只会收到属于自己的、经过校验的条目作为context当工具声明了contextSchema时会按 schema 校验。由于上下文可能跨越工作流与步骤边界源码注释明确要求context 中的值应当可序列化serializable。4.4 stopWhen 取代 maxSteps1.0.0版本移除了maxSteps选项改为stopWhen配合停止条件如isStepCount()使用。当stopWhen为数组时任一条件满足即停止生成。2.0.20进一步修复了停止条件中工具与运行时上下文类型的保留问题2.0.21起stopWhen相关类型推断更加稳定。五、工具审批安全模型工具审批是WorkflowAgent在2.0.x系列中最核心的安全能力其演进路径非常清晰5.1 签名审批2.0.162.0.16在ai核心中引入签名工具审批。通过experimental_toolApprovalSecret配置一个环境变量名注意是变量名而非变量值const agent new WorkflowAgent({ model, tools, experimental_toolApprovalSecret: { environmentVariable: TOOL_APPROVAL_SECRET, }, });关键设计源码注释明确只有环境变量名会跨工作流边界序列化密钥值只在签名与验证步骤内读取从不被序列化。签名过程调用ai/internal的signToolApproval验证调用verifyToolApprovalSignature。5.2 审批重放漏洞与修复1.0.0 与 canary.87CHANGELOG 用较长篇幅记录了一个安全漏洞及其修复commitbae5e2b审批重放路径approval-replay path会从客户端提供的 messages 数组中重建已批准的approved工具调用并直接执行而不重新校验输入是否符合工具的 schema也不重新应用审批策略。攻击者可以伪造一条带有已批准工具调用部分的 assistant 消息让服务端以攻击者选定的参数执行工具。修复后的重放路径现在在配置了experimental_toolApprovalSecret时校验 HMAC 签名依据工具的输入 schema重新校验工具调用输入重新解析审批策略后再执行。5.3 复用核心审批校验1.0.0 / canary.87 的 69d7128为了避免逻辑重复导致的漂移WorkflowAgent.stream不再内联复制核心收集逻辑而是改用共享的collectToolApprovals收集审批并通过validateApprovedToolApprovals统一重新校验输入 schema 重校验、HMAC 签名验证、审批策略重解析两者现在从ai/internal导出。5.4 provider 执行工具的审批转发1.0.0 / canary.100修复了一个逆方向的 bug此前WorkflowAgent在恢复时会剥离所有tool-approval-request/tool-approval-response部分导致 provider 执行型工具如经 OpenAI Responses API 调用的 MCP 工具永远收不到审批结果。修复后本地执行工具的审批仍会被消费并剥离而 provider 执行工具的审批会被保留并转发给 provider。5.5 审批相关的流与重试行为2.0.18被批准的工具保留其上下文与生命周期回调2.0.8当重校验后的工具输入无效时以模型可见的工具错误继续当前generateText/streamText/WorkflowAgent回合1.0.52当兄弟工具因客户端执行或审批而暂停时已完成工具的结果仍会流入流。六、结构化输出结构化输出能力在 CHANGELOG 中多次出现1.0.61WorkflowAgent.stream()将结构化输出的响应格式response format转发给模型流调用2.0.21在流结果中推断构造级的结构化输出1.0.0eb49d29构造级output默认值流级覆盖构造默认值。使用方式即Output.object({ schema })或Output.text()从ai-sdk/workflow主入口导出。OutputSpecification接口src/workflow-agent.ts包含name、responseFormat、parsePartialOutput、parseCompleteOutput四个成员其中parseCompleteOutput可以拿到response、usage、finishReason元数据。onEnd回调与流结果中的output字段只在指定了output规格时可用。七、工具执行的模型输出与错误语义7.1 toModelOutput 钩子1.0.0 / canary.84WorkflowAgent现在会尊重每个工具的toModelOutput钩子本地执行、provider 执行与已批准的工具结果都会经由该钩子路由与generateText、streamText、ToolLoopAgent保持一致。此前钩子被忽略结果一律序列化为text或json。实现上复用了ai/internal的共享工具结果模型输出辅助函数并采用共享的getErrorMessage行为处理工具错误结果。7.2 非法工具调用的错误保留1.0.0 / beta.27 的 a0ca584修复了把非法工具调用当作合成成功结果发出的问题非法的工具调用现在以错误形式保留而不是被伪装成成功。7.3 失败工具执行的流式错误2.0.18失败的本地工具执行会以工具错误tool error的形式流入流而非中断整个流程或静默吞掉。八、流式传输、UI 消息与断线重连8.1 流数据模型ModelCallStreamPartsrc/do-stream-step.ts是流块的联合类型Experimental_LanguageModelStreamPart加上tool-approval-request携带approvalId、toolCallId、可选signature和reset-step。doStreamStep负责执行单步模型调用其选项与GenerationSettings对应含timeoutAt绝对超时。8.2 WorkflowChatTransport持久化流重连workflow-chat-transport.ts 提供了WorkflowChatTransport用于在重连时恢复持久化流。其核心难点是orphan UI chunk孤儿数据块当以负的initialStartIndex重连时游标很容易落在某个 part 的中间导致客户端在收到text-delta/tool-input-delta/*-end时因为没看到对应的*-start而崩溃。createOrphanFilter的实现要点text-start/reasoning-start记录 part idtool-input-start、自包含的tool-input-available/tool-input-error记录 toolCallId引用未见起点的text-delta/text-end/reasoning-delta/reasoning-end、tool-input-delta、tool-approval-request、tool-output-available/tool-output-error/tool-output-denied会被丢弃并输出一次性警告reset-step会清空已见集合注释明确说明这是尽力而为的安全网若想完整保留消息服务端应把流回卷到步骤边界step boundary。相关修复包括1.0.6修复 UI 消息流 part 框架重复或交错的持久化流写入不再以Received text-delta for missing text part崩溃1.0.17的重连修复148babc2.0.1使用 UI 消息 chunk 索引恢复变换后的流4233a40。8.3 步骤边界的流规范化2.0.9修复当另一个合并的 UI 消息流完成某一步骤时保留正在进行的 text 与 reasoning 部分并使工作流流规范化与显式 part 结束 chunk 对齐。1.0.17的e660e45则精简了doStreamStep的步骤边界载荷只返回最小原始聚合在步骤外重建StepResult而不是把完整StepResult与逐 chunk 数组都序列化进持久化事件日志——这直接关系到持久化日志的体积与恢复速度。九、持久化视频生成2.0.11aed8ff3引入的持久化视频生成是该包最有特色的能力之一README与 src/generate-video.ts 提供了完整说明。9.1 使用方式import { experimental_generateVideo as generateVideo } from ai-sdk/workflow/video; export async function videoWorkflow(prompt: string) { use workflow; const result await generateVideo({ model: klingai/kling-v3.0-t2v, prompt, }); return result.videos; }注意子路径导入ai-sdk/workflow/video在 package.json 的exports中声明源码入口为 src/video.ts。9.2 实现机制experimental_generateVideosrc/generate-video.ts的执行流程校验模型要求模型为字符串走 Gateway或支持原生 webhookspecificationVersion v4且handleWebhookOption ! null否则抛出Workflow video generation requires a model with native webhook support.启动视频生成startVideoStep通过createWebhook()创建 webhook 并传入webhookUrl同时自动注入idempotency-key格式aisdk_workflow_video_stepId两个内部 step 均设置maxRetries 0挂起等待工作流在await webhook处挂起、不消耗计算资源直到 provider 回调 webhook URL查询状态getVideoStatusStep使用experimental_getVideoStatus获取结果错误时抛出非 completed 时抛错返回 provider 数据不下载托管 URL返回结果合并了 start 与 status 两个阶段的 warnings。正如 README 所述工作流可以在后续独立步骤中持久化、复制或处理每个返回的视频 URL而无需将视频字节序列化穿过工作流。十、中断、重试与超时语义绝对超时1.0.67修复WorkflowAgent超时处理在持久化模型调用步骤内部强制绝对截止时间并将超时路由到中止处理重试不叠加1.0.68遵循WorkflowAgent模型调用重试设置不叠加工作流步骤重试同时模型流错误部分在已解析结果上暴露原始值不再重试持久化模型步骤中止信号传播2.0.19c143af4将 Agent 的中止信号传播给本地工具执行1.0.0的f32c750简化了mergeAbortSignals步骤重试清理2.0.0的 d3cc3fe当模型调用步骤被重试时清除部分的 UI 消息 partonAbort 回调携带此前所有已完成步骤的StepResult[]。十一、生命周期回调事件形状1.0.00455f24将回调事件与ToolLoopAgent对齐onToolCallStart/onToolCallFinish增加stepNumberonStepStart增加steps此前步骤结果数组onToolCallFinish采用判别联合discriminated union模式success: true/falseonToolCallFinish增加durationMs。当前完整回调集均以WorkflowAgentOn*前缀命名见 src/workflow-agent.tsonStart流开始前一次onStepStart每个步骤前2.0.18起提供稳定版本取代experimental_onStepStartonStepEnd每步完成后旧名onStepFinish1.0.0起更名onToolExecutionStart/onToolExecutionEnd工具执行前后2.0.24起在具体工具集上保留按工具细化的类型并导出回调事件类型onEndLLM 响应与所有请求的工具执行完成后携带steps、messages、text、finishReason、usage/totalUsage、runtimeContext、toolsContext、outputonError、onAbort。工具执行结束事件src/workflow-agent.ts是判别联合success: true时携带outputsuccess: false时携带error。在具体工具集上每个联合成员会把工具调用与其对应的toolContext、输出类型关联起来TypeScript 可以直接窄化。十二、上下文、指令与其他细节12.1 Instructions 类型1.0.0引入Instructions类型d775a57instructions可以是字符串、SystemModelMessage或SystemModelMessage数组使用消息形式时可携带 provider 专属选项如缓存。1.0.39还支持动态工具描述与流级指令。12.2 系统消息注入防护1.0.0b402b95WorkflowAgent默认拒绝prompt/messages内的系统消息与generateText/streamText行为一致以防范提示注入仅当allowSystemInMessages: true时才允许。12.3 可序列化 Schema 与工具过滤1.0.21统一从zod/v4导入与项目规范一致1.0.0fbea042用ai的共享experimental_filterActiveTools替换重复的filterTools/filterToolSet2.0.19尊重空的activeTools列表即显式禁用全部工具1.0.32在工具调用的对话消息中保留 assistant 文本1.0.01e4b350 相关工具结果的模型输出统一走共享辅助函数。12.4 遥测与可观测性1.0.0experimental_telemetry转正为稳定telemetry1949571TelemetrySettings更名为TelemetryOptions1.0.0id属性用于遥测标识与ToolLoopAgentAPI 对齐bf6c17b1.0.0修复stepNumber在遥测事件上的值使按步骤维护状态的集成如ai-sdk/devtools能正确按步骤键控状态81e68da1.0.56在语言模型调用结束回调与遥测 span 上暴露 provider 元数据1.0.0334ae5d步骤性能指标增加明确的 effective / input / output / total token 吞吐字段请求会附带ai-sdk-agentuser-agent 段用于用量归属75763b0。12.5 包工程化1.0.20c29e0d7将包标记为 ESM修复此前require(ai-sdk/workflow)报MODULE_NOT_FOUND声明的 CJS 入口从未发布的问题1.0.66c661693workflow/vitest与已安装的 Workflow 运行时对齐修复集成测试脚手架。十三、从源码结构理解包的全貌src 目录清晰地映射了上述能力文件职责src/index.ts主入口导出WorkflowAgent、Output、全部选项/回调类型、WorkflowChatTransport、toUIMessageChunk、normalizeUIMessageStreamParts等src/workflow-agent.tsWorkflowAgent类与全部类型定义约 3300 行src/do-stream-step.ts单步模型调用执行、流块类型、provider 执行工具结果捕获src/workflow-chat-transport.ts持久化流的客户端传输与重连orphan chunk 过滤src/to-ui-message-chunk.ts模型调用流 → UI 消息 chunk 转换src/normalize-ui-message-stream.tsUI 消息流 part 规范化src/generate-video.ts持久化视频生成webhook 挂起/恢复src/serializable-schema.ts工具 schema 的可序列化处理src/resolve-tool-context.ts工具上下文解析src/add-tool-results-to-conversation.ts工具结果回填对话src/stream-text-iterator.ts流文本迭代器测试覆盖同样完整可作行为验证依据workflow-agent.test.ts核心行为与类型、workflow-agent-e2e.integration.test.ts端到端、workflow-agent-stream-error.test.ts流错误语义、workflow-chat-transport.test.ts与workflow-chat-transport.stream-repair.test.ts重连与流修复、generate-video.test.ts与generate-video.integration.test.ts视频生成、workflow-agent-file-source-retention.test.tsprovider 顺序的文件/来源保留、workflow-agent-response-format.test.ts结构化输出格式、workflow-smoke.integration.test.ts冒烟。示例工作流定义位于 src/test/如calculate-workflow.ts、video-generation-workflow.ts、retrying-model.ts、serializable-video-model.ts、mock.ts可作为编写自定义工作流的参考模板。十四、升级到 2.x 的注意事项CHANGELOG 中与破坏性变更直接相关的记录Workflow 运行时2.0.0要求workflow5beta 标签不再支持 Workflow 4peerDependencies为workflow^5.0.0-beta.42maxSteps已移除1.0.0改用stopWhen 停止条件如isStepCount()上下文重构1.0.0experimental_context已删除使用runtimeContext共享与toolsContext按工具回调更名1.0.0onStepFinish→onStepEndonFinish→onEndonToolCall*事件更名为onToolExecutionStart/onToolExecutionEndexperimental_onStart/experimental_onStepStart已由稳定版本取代WorkflowAgentOn*前缀命名规范0e462a7system弃用推荐使用instructionsNode 版本最低 22支持 22、24、26。结语从1.0.0-beta.0到2.0.28ai-sdk/workflow的 CHANGELOG 本身就是一部如何把 Agent 做到生产可用的实践手册审批重放漏洞的修复展示了客户端消息永远不可信、执行前必须重新校验的安全原则runtimeContext/toolsContext的拆分展示了持久化场景下共享状态与工具隔离状态的边界设计WorkflowChatTransport的孤儿 chunk 过滤展示了持久化流在任意位置重连时如何保证客户端不崩溃。结合 README.md 与 src 源码阅读本文提到的每个能力点即可在自己的项目中正确构建具备持久化、审批、结构化输出与视频生成能力的生产级 Agent。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
