AI Agent / 系统课时

捕获工具异常并设计重试

捕获工具异常并设计重试

工具失败后立即重试并不可靠:参数错误重试多少次都不会成功,业务失败通常需要换路径,只有暂时性异常才适合受控重试。本文把三类失败编码进 LangGraph 状态,并用条件路由限制重试次数、区分兜底和成功出口。

学习目标

  • 能区分参数错误、业务失败与暂时性异常
  • 能用状态记录错误类型、重试次数和最后错误
  • 能让可恢复失败进入有限重试,不可恢复失败进入兜底分支

先把失败分成三类

参数错误表示调用本身不合法,例如缺少必填字段或值域错误;继续用原参数重试没有意义。业务失败表示工具正常执行,但业务规则拒绝请求,例如库存不足或账户被冻结。暂时性异常才是典型的重试对象,例如短时超时、连接重置或服务端限流。

工具异常分类与路由

分类的目的不是为了日志好看,而是让图能决定下一跳。状态里至少要保留错误类别、当前尝试次数和最后错误文本,重试策略才能被测试和限制。

用条件路由实现受控重试

下面的示例模拟一个工具前两次抛出暂时性异常,第三次成功。tool_node 负责捕获异常并写状态,route_after_tool 只决定成功、重试还是兜底。

python
from typing import Literal, TypedDict

from langgraph.graph import END, START, StateGraph

class TemporaryToolError(Exception):
    pass

class AgentState(TypedDict):
    attempt: int
    max_retries: int
    result: str
    error_kind: str
    last_error: str

def unstable_tool(attempt: int) -> str:
    if attempt < 3:
        raise TemporaryToolError("上游服务暂时不可用")
    return "订单状态:已发货"

def tool_node(state: AgentState) -> AgentState:
    attempt = state["attempt"] + 1
    try:
        value = unstable_tool(attempt)
        return {
            **state,
            "attempt": attempt,
            "result": value,
            "error_kind": "",
            "last_error": "",
        }
    except TemporaryToolError as exc:
        return {
            **state,
            "attempt": attempt,
            "error_kind": "temporary",
            "last_error": str(exc),
        }

def route_after_tool(
    state: AgentState,
) -> Literal["retry", "fallback", "__end__"]:
    if state["result"]:
        return END
    if (
        state["error_kind"] == "temporary"
        and state["attempt"] < state["max_retries"]
    ):
        return "retry"
    return "fallback"

def retry_node(state: AgentState) -> AgentState:
    return state

def fallback_node(state: AgentState) -> AgentState:
    return {
        **state,
        "result": f"工具失败,转人工处理:{state['last_error']}",
    }

builder = StateGraph(AgentState)
builder.add_node("tool", tool_node)
builder.add_node("retry", retry_node)
builder.add_node("fallback", fallback_node)
builder.add_edge(START, "tool")
builder.add_conditional_edges("tool", route_after_tool)
builder.add_edge("retry", "tool")
builder.add_edge("fallback", END)

graph = builder.compile()
result = graph.invoke(
    {
        "attempt": 0,
        "max_retries": 3,
        "result": "",
        "error_kind": "",
        "last_error": "",
    }
)
print(result["attempt"])
print(result["result"])

预期输出

text
3
订单状态:已发货

这里 max_retries 表示最多尝试 3 次。如果第三次仍失败,条件路由会进入 fallback,不会出现第 4 次调用。

不可恢复错误不要原样重试

实际工具包装器可以在 except 分支中进一步把错误映射为 invalid_argument、business、temporary 等类别。参数错误应返回给模型修正参数,或者直接进入参数纠错节点;业务失败应把可解释的业务原因交给模型或用户;只有 temporary 才进入自动重试。

如果重试需要等待,应使用指数退避或服务端建议的等待时间,而不是紧密循环。重试次数、总耗时和幂等性也要一起考虑:对“创建订单”“扣款”这类有副作用的工具,如果接口不支持幂等键,自动重试可能造成重复执行。

验证兜底分支真的可达

把示例中的 max_retries 改为 2 再运行,第二次暂时性异常后就会进入 fallback。预期结果应变为尝试次数 2,并输出“转人工处理”的结果。这个检查很重要,因为很多重试图只验证“最终成功”,却从未验证上限耗尽后的路径。

受控重试的核心不是“多试几次”,而是让错误分类、次数上限和兜底出口全部成为图中的显式状态与分支。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

捕获工具异常并设计重试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通