AI Agent / 系统课时
捕获工具异常并设计重试
捕获工具异常并设计重试
工具失败后立即重试并不可靠:参数错误重试多少次都不会成功,业务失败通常需要换路径,只有暂时性异常才适合受控重试。本文把三类失败编码进 LangGraph 状态,并用条件路由限制重试次数、区分兜底和成功出口。
学习目标
- 能区分参数错误、业务失败与暂时性异常
- 能用状态记录错误类型、重试次数和最后错误
- 能让可恢复失败进入有限重试,不可恢复失败进入兜底分支
先把失败分成三类
参数错误表示调用本身不合法,例如缺少必填字段或值域错误;继续用原参数重试没有意义。业务失败表示工具正常执行,但业务规则拒绝请求,例如库存不足或账户被冻结。暂时性异常才是典型的重试对象,例如短时超时、连接重置或服务端限流。

分类的目的不是为了日志好看,而是让图能决定下一跳。状态里至少要保留错误类别、当前尝试次数和最后错误文本,重试策略才能被测试和限制。
用条件路由实现受控重试
下面的示例模拟一个工具前两次抛出暂时性异常,第三次成功。tool_node 负责捕获异常并写状态,route_after_tool 只决定成功、重试还是兜底。
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"])预期输出
3
订单状态:已发货这里 max_retries 表示最多尝试 3 次。如果第三次仍失败,条件路由会进入 fallback,不会出现第 4 次调用。
不可恢复错误不要原样重试
实际工具包装器可以在 except 分支中进一步把错误映射为 invalid_argument、business、temporary 等类别。参数错误应返回给模型修正参数,或者直接进入参数纠错节点;业务失败应把可解释的业务原因交给模型或用户;只有 temporary 才进入自动重试。
如果重试需要等待,应使用指数退避或服务端建议的等待时间,而不是紧密循环。重试次数、总耗时和幂等性也要一起考虑:对“创建订单”“扣款”这类有副作用的工具,如果接口不支持幂等键,自动重试可能造成重复执行。
验证兜底分支真的可达
把示例中的 max_retries 改为 2 再运行,第二次暂时性异常后就会进入 fallback。预期结果应变为尝试次数 2,并输出“转人工处理”的结果。这个检查很重要,因为很多重试图只验证“最终成功”,却从未验证上限耗尽后的路径。
受控重试的核心不是“多试几次”,而是让错误分类、次数上限和兜底出口全部成为图中的显式状态与分支。