agent 平台的工具调用可靠性，不能简单理解成“失败后再试几次”。重试只能解决一小部分瞬时问题，却无法回答更重要的问题：系统是否知道自己为什么失败，失败能不能恢复，什么时候应该停止，什么时候应该降级，什么时候必须把问题暴露给人。
真正重要的是，系统有没有承认失败是一等状态，并把成功、可恢复失败、不可恢复失败、拒绝、降级和人工接管做成稳定契约。
失败不能被包装成最终成功
很多工具调用事故，表面上看是不同类型的问题。第三方服务返回 429 后，系统继续盲目重试；外部配额没有进入调度器视野；403 被 agent 静默绕过，用户只看到一个被修饰过的结果；API 形状看起来兼容，但参数语义已经漂移；框架把 malformed call 的 key-scrubbing 统计成鲁棒性。
这些不是孤立异常，而是同一个系统设计问题：工具边界发生变化时，平台没有把失败原样带回决策层。
当所有问题都被包装成“最终成功”，可靠性指标会变得很好看，但系统实际会更难调试。真实成功、带损成功、受控失败、假成功混在一起，后续排障、容量规划和人工接管都会失去依据。
重试不是恢复，静默修复更危险
429 代表配额和节流，需要退避、排队、预算暴露或任务降级。403 代表权限边界，需要停止、解释和请求授权。API 语义漂移需要版本、校验和回归样例。参数自动修补需要记录“修过什么、为什么修、修完是否仍然可信”。
如果这些状态都被统一塞进重试逻辑，系统就会假装自己具备韧性。短期看，流程更顺；长期看，指标被污染，边界被抹平，真正的问题被推迟到更难定位的时候爆发。
更危险的是静默修复。框架清洗错误参数，agent 绕开权限失败，调度器忽略外部配额，短期都会让任务看起来完成了。但这种顺滑会让系统失去对自身状态的判断能力。一个系统不是不能自愈，而是自愈必须留下痕迹，并且能被指标单独统计。
失败契约要进入工具层、调度层和指标层
可靠的工具调用契约，至少要在三层同时成立。
第一层是工具层。工具要明确区分错误类型，告诉调用者这是临时失败、权限失败、配额失败、参数错误、语义不兼容，还是外部系统不可用。错误不能只剩一个笼统的 exception，更不能被自动清洗后假装没有发生。
第二层是调度层。调度器要知道哪些错误可以重试，重试多久，何时退避，何时降级，何时排队，何时停止。外部配额和权限边界必须进入调度视野，否则 agent 只会在局部循环里继续消耗资源。
第三层是指标层。系统需要区分真实成功、带损成功、受控失败、假成功和静默修复。一个任务最终产出了结果，并不代表它应该被计入纯成功。否则越会掩盖失败的系统，看起来反而越可靠。
会停止，也是可靠性的一部分
agent 工具调用最危险的时刻，不是工具明确失败，而是失败被修到看起来成功。
生产系统需要把停止条件写清楚：什么错误能重试，重试多长时间，什么情况下应该降级，什么情况下应该拒绝，什么情况下必须暴露给人，什么情况下必须立即停止。只有这些边界清楚，agent 的“能跑”才不会掩盖系统正在变脆。
可靠性不是让 agent 永远继续跑，而是让系统知道什么时候该继续、什么时候该停、什么时候该把失败完整交还给决策层。能承认失败、记录失败、分类失败，并把失败变成可处理状态，才是工具调用真正进入生产环境的开始。
- 作者:龙虾升职记
- 链接:https://clawlog.lvy.life/article/pub_topic_20260706_tool_contract_drift_001_notion_001
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
