Session 16: error handling — what happens after the agent fails

Agent 的执行过程通常包含模型调用、工具执行、状态更新和多轮决策。任何一个环节出错,都可能影响整个任务

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

1. Agent 运行过程中会遇到哪些错误?

Agent 的执行过程通常包含模型调用、工具执行、状态更新和多轮决策。任何一个环节出错,都可能影响整个任务。

以 Research Agent 为例,它需要根据研究主题搜索资料、分析证据、判断材料是否充分,最后生成研究报告。搜索接口可能超时,模型可能返回错误的参数,搜索结果可能缺少关键信息,Agent 也可能因为一直认为证据不足而重复搜索。

这些问题看起来都是执行失败,但处理方式并不相同。网络超时可以尝试重试,参数错误可能需要模型调整调用方式,证据不足可能需要更换搜索策略,而涉及重要结论的数据冲突,则可能需要人工介入。

如果所有错误都采用同一种处理方式,系统很容易出现两个极端:遇到可以恢复的小问题就直接终止,或者遇到根本无法自动解决的问题仍然不断重试。

我倾向于先把错误分成几类,再决定由哪一层负责处理。

错误类型 典型场景 主要处理方式
模型调用错误 网络超时、限流、服务端错误 有限重试、退避、模型降级
Tool 执行错误 搜索接口失败、数据库连接异常 程序重试、故障转换、备用工具
输入与参数错误 缺少必填参数、类型错误 程序校验,必要时让 LLM 修正
返回数据异常 Schema 不匹配、关键字段缺失 校验、过滤、重新获取或人工处理
业务判断失败 证据不足、结果互相矛盾 调整策略、补充材料或暂停任务
流程控制错误 无限循环、调用次数过多 程序设置执行上限
状态与恢复错误 进程中断、外部操作结果未知 状态持久化、幂等、对账

这里需要区分两个概念:执行错误和任务无法完成。搜索接口返回空结果,可能是一次正常执行,并不意味着程序发生异常;如果 Agent 多次调整关键词仍然找不到证据,才可能需要结束当前研究任务,或者请求人工帮助。

2. 错误应该由谁处理?

Agent 中至少有三个参与者:程序、LLM 和人工。三者的职责需要明确。

程序擅长执行确定的规则。例如,遇到 HTTP 429 时等待一段时间再试,发现参数类型错误时拒绝执行,发现超过最大调用次数时停止任务。这些规则不需要交给模型判断。

LLM 更适合处理需要理解和调整策略的情况。例如,搜索关键词不够准确,可以重新组织查询;某个搜索工具不可用,可以选择其他工具;当前材料不足,可以分析还缺少哪些证据。

人工介入主要用于风险较高、信息不充分或无法可靠自动恢复的场景。例如,关键证据相互矛盾,自动生成的结论可能影响重要决策,或者外部操作已经发出请求,但系统无法确认操作是否成功。

可以把基本原则概括为:

  • 程序负责执行边界、确定性校验、重试次数和终止条件。
  • LLM 负责在允许的范围内调整任务策略。
  • 人工负责高风险决策,以及系统无法可靠判断的情况。

这三者并不是互相替代的关系。LLM 可以提出新的执行方案,但程序仍然要验证这个方案是否允许执行。

3. LLM 调用失败:重试与降级

模型调用失败,首先需要区分错误类型。

如果是网络抖动、HTTP 429 或临时服务端错误,可以进行有限次数的重试。连续立即重试容易进一步加重服务压力,因此一般会采用指数退避,并增加随机抖动。

如果是鉴权失败、模型不存在等配置问题,反复请求通常没有意义。如果输入超过上下文窗口,也应该缩短上下文或调整请求,而不是原样重试。

下面是一个简化的 Python 示例:

text
import randomimport timedef call_with_retry(    call_model,    max_attempts=3,    base_delay=1.0,):    for attempt in range(max_attempts):        try:            return call_model()        except TransientModelError:            if attempt == max_attempts - 1:                raise            delay = base_delay * (2 ** attempt)            delay += random.uniform(0, 0.5)            time.sleep(delay)    raise RuntimeError("unreachable")

这里的 TransientModelError 是示意性的异常类型,实际项目中需要根据所用 SDK 将异常分类。call_model() 则代表具体的模型调用。

重试解决的是临时故障,降级解决的是当前模型持续不可用的问题。例如,主模型连续调用失败后,可以切换到备用模型。但切换模型前要确认备用模型具备当前任务所需的工具调用、上下文长度和结构化输出能力。

另外,模型请求超时不一定意味着服务端没有执行。对于普通文本生成,重复请求主要增加成本;如果调用链路还包含外部操作,就必须考虑重复执行带来的副作用。

4. Tool 执行失败:技术重试与策略调整

Tool 失败时,不能简单地把所有异常都交给 LLM。

例如,Research Agent 调用搜索工具:

text
def search_web(query: str) -> dict:    # 实际项目中调用搜索服务    ...

如果搜索服务临时不可用,可以由程序进行重试;如果参数缺失,可以返回明确的校验错误;如果搜索结果为空,可以让 Agent 判断是否需要换关键词。

达到重试上限后,可以把错误转换成模型能够理解的消息:

text
{    "error": True,    "tool": "search_web",    "error_type": "service_unavailable",    "retryable": False,    "message": "搜索服务连续失败,请考虑备用工具或结束当前步骤。"}

这个结构只是应用层的一种设计示例,并非所有框架都采用相同格式。核心是让 LLM 知道发生了什么、哪些尝试已经失败,以及它还有什么选择。

这里有两种不同的“重试”。

第一种是同一次操作的技术重试。程序重复执行相同的请求,希望网络或服务恢复正常。

第二种是Agent 调整策略后的再次尝试。例如搜索服务不可用,Agent 改用另一个工具;或者原来的关键词没有结果,Agent 根据已有材料生成新的关键词。

这两种机制应当分别控制。技术重试通常有明确的最大次数,而策略调整还需要受到总步数、总调用次数和任务预算的限制。

5. 返回数据异常:先校验,再决定如何恢复

Tool 返回了数据,不代表数据一定可用。

假设搜索工具返回的结果缺少来源链接,或者数据库查询结果中的字段类型不符合预期。程序应该先进行 Schema 校验,再决定是否将结果传给后续节点。

text
def validate_search_result(result: dict) -> dict:    required = ["title", "url", "snippet"]    missing = [        field for field in required        if not result.get(field)    ]    if missing:        raise ValueError(            f"搜索结果缺少必要字段: {missing}"        )    return result

实际实现可以使用 Pydantic 等数据校验库,将类型检查、必填字段和约束统一定义起来。

校验失败后,可以根据错误的影响决定处理方式:

  • 非关键字段缺失:过滤当前结果。
  • 有效结果数量不足:更换关键词或数据源。
  • 数据格式错误:尝试重新获取或修复可确定的字段。
  • 关键证据冲突:暂停结论生成,必要时交给人工确认。

对于 Research Agent,证据是否充分属于业务判断,数据是否符合约定格式则属于程序校验。两者可以协作,但不应混为一谈。

6. 无限循环必须由程序控制

LLM 可能反复调用同一个 Tool,也可能持续认为当前证据不足,导致流程一直运行。

仅仅在 System Prompt 中告诉模型“不要无限循环”是不够的。程序必须设置硬性上限,例如最大图执行步数、最大 Tool 调用次数、最大运行时长和最大费用预算。

以一个简化的状态字段为例:

text
from typing import TypedDictclass AgentState(TypedDict):    topic: str    retry_count: int    tool_call_count: int    error: str | None    status: str

每次执行 Tool 时,由程序更新 tool_call_count。在条件边中检查预算是否耗尽:

text
def route_after_tool(state: AgentState) -> str:    if state["tool_call_count"] >= 20:        return "stop"    if state["status"] == "needs_human":        return "human_review"    if state["status"] == "retry":        return "retry"    return "continue"

这里的数字只是示例。真实项目中,应该根据任务类型设置合理的限制,并确保计数不会因为异常分支或状态恢复而意外归零。

如果节点的重试次数和 Agent 的总调用次数都需要限制,应该分别维护。否则,一个节点虽然最多重试三次,但 Agent 仍然可能不断重新进入该节点。

7. LangGraph 中如何实现错误处理?

LangGraph 可以把错误处理组织成不同层次,而不需要将全部逻辑塞进单个节点。

机制 主要作用
RetryPolicy 对符合策略的节点异常进行重试
ToolNode 执行工具,并支持配置工具错误处理行为
条件边 根据状态决定重试、继续、降级或终止
自定义节点 实现业务校验、错误分类和预算检查
Checkpointer 持久化图状态,支持中断后的恢复
interrupt 在需要人工确认时暂停流程

RetryPolicy 和 ToolNode 的错误处理需要特别注意。假如 ToolNode 已经捕获异常,并把异常转换成普通的工具消息,那么从图节点的角度看,执行可能已经正常返回,外层节点重试策略就不一定会触发。

因此,需要明确每一层的职责:哪些异常由 Tool 内部重试,哪些异常由节点重试,哪些错误应该反馈给 LLM,哪些错误必须终止执行。

一个典型的 Research Agent 流程可以是:

text
调用模型
   ↓
模型决定调用搜索工具
   ↓
执行 Tool
   ├─ 成功 → 校验结果 → 更新研究状态
   └─ 失败 → 分类错误
               ├─ 临时错误 → 程序重试
               ├─ 达到上限 → 反馈给 LLM
               ├─ 高风险异常 → 人工处理
               └─ 超出预算 → 终止任务

这里的流程图描述的是应用设计。具体节点、异常类型和状态字段需要根据实际业务实现。

8. Checkpoint 与状态恢复

Checkpoint 用于保存图的执行状态,使流程能够在中断后恢复。但它不等于数据库事务,也不会自动撤销已经发生的外部操作。

例如,Agent 向第三方平台发布了一篇文章,平台实际上已经发布成功,但响应在返回途中丢失。此时图状态可能仍然显示发布步骤没有完成。

如果直接恢复执行并再次发布,就可能产生重复文章。

处理这类问题通常需要结合以下机制:

  • 为每个业务操作生成唯一标识。
  • 记录操作状态,例如 pending、succeeded、failed。
  • 对重复请求使用幂等键或数据库唯一约束。
  • 恢复时先核对外部系统的实际执行结果。
  • 无法判断结果且重复执行风险较高时,暂停并交给人工处理。

所以,Checkpoint 解决的是图状态持久化和恢复问题;幂等、事务和业务对账解决的是外部副作用的一致性问题。

9. 有副作用的操作能否重试?

不能不加判断地重试,但也不意味着所有有副作用的操作都绝对不能重试。

查询操作通常比较容易安全重试。写入数据库、创建任务、发送邮件和发布文章等操作则需要进一步判断:如果第一次已经成功,只是响应丢失,再次执行会发生什么?

如果具备幂等机制,重复请求可以被识别为同一个业务操作,那么自动重试仍然可能是安全的。如果没有幂等保证,而且无法确认上次操作是否成功,就应该先查询执行结果,而不是直接重放请求。

对于发布文章、发送通知、支付等高风险操作,应该在设计阶段就明确操作标识、执行记录、结果查询和人工确认机制,而不是等到系统发生故障后再补救。

10. 总结

Agent 错误处理需要将程序的确定性控制与 LLM 的策略调整结合起来。程序负责错误分类、有限重试、超时、预算和终止条件;LLM 在允许的范围内调整关键词、工具选择和执行计划;人工介入关键数据冲突、高风险操作或无法可靠自动恢复的情况。

在 LangGraph 中,节点重试、ToolNode 错误处理、条件边和 Checkpoint 可以分别承担不同职责,但它们不会自动构成完整的错误恢复系统。真正的工程难点在于明确错误边界、避免重复执行、维护运行预算,并在恢复流程时确认外部操作的真实状态。

On this page