书名：《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》
作者：陈堂会
章节：第四章 工具系统设计 / 4.5 失败分类
电子版系列：查看完整目录
第四章 工具系统设计：4.5 失败分类
工具失败不应只有 error: string。至少分为：
| 类型 | 例子 | Runtime 行为 |
|---|---|---|
INVALID_ARGUMENTS | 参数缺字段、类型错 | 反馈模型重新调用 |
NOT_FOUND | 文件不存在 | 提示可选路径或要求搜索 |
PERMISSION_DENIED | 用户拒绝或策略拒绝 | 停止或让模型寻找低风险方案 |
TIMEOUT | 命令超时 | 截断输出，允许一次重试或降级 |
TOOL_CRASH | 工具内部异常 | 记录 trace，必要时停止 |
OUTPUT_TOO_LARGE | 日志过长 | 摘要后继续 |
SIDE_EFFECT_UNCERTAIN | 写入中断 | 进入恢复流程 |
失败分类不是为了把错误消息写得更漂亮。它让模型、runtime 和后续 eval 都能理解失败性质。
建议把失败分类写进工具开发规范，并要求每个工具的测试覆盖至少三类失败：参数失败、执行失败、输出过大。只测 happy path 的工具，进入 Agent Loop 后会把复杂性转嫁给模型。
