Agent 工具错误应该如何分类和处理？
简化版
Agent 工具错误不能统一成“调用失败然后重试”。至少要区分输入校验、认证、授权、限流、超时、上游不可用、业务冲突、部分成功、结果解析和结果不确定；每类对应修参、刷新凭证、停止、退避、查询状态、补偿或人工接管。错误协议应包含稳定错误码、可重试性、重试时间、影响对象和副作用状态，模型只负责基于这些事实选择下一步。
详细版
可将错误按“谁能修、重试是否安全、外部状态是否已改变”分类。参数缺失可让模型补齐；权限拒绝必须升级授权；429 和瞬态 5xx 可按服务建议退避；业务冲突要重新读取状态；写请求超时属于结果未知，必须凭幂等键查询，不能直接重放。
| 错误类 | 典型处置 | 能否原样重试 |
|---|---|---|
| VALIDATION | 修正字段 | 否 |
| AUTHN/AUTHZ | 刷新身份或申请权限 | 否 |
| RATE_LIMIT | 按 retry_after 退避 | 稍后可以 |
| TRANSIENT | 有上限地退避重试 | 通常可以 |
| CONFLICT | 刷新状态后重规划 | 否 |
| UNKNOWN_OUTCOME | 查询业务状态 | 不能直接重试 |
错误适配层将各工具私有响应转换成统一协议，同时保留原始 trace ID。调度器执行重试预算、熔断和死信；模型看到安全摘要及可选恢复动作。监控按错误类统计成功恢复率和无效重试率，避免某个工具故障引发 Agent 循环。
完整版教学
一、为什么一个 TOOL_ERROR 不够
“失败”可能意味着请求根本没发出，也可能意味着服务已经扣款但响应丢了。前者可以安全重试，后者直接重试可能扣两次。若错误协议抹平差异，模型再聪明也缺少正确决策所需事实。
分类的目标不是给日志贴更多标签，而是确定下一动作：谁负责修复、要不要等待、能否重试、是否需要补偿。分类结果应由工具适配器根据协议和业务状态产生，而不是让模型从模糊报错猜。
| 判断问题 | 可能结论 | 首选动作 |
|---|---|---|
| 请求字段不合法吗 | 输入错误 | 修正参数后重新校验 |
| 身份有权访问吗 | 认证或授权错误 | 刷新身份或停止并申请权限 |
| 外部状态改变了吗 | 已提交、部分提交或未知 | 查询、补偿或人工对账 |
| 故障会自行恢复吗 | 瞬态或永久 | 退避重试或立即停止 |
记忆钩子：先问“外部世界改变了吗”，再问“谁能修”，最后才问“要不要重试”。
二、输入与契约错误要修参数
缺少必填字段、类型错误、值超范围和 Schema 版本不兼容都属于调用前或服务端校验错误。原样重试不会改变结果，只会浪费预算。
错误对象应指出安全的字段路径和约束，例如 items[2].quantity must be <= 10。模型可据此修改候选参数，但涉及金额、收件人等高风险字段时要重新让用户确认。
工具注册阶段也应验证模型可见 Schema 与服务真实 Schema 一致。大量参数错误突然上升，可能是接口升级，而不是模型能力下降。
三、认证和授权必须分开
认证失败表示身份凭证缺失或失效，可能通过刷新 token 恢复；授权失败表示身份存在但无权访问资源，继续刷新或重试无效。把 401 和 403 都映射成“登录问题”会造成错误循环。
Agent 不应自行扩大权限。需要额外权限时进入明确审批或用户授权流程，并限制作用域和有效期。跨租户访问被拒绝应作为安全事件记录，不能把目标租户改成别的值来“修复”。
错误摘要不应包含令牌、密钥或完整内部策略。调试细节进入受控日志，模型只拿到恢复所需信息。
四、瞬态错误要退避且有预算
网络抖动、临时 5xx 和连接重置常可恢复，但立即并发重试会放大故障。指数退避加随机抖动能把请求摊开，并遵守服务端 Retry-After。
delay_n = min(cap, base × 2^n) + random_jitter若 base=1s、上限 8s，前三次大致等待 1、2、4 秒。每个动作和整个任务都要有重试预算；超过上限后熔断、换备用工具或转人工，不能无限等。
只有幂等读请求或带幂等键的写请求才适合自动重试。
五、业务冲突需要重新读取状态
版本冲突、库存变化、资源已存在和前置条件失败不是基础设施故障。它们说明 Agent 的观察已经过期，正确动作是读取当前状态并重规划。
例如更新文档时携带版本 7，服务返回当前版本 8。原样重试仍会失败；强行去掉版本条件可能覆盖别人的修改。Agent 应获取版本 8，计算新补丁，并在必要时让人解决语义冲突。
业务冲突应携带冲突对象和当前版本引用，但避免把无权查看的完整资源泄露出来。
六、部分成功必须精确描述副作用
批量发 100 封邮件，80 封成功、20 封失败，不能简单返回失败后整批重试。Observation 要列出成功项的稳定 ID、失败项及错误类，让补偿或重试只作用于失败部分。
{"status":"partial","succeeded":["m1","m2"],
"failed":[{"id":"m3","code":"RATE_LIMIT"}]}成功列表很大时可以存成 artifact，但摘要必须给出数量和范围。后续计划把部分结果当成整体成功同样危险，所以 partial 要成为一等状态。
七、超时后的结果未知最危险
客户端超时只说明没有按时收到响应，不说明服务端没有执行。付款、下单、发送消息等动作超时后，应使用幂等业务号查询状态。查询确认未执行，才能重试；确认成功则补记结果；持续未知则人工对账。
假设服务实际成功率 99%，响应丢失率 0.2%。一天十万次写调用约有 200 次处于“可能成功但客户端不知道”，足以造成大量重复副作用。
工具协议应明确 side_effect_state: none|committed|partial|unknown，让控制器作确定性处理。
八、统一协议仍要保留工具证据
适配层可输出 code、category、retryable、retry_after、side_effect_state、safe_message、trace_id。统一分类便于控制器通用处理，原始工具码和 trace ID 则支持排障。
监控应看各错误类数量、恢复成功率、平均重试次数、无效重试率和结果未知积压。若授权错误被重试率不为零，说明策略本身有 bug。
故障演练要模拟 429、连续 5xx、响应超时但服务成功、部分成功和错误 Schema，确认 Agent 不会循环或重复写。
九、常见误区与追问
- 误区：工具报错后统一重试三次最简单。 参数、权限和业务冲突不会被原样重试修复。
- 误区：超时就说明调用失败。 服务端可能已提交副作用，必须查询状态。
- 误区：HTTP 状态码足够表达错误。 业务冲突、部分成功和副作用状态需要领域错误码。
- 误区：让模型读堆栈最容易定位。 堆栈可能泄密且不稳定，应提供安全、结构化恢复信息。
- 误区：批量接口失败可以整批重放。 先识别成功项，只处理失败范围。
- 追问：哪些错误可以自动重试？ 明确瞬态且请求幂等，或写请求有稳定幂等键时。
- 追问：错误分类由谁负责？ 工具适配层基于协议负责，模型不应凭自然语言猜类别。
- 追问：如何防止重试风暴？ 指数退避、抖动、任务级预算、熔断和全局并发限制结合。
十、加强记忆
工具错误分类记住“参数要修、权限要停、限流要等、冲突要读、未知要查、部分要拆”：先确认副作用是否发生，再根据责任方选择修参、授权、退避、重规划或人工接管。统一错误协议给出稳定码、可重试性和副作用状态，控制器实施预算与熔断，模型只在这些事实之上选择恢复路径。