Mastra 工作流重试：让偶发故障不再拖垮整条 run

Mastra 工作流重试让偶发故障不再拖垮整条 run【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra跑 Mastra 工作流的人大概率遇到过这个场景一个 fetch 外部接口的步骤偶发超时整条 run 直接失败前面已经跑完的五个步骤全部作废只能手动从头重跑。Mastra 工作流重试就是为这类瞬时性故障准备的失败的步骤按你配置的次数和间隔重跑而不是让整条 run 陪葬。1 没有重试一条 run 能赔掉多少一次 fetch 超时步骤失败run 进入 failed 状态。上游调度的下一次调度要等几分钟期间用户侧已经感知到没结果。你手动重启后前面 5 个步骤含 LLM 调用原样重跑一遍token 和耗时全花第二次。重试机制只解决一件事把偶发失败和整条 run 报废隔开代价是几毫秒到几秒的等待。2 触发、行为、结果三段看懂机制这一节帮你建立准确的预期后面所有配置都建立在这个模型上。触发某个 step 抛出异常。引擎会先查这个 step 是否自己声明了重试通过error()配置没有则回落到工作流级的retryConfig两者都没配就按attempts 0处理即失败即停。行为以固定delay毫秒间隔重跑该步骤最多重试attempts次。注意是固定间隔不是指数退避别按后者的预期去调参。结果任意一次重试成功流程从该步骤继续往下走全部耗尽整条 run 才失败。已执行完的步骤不受影响不重跑。3 最小可用示例给 fetch 步骤加 3 行重试下面这段只覆盖最常见的场景一个调外部接口的步骤偶发超时。关键点全在error()的options里。const fetchStep createStep({ id: fetch-data, inputSchema: z.object({ url: z.string() }), outputSchema: z.object({ data: z.any() }), execute: async ({ context }) { const res await fetch(context.url); if (!res.ok) throw new Error(HTTP ${res.status}); return { data: await res.json() }; }, error: () error({ message: fetch failed, options: { retry: { attempts: 2, delay: 500 } } }), });attempts: 2表示重试 2 次连同首次一共执行 3 次。外部接口偶发超时2 次基本够用再高就是浪费。delay: 500表示每次重试前等 500ms。给对端一点恢复窗口又不至于让整条 run 的延迟失控。不写error()时走工作流级retryConfig默认是{ attempts: 0, delay: 0 }也就是不重试。所以配了没生效九成是写错了层级。4 不同场景怎么选参数这张表帮你按场景直接取值不用逐个参数试。场景建议配置理由外部 API 偶发超时attempts: 2delay: 500~1000ms2 次覆盖多数瞬时抖动总延迟增加约 1s本地确定性计算不配重试同输入必同结果重跑 100 次也是错批量任务中的单条失败低 attemptsdelay 调大单条慢恢复不影响整体吞吐LLM 调用限流429attempts: 3delay: 1000ms 起限流窗口通常秒级间隔太短白烧次数写操作发消息、扣款不配或极谨慎重试可能放大副作用先确认幂等核心原则一句话重试只用来对抗瞬时性故障确定性错误重试一百次也是错。5 高频翻车点自查这四个坑都是真实容易踩的按现象 → 原因 → 修法对号入座。现象attempts 写了 3失败时只看到重试了 1 次。原因step 级error()的 retry 会覆盖工作流级retryConfig你改的可能不是生效的那层。修法确认生效层级源码逻辑是 step 声明优先、工作流配置兜底。现象重试明明生效了但业务上还是错。原因步骤失败是确定性的比如参数缺失重试只增加耗时不改变结果。修法这类错误不配重试直接快速失败。现象delay 设了 1 秒重试还是立刻发生。原因delay 单位是毫秒delay: 1等于 1ms约等于没有。修法想要秒级等待就写delay: 1000起。现象日志里看不到重试痕迹不知道有没有生效。原因没在失败场景里实际验证过。修法本地让步骤前两次故意抛错确认第三次成功且 run 最终成功。下一步挑一条你线上最常超时的工作流按第 3 节的写法加一段error()重试配置然后故意制造一次失败验证它真的生效。机制源码在 packages/core/src/workflows/工作流级默认配置attempts: 0, delay: 0见 packages/core/src/workflows/default.ts行为边界以 retry 预算测试 为准。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考