Mastra 工作流错误处理与重试：3 步把失败步骤找出来、控制住
【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra
工作流跑到一半挂了，你不知道挂在哪个步骤、为什么挂、该不该再来一次——这是搭建 AI 工作流时最常见的三类问题。Mastra 的 TypeScript 工作流引擎把这三件事拆开处理：先用追踪面板定位失败步骤与具体报错，再按错误类型决定重试与否，最后通过 retryConfig 控制重试次数与延迟。下面按"先诊断、后治疗"的顺序讲清楚。
追踪面板怎么用：先定位到失败步骤和报错原因
不要看到"执行失败"就动手加代码。Mastra 的可观测集成会把工作流拆成 span，你在追踪面板里能直接看到某次 run 停在哪个步骤、该步骤抛出的错误是什么。
排查顺序建议固定为三步：
- 找到 runId 对应的 trace，确认失败步骤名
- 读该 span 的错误信息，区分是外部调用问题还是自身逻辑问题
- 对照历史 run，判断是偶发抖动还是稳定复现
稳定复现的错误重试没有意义，先修代码；偶发抖动才进入后面的重试设计。追踪入口的实现可以看 packages/core/src/workflows/ 里各引擎对 span 的封装，面板功能细节见 docs/src/content/en/reference/workflows/workflow.mdx。
哪些错误该重试、哪些不该：按错误类型划界限
把错误分成三类，处理方式不同：
- 外部调用类：上游 API 超时、连接中断、限流。这类瞬时问题占失败的大头，适合重试
- 业务逻辑类：输入 schema 校验不过、数据不满足预期。重试一万次结果也一样，应直接标记失败并落日志
- 系统资源类：内存不足、宿主负载过高。自动重试意义不大，更该触发告警让人介入
Mastra 给了两个配合使用的工具：context.retryCount记录当前步骤已重试的次数，用于"第 N 次之后放弃"；TripWire 的retry选项让你在运行时判断这次失败值不值得再来一次，而不必把所有异常一刀切。
重试次数和延迟怎么配：从固定间隔到按次数退避
工作流支持retryConfig，只有两个参数：attempts最大尝试次数，delay两次尝试之间的毫秒间隔。先写最简配置：
const wf = createWorkflow({ id: 'order-checkout', inputSchema: orderInput, outputSchema: orderOutput, steps: [charge, notify], retryConfig: { attempts: 2, delay: 3000 }, }).commit();这段配置的含义：整条工作流最多重试 2 次，每次间隔 3 秒。改attempts直接调整重试预算；把delay加大，则拉长与下游服务之间的恢复窗口。
对延迟有讲究的步骤，可以在步骤内部按retryCount自己算间隔，实现简单的递增退避：
// 重试越多，等得越久：第 1 次等 2s，第 2 次等 6s const backoff = 2000 * Math.pow(3, context.retryCount);固定间隔适合秒级抖动的调用；递增退避适合下游恢复需要更长时间、或者会持续限流的场景。
重试机制常见的三个坑：错误做法、后果和正确姿势
| 错误做法 | 后果 | 正确做法 |
|---|---|---|
| 把所有异常都标为可重试 | 业务逻辑错误反复空跑，浪费 token 与配额 | 先用追踪面板看原因，只对瞬时性错误开重试 |
| 把 attempts 调到很大图"永不失败" | 失败 run 越堆越多，排查成本上升 | 从 2 次起步，按一周追踪数据再调 |
| 用固定短间隔猛重试下游 API | 触发对端限流，失败率反而更高 | 用retryCount递增延迟，或加大 delay |
控制重试成本：并发、资源与告警怎么配
重试不是免费的，建议按下表管理：
| 项目 | 建议 |
|---|---|
| 次数 | 起步 2 次；追踪里确认某类错误重试成功率高，再逐步上调 |
| 间隔 | 外部 API 类错误用 2 秒起步的递增退避；本地逻辑错误直接失败 |
| 并发 | 限制同时重试的任务数，避免对下游打爆 |
| 资源 | 失败步骤的临时数据及时清理，避免内存堆积 |
| 告警 | 重试耗尽时推送通知，人工介入而不是继续硬试 |
三分钟总结
- 先看追踪，定位失败步骤和报错原因，再决定要不要重试
- 只重试瞬时性错误；业务逻辑错误直接失败
retryConfig只有 attempts 和 delay 两个参数，从 2 次、3 秒起步- 用
retryCount和 TripWire 的 retry 选项控制"何时放弃、何时再来" - 重试耗尽要告警，别让它静默地反复烧钱
下一步：把你手上最不稳定的一条工作流先设成attempts: 2, delay: 3000，跑一周后回看追踪面板里每个失败步骤的错误分布，再决定哪些步骤值得更高的重试预算。
【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
