Mastra 工作流重试机制与错误处理实战retries 怎么配、不生效怎么查【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 工作流里一个步骤调用外部 API 偶尔返回 500 或超时是整条流程重跑还是只补跑失败的那一步Mastra 内置的重试机制给出的答案是步骤级失败会按配置次数自动重试已跑完的步骤输出不会丢而你不想重试的错误可以显式标记为不可重试。本文讲清楚重试策略配置、错误分类以及重试没生效时怎么排查。步骤偶发失败整条流程重跑还是只补跑失败步骤整条工作流重跑代价不小前面步骤已经写过的数据、调用过的接口要再执行一遍副作用无法忽略。Mastra 的做法是步骤粒度重试——当某个叶子步骤执行失败引擎只为它重新发布一次workflow.step.run事件事件里带着stepResults此前所有步骤的输出和递增后的retryCount。也就是说重试是补跑失败步骤不是重放整条流程这是理解后面所有配置的前提。Mastra 重试策略配置retries 参数写在哪重试参数有两个位置步骤级retries写在createStep的定义里只对这个步骤生效工作流级retryConfig.attempts写在createWorkflow里作为所有步骤的默认值。生效优先级是步骤级覆盖工作流级两者都没配时默认 0即失败即终止、不重试。这里有个容易踩的坑retries表示重试次数而不是总执行次数retries: 3意味着该步骤最多执行 4 次1 次原始 3 次重试。import { createStep, createWorkflow } from mastra/core/workflows; const callApi createStep({ id: call-api, retries: 3, inputSchema: z.object({ url: z.string() }), outputSchema: z.object({ data: z.any() }), execute: async ({ inputData }) fetchJson(inputData.url), }); const flow createWorkflow({ id: report-flow, retryConfig: { attempts: 2 }, steps: [callApi] });想要指数退避用上下文里的 retryCount 自己算延迟核心重试循环没有内置延迟上一次失败后下一次重试会立即发起。如果需要工作流指数退避这类策略比如等限流窗口过去再试可以用execute上下文里的retryCount自己控制execute: async ({ inputData, retryCount }) { if (retryCount 0) { await sleep(Math.pow(2, retryCount) * 1000); // 2s → 4s → 8s } return fetchJson(inputData.url); }固定间隔就把这一行换成常量延迟即可。退避逻辑写在步骤内部好处是它和重试计数天然对齐不用额外状态。错误类型识别用 MastraNonRetryableError 划清可重试边界重试不是越多越好。对参数校验失败、业务规则不满足这类永久性错误重试 3 次也是浪费。Mastra 提供了MastraNonRetryableError步骤里抛出它该步骤的执行结果会被打上nonRetryable标记引擎不会再重试。适合重试也没用的场景比如无效的模板 ID、鉴权失败。而网络超时、429 限流、5xx 这类瞬时错误抛普通错误即可由引擎按retries配置处理。需要结构化分类时MastraError还带 domain / category 字段方便在监控端按错误类型聚合。Mastra 错误追踪从 stepResults 和追踪视图看到每一次重试stepResults 里看每一步的状态与错误运行结束后stepResults中每个步骤都有status和error字段失败结果上还能看到nonRetryable标记。每一次重试对应一组workflow.step.run/workflow.step.end的 pubsub 事件想接自定义告警比如重试耗尽时发通知订阅这些事件就够了。接入 observability 后在追踪视图里定位失败接入mastra/observability后每次工作流运行会生成 trace每个步骤的执行是其中的 span重试过程在追踪视图里逐次可见失败步骤的异常信息直接挂在对应 span 上。仓库的 observability/ 目录 下有 mastra、langfuse 等多个 provider 实现可按需选择。重试没生效怎么排查三种不重试的判定引擎的停止条件就一条retryCount retries或结果被标记nonRetryable。对照排查通常是这三种情况根本没配重试——步骤级retries和工作流级retryConfig都为空默认就是 0 次重试抛了不可重试错误——步骤内部抛出了MastraNonRetryableError重试被强制跳过次数口径误解——retries: 3是重试 3 次、共执行 4 次第 4 次失败属于预期内不是没重试。排查顺序建议先在运行详情或追踪视图里数该步骤实际执行了几次再确认错误是否带nonRetryable标记最后核对配置是否写在了正确的工作流对象上。高频问题问重试会从头重跑整条工作流吗不会。只有失败的步骤被重新发布执行之前步骤的输出通过stepResults原样传入失败步骤拿到的输入仍然是上游输出不会二次触发。问配了 retries 但第一次失败就停了先查什么按顺序查三处抛出的错误是不是MastraNonRetryableError会强制不重试这个retries是否写在支持重试的条目上step、agent、tool 条目支持mapping 条目不支持工作流级retryConfig是不是配到了另一个 workflow 上。延伸阅读步骤定义与 retries 字段、MastraNonRetryableError 定义。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
