11. Agent 的错误应该在哪一层处理

本次测试中，Claude Code 请求返回 403，Grok 返回 402。两者都没有进入工具调用。如果只记录 task_failed，这两条轨迹会与本地命令失败混在一起。

先按失败发生的位置分类

错误层级决定谁有能力修复。模型不能通过换一种措辞修正账户额度；执行器也不能通过重启进程修正一个缺失的工具参数。

重试还要判断是否可恢复

指数退避是让每次重试等待时间逐步增加的策略，适合临时限流和服务端异常。它不适合权限拒绝、参数确定错误或额度不足。

错误要保留机器字段与可读说明

工具只返回“失败了”，模型无法决定下一步；只返回原始堆栈，又会增加上下文并暴露内部路径。日志与模型回填可以分层：

• 日志保存错误类型、原始信息、调用标识、耗时和重试计数。
• 模型收到稳定错误码、必要说明和允许的下一步。
• 用户看到影响、可执行处理和相关证据。

三种受众需要的信息不同。

部分失败不能抹掉成功结果

并行调用中，一个成功、一个失败，应保存两项独立状态。模型可以利用成功结果继续完成部分任务，运行时也只需重试失败项。

若聚合层把整个批次改成失败，已完成动作会丢失，并可能在重试时重复执行。

失败也要有终止条件

每项任务应限制：

• 模型总轮次。
• 单工具重试次数。
• 总运行时间。
• 总 Token。
• 连续同类错误次数。

达到上限后进入明确终态，并说明哪一步未完成。没有终止条件的 Agent 循环会把确定性错误变成持续消耗。

Claude Code 与 Grok 的本次失败告诉我的不是产品能力高低，而是错误分层的重要性：两条请求都到达服务端，却停在不同账户或组织检查位置。比较最终答案之前，先确认轨迹是否进入了同一阶段。

退避策略需要抖动与预算

多个 Agent 同时遇到限流时，固定等待会让它们在同一时刻再次请求。抖动是在退避时间中加入随机范围，用来减少同步重试。运行时还要设置总重试预算，避免某个工具消耗整项任务的时间和 Token。

服务端给出 Retry-After 时优先遵守该值；没有提示时再使用带抖动的指数退避。每次重试保存错误类别、等待时间和剩余预算。

错误分类本身也要验证

适配器可能把 403 错误误归类为临时服务异常，或把工具超时包装成参数错误。回归集应包含真实或模拟的响应样本，并断言标准错误码、可重试性、副作用状态和用户提示。

当分类器无法确定时，默认进入不可自动重试的未知状态，比把所有未知错误都当作临时错误更安全。

重试要回答三个问题

原因是否会自行消失、重复动作是否安全、剩余时间与费用是否允许继续，三项共同决定下一步。HTTP 429 可能随时间恢复，却不证明已被接收的写请求可以直接重发；参数错误不会自行消失，但模型修改字段后可以继续。

指数退避逐步增加等待，抖动加入随机量，避免大量 Agent 同时重试。任务还要有总预算。报告分别记录尝试、模型修正、等待、执行和停止原因，不能把等待归入模型延迟。

错误回填提供机器错误码、字段路径、可公开摘要和受控诊断引用。完整调用栈可能泄露路径与秘密，“失败”两个字又不足以纠正。

故障矩阵覆盖结构错误、权限拒绝、资源不存在、限流、超时、服务端错误、结果解析和用户取消。每格明确下一步是改参、等待、查询状态、请求授权、停止还是交给用户。