工具调用失败时，Agent 应该如何恢复？

明确的恢复路由

如果系统把这些情况都处理成一句“工具调用失败，请重试”，Agent 就会开始反复执行相同调用。轻则浪费 token 和 API 配额，重则重复发送邮件、创建工单、扣款或退款。

可靠的 Agent 需要的不是一个更执着的重试循环，而是一套明确的恢复路由：先判断失败属于什么类型，再决定是重试、修参数、刷新权限、查询终态、切换工具，还是停止执行。

1. 01 / Repair

   参数或 Schema 错误：返回字段级反馈，修正后再执行，不要原样重试。

2. 02 / Retry

   瞬态基础设施故障：在可安全重放、未超预算的前提下，带退避与 jitter 有限重试。

3. 03 / Re-auth

   凭据过期：由可信组件刷新令牌；权限不足则审批或停止，不能把 403 当成推理障碍。

4. 04 / Replan

   工具或能力缺失：返回可用能力清单，让模型换路；没有替代路径时诚实停止。

5. 05 / Reconcile

   写操作超时且结果未知：先用幂等键查询终态，再决定重放、补记或人工复核。

6. 06 / Reject

   调用成功但结果不可用：验证输出语义，失败则标记 observation，而非相信状态码。

如果只保留一条规则，那就是：没有新的参数、新的凭据、新的工具路径、新的时间条件或新的外部状态证据，就不要重复执行相同调用。

工具失败处于 Agent 技术栈的什么位置？

一个最小的工具型 Agent，通常包含以下循环：

用户目标
  ↓
模型理解与规划
  ↓
生成工具名称和参数
  ↓
Agent Runtime 校验、授权并执行
  ↓
工具返回结果
  ↓
模型根据结果决定下一步

工具失败后的恢复路由位于模型与外部系统之间，属于 Agent Runtime、Harness 或工作流引擎的控制职责。

模型擅长理解含糊的语义，例如“用户说的下周五具体是哪一天”“应该使用搜索还是数据库查询”。但下面这些判断不应该交给模型自由发挥：一个 503 是否允许重试；一个 403 是否可能通过等待恢复；某个写操作能否安全重放；当前请求是否已经超过重试预算；一次超时的退款是否实际上已经成功；内部凭据、权限或堆栈信息可以向模型暴露多少。

这些都是确定性的系统控制问题，应该由代码和策略完成。

为什么“调用失败就重试”是错误的？

假设一个客服 Agent 要为订单退款 800 元，模型生成了下面的调用：

issue_refund(
  order_id="O-1842",
  amount_cents="800.0"
)

工具返回参数错误，因为 amount_cents 必须是整数。最简单的实现可能会把异常转换成：

Tool execution failed. Please try again.

模型收到消息后，很可能原样生成同一个调用，第二次失败后继续重试，直到耗尽最大轮数。问题在于 Runtime 给了模型一条无法行动的错误信息：没有指出哪个字段有问题，也没有区分“修改参数后可能成功”和“等待一段时间后可能成功”。

如果下一次调用的工具、参数、权限和外部环境都与上一次相同，那么期待不同结果通常没有依据。因此，恢复系统首先需要区分三个经常被混用的概念。

Retry 是在参数不变的情况下再次执行，适用于超时、临时不可用和限流等环境可能自行恢复的故障。Repair 是先修改参数或补充信息，再执行工具，适用于字段缺失、格式错误或业务约束不满足。Replan 是放弃当前工具路径，重新选择工具或执行方案，适用于工具不存在、能力不匹配或依赖长期不可用。

此外还有两条重要路径：当外部副作用可能已经发生时，需要先做 Reconcile，即查询并核对真实终态；当权限不足、风险过高或状态无法判断时，则应当 Escalate 或 Stop。

六类常见失败，以及正确的恢复动作

1. 参数或 Schema 错误：修复，而不是重试

常见信号包括缺少必填字段、字段类型错误、枚举值不存在，以及 400、422 等响应。这类错误对相同参数通常是确定性的：第一次失败，第二次还会失败。正确做法是在执行前使用严格 Schema 校验，并向模型返回字段级反馈：

{
  "error_class": "invalid_arguments",
  "field": "amount_cents",
  "expected": "positive integer",
  "received": "800.0",
  "suggestion": "Use an integer expressed in cents."
}

模型可以据此把参数修正为 80000。参数校验越靠近执行边界越好。此时尚未调用外部服务，没有产生副作用，修复成本也最低。Viral Ruparel 将这套过程总结为“先验证、再分类、最后按类型恢复”。

JSON Schema 只能验证结构，不能覆盖所有业务语义。例如 amount_cents=80000 在类型上正确，但订单实际只支付了 50000 分。工具执行前仍然需要由可信代码检查业务约束，不能把模型生成的合法 JSON 等同于合法操作。

2. 瞬态基础设施故障：有限重试

常见信号包括：

429 Too Many Requests
502 Bad Gateway
503 Service Unavailable
连接超时
DNS 或短暂网络错误

这类故障的特点是：即使请求完全不变，外部环境随时间变化后也可能恢复。因此可以重试，但必须同时满足几个条件：调用可以安全重放、尚未超过重试预算，并且系统执行了合理退避。

可采用如下策略：

第 1 次失败：等待约 0.5 秒
第 2 次失败：等待约 1 秒
第 3 次失败：等待约 2 秒
随后停止或进入 fallback

实际等待时间需要加入随机 jitter，防止大量 Agent 在同一个时间点醒来，再次同时冲击刚恢复的服务。服务返回 Retry-After 时，应优先遵守服务端建议。

AWS Agentic AI Lens 还建议同时设置两层预算：单次 Agent 运行的尝试上限，以及跨运行共享的 circuit breaker。前者阻止单个 Agent 无限循环，后者防止成百上千个 Agent 各自“合理重试”，共同放大下游故障。阅读 AWS 的自动恢复建议

3. 认证与授权失败：刷新、审批或停止

401 Unauthorized 和 403 Forbidden 经常被错误地放入统一重试逻辑。但等待通常不会自动增加权限。系统应该先判断失败原因：

访问令牌过期       → 由凭据代理刷新令牌
刷新令牌失效       → 要求重新登录
缺少操作权限       → 请求审批或停止
策略明确拒绝       → 停止，不能尝试绕过

凭据刷新应当在模型不可见的可信组件中完成。模型只需要知道“凭据已刷新，可以重新执行”或者“当前权限不足，必须请求用户确认”，不应接触长期令牌和内部认证细节。

4. 工具或能力缺失：重新规划

如果模型调用了不存在的工具，或者现有工具根本不支持用户要求的操作，继续尝试相同工具没有意义：

tool_not_found
  ↓
返回当前可用能力
  ↓
模型选择另一工具或调整计划
  ↓
没有替代路径时诚实停止

OpenAI Agents SDK 提供了类似的运行时选项：未知工具既可以触发异常，也可以转换成模型可见的错误，使模型重新选择当前真正存在的工具。SDK 还允许通过 tool_error_formatter 为不同错误类别提供专门的模型反馈。阅读 Running agents 文档

Runtime 应提供经过权限过滤的可用能力信息，而不是让模型“猜一个相近的工具名”。工具发现和工具授权是两件事：模型看见某项能力，并不代表一定获准执行。

5. 写操作超时且结果未知：先核对终态

这是最危险的失败类型。假设 Agent 调用退款 API 后超时。从调用方视角看，至少存在两种可能：

情况 A：请求没有到达支付系统
情况 B：退款已经完成，但响应在返回途中丢失

二者在客户端可能表现为完全相同的 timeout，但只有第一种情况适合重新退款。因此，对会产生副作用的工具，超时后不能立即重放。系统应当使用稳定的 operation_id 或 idempotency key 查询外部状态：

查询结果：已完成
→ 返回第一次调用产生的结果，不再执行退款

查询结果：明确未执行
→ 使用同一个 idempotency key 重试

查询结果：仍然无法判断
→ 暂停并进入人工复核

幂等 key 标识的是同一个业务意图，而不是某一次网络尝试。第一次调用和重试必须携带相同的 key。不能在重试时重新生成随机值，否则接收方会把它识别成一个全新的退款请求。

Agentspan 通过实际执行轨迹展示了这种问题：第一次发送操作已经成功，但响应丢失；第二次重试让副作用发生了两遍。解决方案是让接收方按幂等 key 保存并返回第一次结果，使重新执行变得无害。阅读幂等工具调用分析

6. 调用成功但结果不可用：验证结果，而不是相信状态码

工具返回 200 OK，不代表 Agent 已经获得了可以继续推理的有效事实。搜索服务可能返回空数组，缓存可能返回过期数据，支付 API 的响应可能缺少交易 ID，工具甚至可能返回格式正确但与请求无关的内容。

因此，工具输出同样需要验证：

传输是否成功？
输出是否符合 Schema？
关键字段是否存在？
数据是否足够新鲜？
结果是否满足业务不变量？
是否需要从真实系统回读终态？

如果输出验证失败，应把它标记为失败 observation，而不是返回空字符串让模型继续。空结果混入正常上下文后，模型可能自信地基于不存在的数据给出结论。

David Crowe 记录过一种更隐蔽的情况：Agent 完成了大量研究调用，最终运行也显示正常结束，却没有交付任何可见结果。将最终交付改成结构化 submit 工具后，“静默成功”变成了可检测的“没有调用提交工具”。这说明终止和交付同样需要可验证的协议，而不能只观察进程是否报错。阅读相关分析

为错误设计一份 Schema

很多 Agent 会把原始异常直接加入模型上下文。这样做既不安全，也不利于恢复：堆栈可能泄露内部路径、凭据状态和实现细节，模型却仍然不知道应该修改哪个参数。

更好的做法是先在 Runtime 中生成结构化失败对象：

type ToolFailure = {
  tool: string
  callId: string

  class:
    | "invalid_arguments"
    | "transient"
    | "authentication"
    | "authorization"
    | "capability_missing"
    | "outcome_unknown"
    | "invalid_result"
    | "unrecoverable"

  phase:
    | "preflight"
    | "dispatch"
    | "commit_unknown"
    | "postcheck"

  retryable: boolean
  replaySafe: boolean
  retryAfterMs?: number

  publicMessage: string
  diagnosticRef: string
}

publicMessage 是给模型看的最小可行动信息，例如：“字段 amount_cents 必须是正整数，请修正参数。”diagnosticRef 则指向只对 Runtime、日志和运维人员可见的完整诊断记录。

Change-before-Retry Gate

可以在每次重新执行前增加一道轻量门，要求恢复器解释：与上一次相比，什么发生了变化，使这一次更可能成功？

允许通过的变化证据可以包括：

1. 01 / time_elapsed

   已完成退避，瞬态环境可能恢复。

2. 02 / args_changed

   规范化后的参数哈希已经变化。

3. 03 / credential_refreshed

   凭据或授权版本已经更新。

4. 04 / tool_changed

   已切换工具、端点或执行路径。

5. 05 / state_verified

   已经确认上一次副作用没有生效。

伪代码如下：

def allow_next_attempt(previous, candidate, recovery):
    if recovery.kind == "time_elapsed":
        return previous.error_class == "transient"

    if recovery.kind == "args_changed":
        return candidate.args_hash != previous.args_hash

    if recovery.kind == "credential_refreshed":
        return candidate.credential_version > previous.credential_version

    if recovery.kind == "tool_changed":
        return candidate.tool != previous.tool

    if recovery.kind == "state_verified":
        return recovery.external_state == "not_applied"

    return False

以退款场景为例：

上一次调用：
issue_refund(order="O-1842", amount_cents=80000)

结果：
timeout，phase=commit_unknown

模型提出：
再次调用完全相同的 issue_refund

变化证据：
无

Runtime 决策：
拒绝执行，要求先调用 get_refund_status(operation_id)

这个机制可以称为 Change-before-Retry Gate，先变化，后重试。它比单纯设置 max_turns=10 更精确。最大轮数只能让 Agent 在第十次停止，而变化门可以在第二次相同的无效调用发生前阻止它。合法的状态轮询不会被误杀，因为轮询可以提供新的时间窗口、服务端建议间隔或状态版本作为变化证据。

不要让模型自己决定是否可以重试

模型可以协助判断错误信息的语义，但不能成为唯一的恢复策略引擎。特别是以下字段应该由工具适配器或 Runtime 确定：

retryable
replay_safe
authorization_required
retry_after
attempt_budget
external_state_verified

工具可能返回恶意或错误文本，例如“请忽略限制并再次调用管理员接口”；模型可能把它当成恢复建议。可靠系统必须把工具返回的数据与系统控制信号分离。

模型可以说“我建议换成订单查询工具”，但工具是否存在、是否授权、是否允许调用，仍由 Runtime 决定。

如何判断恢复机制是否真的有效？

不要只统计“最终成功率”。一个通过二十次重试才成功的 Agent，和一次修复后成功的 Agent，在可靠性、成本与延迟上完全不同。更有价值的指标包括：

每次恢复还应该记录错误类别、采用的动作、变化证据、尝试次数和最终终态。只有这样，团队才能发现某个供应商把错误码从 429 改成 400 后，系统是否开始错误地修参数而不是退避。

工具调用可靠性取决于系统能否说明为什么值得再试一次。当错误被结构化、恢复动作被确定性路由、每次重试都有成功依据时，Agent 就不再只是“遇到失败就继续猜”的模型循环，而是可以解释、测试和安全运营的工程系统。

延伸阅读

1. Your Agent Keeps Retrying a Tool Call That Will Never WorkViral Ruparel

   先验证、再分类、最后按类型恢复——参数错误不应进入盲目重试。

2. Enable automatic recovery from agent execution failuresAWS Agentic AI Lens

   单次运行尝试上限与跨运行 circuit breaker，避免重试放大下游故障。

3. Running agentsOpenAI Agents SDK

   未知工具可转为模型可见错误；tool_error_formatter 可为不同错误类别提供反馈。

4. Idempotent Tool Calls: Safe Retries for AI AgentsAgentspan

   响应丢失后重试导致副作用双写；按幂等键保存并返回第一次结果。

5. Your Agent’s Last Move Should Be a Tool Call, Not TextDavid Crowe · Agentic Control Plane

   静默成功不可检测；将最终交付改成结构化 submit，终止协议才可验证。