AI Agent 工具调用返回结构化错误时怎么让模型重试

Agent 调用工具失败时，关键不是把整次模型请求无条件重放，而是让工具返回一份模型能理解的结构化结果：错误码说明原因，retryable 表示能否再试，attempt 限制次数，message 只暴露解决问题所需的信息。应用收到这份结果后，再把它和原始 call_id 一起回传给模型，模型才有机会修正参数或换一条路径。

可重试的业务错误最多给模型 2～3 次机会；参数、权限、余额和平台配额错误直接结束或走服务端退避。模型重试与 API 重试是两层机制，不能混成一个无限循环。

先把工具失败变成模型能读懂的结果

工具调用是一个闭环：模型提出调用，应用执行函数，再把工具结果发回模型。工具函数抛出的 Python 异常、数据库堆栈或 HTTP 原文并不是稳定的协议，模型可能把它当成普通文本，也可能反复用同一组参数调用。

建议统一返回如下结果。这里的字段是应用自己的协议，不依赖某一家 Agent 框架：

def error_result(code, message, retryable, attempt, retry_after=None):
    # 只返回模型修复任务所需的信息，不泄露内部堆栈和密钥
    return {
        "ok": False,
        "data": None,
        "error": {
            "code": code,
            "message": message,
            "retryable": retryable,
            "retry_after_seconds": retry_after,
        },
        "attempt": attempt,
    }

message 应该告诉模型下一步能做什么，例如“订单号不存在，请确认订单号”，而不是“系统异常”。retryable 表示是否值得让模型再次规划，不代表应用可以立刻重发网络请求。

错误码决定模型重试还是服务端退避

OpenAI 的工具定义可以用 JSON Schema 约束参数，严格模式要求对象关闭额外字段，并把属性标为必填；这能减少“参数根本无法解析”的调用。但严格参数校验解决不了库存不足、权限变化或上游超时，所以工具返回协议仍然需要单独设计。

回传原始 call_id，让模型有机会修正调用

在 Responses API 中，应用处理模型输出里的 function_call，执行工具后追加一个同 call_id 的 function_call_output。下一次请求带上这组输入，模型才能把错误和刚才的调用对应起来。

import json

MAX_MODEL_RETRIES = 2

def run_tool_turn(client, response, input_items, tools, attempts):
    # 保存模型原始输出，确保 function_call 与 output 成对回传
    input_items += response.output
    for item in response.output:
        if item.type != "function_call":
            continue
        args = json.loads(item.arguments)
        result = dispatch_tool(item.name, args, attempts.get(item.call_id, 0) + 1)
        attempts[item.call_id] = result.get("attempt", 0)
        input_items.append({
            "type": "function_call_output",
            "call_id": item.call_id,  # 必须对应这一次工具调用
            "output": json.dumps(result, ensure_ascii=False),
        })
    return client.responses.create(model="gpt-5.6", input=input_items, tools=tools)

代码里的计数不能只放在模型提示词中，因为模型看不到可靠的服务端状态。更稳妥的做法是按 task_id + tool_name 保存次数，并在 dispatch_tool 内部对副作用操作使用幂等键。只读查询可以重试，扣款、发货、写入工单等动作必须先确认幂等。

到达上限后要稳定收敛，而不是继续追问

把模型重试预算和网络重试预算分开记录。例如一次上游超时，HTTP 客户端可按 Retry-After 做 1～2 次退避；退避结束仍失败，再返回 UPSTREAM_TEMPORARY_FAILURE 给模型。模型最多看到两次同类错误，随后返回可读的降级答案或转人工。

日志至少记录 task_id、call_id、工具名、错误码、attempt、是否执行过副作用和最终状态。不要把完整工具参数、用户隐私或访问令牌原样写入日志。若错误是余额、项目额度或权限问题，继续调用不会改变状态，应直接提示运维或用户处理。

最后做一次反向验证：成功路径只产生一个有效副作用；可修正的参数错误能在预算内恢复；不可重试错误不会再次调用；达到上限后对话有明确结论。这样 Agent 的“会重试”才是受控的恢复能力，而不是把故障放大成调用风暴。

常见问题

工具返回 JSON 错误后，模型一定会自动重试吗？

不会。模型是否继续调用取决于错误内容、工具描述和对话上下文。应用应明确返回可行动的错误，并在服务端设置硬上限。

429 也应该设置 retryable=true 吗？

通常不要把平台配额错误交给模型循环。先遵守 Retry-After、降低请求速率并检查额度；恢复后再开启新的模型回合。

为什么不能只重发上一条模型请求？

重发可能重复工具副作用，也会丢失工具已经执行过的事实。应追加带原始 call_id 的工具输出，并用幂等键保护写操作。

把错误码、重试预算、模型可见信息和副作用状态分开，Agent 才能在“修正参数”“等待恢复”和“立即结束”之间做出可控选择。