工具调用失败时，Agent 应该怎样降级

Agent 的可靠性，往往不是看它成功时有多聪明，而是看它失败时怎么处理。

工具调用失败很常见：路径不存在、参数错了、网络超时、权限不足、接口返回格式变化。个人助理必须把失败当成正常路径，而不是异常意外。

不要假装成功

最坏的失败方式，是工具失败后继续输出成功结论。

例如构建命令失败，却说“已部署”；文件没写入，却说“已保存”；搜索不到资料，却编一个结果。这会直接破坏信任。

Agent 必须把工具返回结果当成事实来源，而不是只根据意图推断结果。

第一步：识别失败类型

失败先分类：

• 参数错误：输入格式、路径、字段不对。
• 权限错误：没有读写、执行或网络权限。
• 环境错误：命令不存在、依赖缺失、服务未启动。
• 网络错误：超时、DNS、API 不可达。
• 业务错误：接口返回成功但结果不符合预期。

分类之后，才知道能不能自动恢复。

第二步：有限重试

有些失败可以重试，例如网络超时或临时服务抖动。

但重试必须有限制。无限循环重试会浪费资源，还可能造成重复写入或重复请求。

一个简单规则是：

• 只对幂等或只读操作自动重试。
• 写入操作默认不自动重试，除非有明确幂等键。
• 重试次数固定，例如 1-2 次。
• 每次重试记录原因。

第三步：换工具或换路径

如果失败来自工具不可用，可以尝试替代路径。

例如 rg 不可用时用 PowerShell 搜索；Hugo 不在 PATH 时使用临时下载的二进制；网页无法访问时改用本地文件或缓存。

换工具前要保证语义一致。不能因为搜索失败，就把猜测当成搜索结果。

第四步：询问用户

当缺少关键信息，或者继续执行会改变外部状态时，应该停下来问用户。

适合询问的情况：

• 目标路径有多个候选。
• 需要凭据或人工登录。
• 操作可能覆盖现有数据。
• 高风险动作没有确认。
• 自动恢复会引入新假设。

询问不是失败，而是正确的降级。

第五步：记录失败

失败应该留下记录。

至少记录：

• 失败发生在哪个 Skill。
• 调用了哪个工具。
• 输入摘要是什么。
• 错误信息是什么。
• 是否重试。
• 最终是否需要人工处理。

这些记录以后可以变成 QPC 知识或维护手册。

降级决策表

个人助理的底线是：失败要可见，恢复要可解释，不能为了完成任务牺牲可靠性。