跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 03

03-03|Tool 失败以后怎么办

把 Tool Failure 设计成稳定状态与恢复策略,覆盖 invalid input、not found、unauthorized、timeout、empty 和 malformed result。

Tool Failure · Error Handling · Recovery

“工具调用失败”不是一种错误

订单号格式错误时应请客户重新输入;订单不存在时应核对编号;未授权时必须停止;超时可以有限重试;空结果可能代表上游确实没有物流事件;畸形结果说明接口契约被破坏。

若这些情况都返回 Something went wrong,Agent 无法安全恢复。若全部交给模型自由解释,它可能在没有事实时补出一个看似合理的状态。

六类失败与恢复路径

invalid_input

参数格式或必填缺失

请客户补充或修正
not_found

范围内没有该订单

核对编号;不编造
unauthorized

身份或租户不允许

立即停止并安全说明
timeout

上游在预算内未响应

有限重试,再升级
empty_result

调用成功但没有事件

说明暂无可用数据
malformed_result

上游结果不符合契约

拒绝使用并告警
图 1|错误码把技术现象转换成可测试的系统状态;恢复策略由 Runtime 约束。

设计稳定的 Tool Result

成功与失败都使用可预测形状:

{
  "ok": false,
  "error": {
    "code": "timeout",
    "retryable": true,
    "safeMessage": "Tracking service did not respond in time."
  },
  "source": "carrier_sandbox",
  "requestId": "req_7f2"
}

safeMessage 可以进入模型 Context;内部 URL、堆栈、令牌和数据库细节不应进入。requestId 供日志关联,最终客户回复通常不需要展示。成功结果也要包含 source 和必要更新时间,便于判断事实新鲜度。

错误策略先于模型判断

Tool Result: error
↓
unauthorized / malformed?
YES → STOP + audit / alert
NO → retryable?
YES → budget available? → retry once → stop/escalate
NO → ask user / explain empty / escalate

图 2|硬边界由 Runtime 直接处理;模型只在安全选项中组织下一步。

invalid input

Schema 层应拦截大部分类型错误,业务层仍可能发现订单号格式不合法。返回字段级问题,让 Agent 精确追问,不要把原始数据库错误交给客户。

order not found

只说明在当前授权范围内未找到。不能透露该编号是否存在于其他客户或店铺,也不能自动尝试相邻编号。

unauthorized

立即停止当前查询,不重试、不换客户 ID、不让模型寻找替代工具。记录安全事件所需的最小元数据。

timeout

读取操作可以在预算内有限重试,采用退避并记录次数。达到上限后说明暂时无法确认,必要时建立人工跟进。

empty result

调用成功但物流事件数组为空,与 timeout 不同。最终回复应说“当前没有可用物流事件”,不能说“包裹仍在运输”。

malformed result

上游声称成功,但缺少契约字段或类型异常。系统拒绝使用该数据并告警;模型不负责猜字段含义。

防止模型在失败后猜结果

禁止

“物流接口暂时不可用,但您的包裹应该仍在清关。”

“应该”补出了工具没有提供的事实。
允许

“目前无法从承运商取得最新状态。我已记录此次查询;你可以稍后重试或转人工跟进。”

只陈述失败状态和可用下一步。
图 3|工具没有返回事实时,回复只能描述已知失败和恢复选项。

Failure Lab

所有错误都自动重试三次

为什么诱人: 一个通用策略实现简单。

为什么失败: unauthorized 重试是安全问题,invalid input 重试不会改变参数,动作工具重试还可能重复副作用。

更好的设计: 错误码携带 retryable,Runtime 按工具与错误类型设置预算。

把原始异常文本发送给模型

为什么诱人: 模型能帮助解释错误。

为什么失败: 堆栈、查询语句和内部地址可能泄露,且文本格式不稳定。

更好的设计: 在 Tool 边界映射成稳定安全错误,详细诊断留在受控日志。

not_found 后尝试猜相邻订单号

为什么诱人: 客户可能只输错一位。

为什么失败: 会探测其他订单并扩大越权风险。

更好的设计: 请客户核对编号,查询仍受当前身份范围约束。

实践:制作 Failure Contract

为订单与物流 Tool 分别填写六类错误:触发条件、是否可重试、最大次数、进入模型的安全信息、客户可见回复和最终状态。然后用 Mock 强制每种错误发生,检查 Agent 是否走到预定出口。

Acceptance Criteria

  • ☐ 六类错误均有稳定 code 与明确含义。
  • ☐ unauthorized 立即停止且不可重试。
  • ☐ timeout 只有有限重试并记录次数。
  • ☐ empty_result 与 timeout 的客户说明不同。
  • ☐ malformed_result 不会被模型补字段后继续使用。
  • ☐ Tool Result 不暴露堆栈、密钥或内部地址。
  • ☐ 最终回复没有工具未提供的订单或物流事实。
  • ☐ 每个失败路径都有自动测试与可观察 Stop Reason。

合上正文,试着回答

  1. 为什么 “tool_failed” 一个错误码不够?
  2. empty_result 与 not_found 有什么差别?
  3. 哪些失败绝不能交给模型自由恢复?
  4. Tool Result 中哪些信息适合进入 Context,哪些只应留在日志?
  5. 如何从测试上证明模型没有在失败后猜结果?

下一课会把 Schema、Runtime、Failure Contract 与 Mock 数据合在一起,让 V0.3 通过受控 Tool 查询订单和物流。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: 错误必须分类、可观察、有限恢复;没有工具证据就不生成业务事实。当前实现方式: SDK 的异常类和重试钩子会变化,业务错误契约应保持稳定。