Session 16: error handling — what happens after the agent fails
Agent 的执行过程通常包含模型调用、工具执行、状态更新和多轮决策。任何一个环节出错,都可能影响整个任务
1. Agent 运行过程中会遇到哪些错误?
Agent 的执行过程通常包含模型调用、工具执行、状态更新和多轮决策。任何一个环节出错,都可能影响整个任务。
以 Research Agent 为例,它需要根据研究主题搜索资料、分析证据、判断材料是否充分,最后生成研究报告。搜索接口可能超时,模型可能返回错误的参数,搜索结果可能缺少关键信息,Agent 也可能因为一直认为证据不足而重复搜索。
这些问题看起来都是执行失败,但处理方式并不相同。网络超时可以尝试重试,参数错误可能需要模型调整调用方式,证据不足可能需要更换搜索策略,而涉及重要结论的数据冲突,则可能需要人工介入。
如果所有错误都采用同一种处理方式,系统很容易出现两个极端:遇到可以恢复的小问题就直接终止,或者遇到根本无法自动解决的问题仍然不断重试。
我倾向于先把错误分成几类,再决定由哪一层负责处理。
| 错误类型 | 典型场景 | 主要处理方式 |
|---|---|---|
| 模型调用错误 | 网络超时、限流、服务端错误 | 有限重试、退避、模型降级 |
| Tool 执行错误 | 搜索接口失败、数据库连接异常 | 程序重试、故障转换、备用工具 |
| 输入与参数错误 | 缺少必填参数、类型错误 | 程序校验,必要时让 LLM 修正 |
| 返回数据异常 | Schema 不匹配、关键字段缺失 | 校验、过滤、重新获取或人工处理 |
| 业务判断失败 | 证据不足、结果互相矛盾 | 调整策略、补充材料或暂停任务 |
| 流程控制错误 | 无限循环、调用次数过多 | 程序设置执行上限 |
| 状态与恢复错误 | 进程中断、外部操作结果未知 | 状态持久化、幂等、对账 |
这里需要区分两个概念:执行错误和任务无法完成。搜索接口返回空结果,可能是一次正常执行,并不意味着程序发生异常;如果 Agent 多次调整关键词仍然找不到证据,才可能需要结束当前研究任务,或者请求人工帮助。
2. 错误应该由谁处理?
Agent 中至少有三个参与者:程序、LLM 和人工。三者的职责需要明确。
程序擅长执行确定的规则。例如,遇到 HTTP 429 时等待一段时间再试,发现参数类型错误时拒绝执行,发现超过最大调用次数时停止任务。这些规则不需要交给模型判断。
LLM 更适合处理需要理解和调整策略的情况。例如,搜索关键词不够准确,可以重新组织查询;某个搜索工具不可用,可以选择其他工具;当前材料不足,可以分析还缺少哪些证据。
人工介入主要用于风险较高、信息不充分或无法可靠自动恢复的场景。例如,关键证据相互矛盾,自动生成的结论可能影响重要决策,或者外部操作已经发出请求,但系统无法确认操作是否成功。
可以把基本原则概括为:
- 程序负责执行边界、确定性校验、重试次数和终止条件。
- LLM 负责在允许的范围内调整任务策略。
- 人工负责高风险决策,以及系统无法可靠判断的情况。
这三者并不是互相替代的关系。LLM 可以提出新的执行方案,但程序仍然要验证这个方案是否允许执行。
3. LLM 调用失败:重试与降级
模型调用失败,首先需要区分错误类型。
如果是网络抖动、HTTP 429 或临时服务端错误,可以进行有限次数的重试。连续立即重试容易进一步加重服务压力,因此一般会采用指数退避,并增加随机抖动。
如果是鉴权失败、模型不存在等配置问题,反复请求通常没有意义。如果输入超过上下文窗口,也应该缩短上下文或调整请求,而不是原样重试。
下面是一个简化的 Python 示例:
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 调用搜索工具:
def search_web(query: str) -> dict: # 实际项目中调用搜索服务 ...
如果搜索服务临时不可用,可以由程序进行重试;如果参数缺失,可以返回明确的校验错误;如果搜索结果为空,可以让 Agent 判断是否需要换关键词。
达到重试上限后,可以把错误转换成模型能够理解的消息:
{ "error": True, "tool": "search_web", "error_type": "service_unavailable", "retryable": False, "message": "搜索服务连续失败,请考虑备用工具或结束当前步骤。"}
这个结构只是应用层的一种设计示例,并非所有框架都采用相同格式。核心是让 LLM 知道发生了什么、哪些尝试已经失败,以及它还有什么选择。
这里有两种不同的“重试”。
第一种是同一次操作的技术重试。程序重复执行相同的请求,希望网络或服务恢复正常。
第二种是Agent 调整策略后的再次尝试。例如搜索服务不可用,Agent 改用另一个工具;或者原来的关键词没有结果,Agent 根据已有材料生成新的关键词。
这两种机制应当分别控制。技术重试通常有明确的最大次数,而策略调整还需要受到总步数、总调用次数和任务预算的限制。
5. 返回数据异常:先校验,再决定如何恢复
Tool 返回了数据,不代表数据一定可用。
假设搜索工具返回的结果缺少来源链接,或者数据库查询结果中的字段类型不符合预期。程序应该先进行 Schema 校验,再决定是否将结果传给后续节点。
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 调用次数、最大运行时长和最大费用预算。
以一个简化的状态字段为例:
from typing import TypedDictclass AgentState(TypedDict): topic: str retry_count: int tool_call_count: int error: str | None status: str
每次执行 Tool 时,由程序更新 tool_call_count。在条件边中检查预算是否耗尽:
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 流程可以是:
调用模型
↓
模型决定调用搜索工具
↓
执行 Tool
├─ 成功 → 校验结果 → 更新研究状态
└─ 失败 → 分类错误
├─ 临时错误 → 程序重试
├─ 达到上限 → 反馈给 LLM
├─ 高风险异常 → 人工处理
└─ 超出预算 → 终止任务
这里的流程图描述的是应用设计。具体节点、异常类型和状态字段需要根据实际业务实现。
8. Checkpoint 与状态恢复
Checkpoint 用于保存图的执行状态,使流程能够在中断后恢复。但它不等于数据库事务,也不会自动撤销已经发生的外部操作。
例如,Agent 向第三方平台发布了一篇文章,平台实际上已经发布成功,但响应在返回途中丢失。此时图状态可能仍然显示发布步骤没有完成。
如果直接恢复执行并再次发布,就可能产生重复文章。
处理这类问题通常需要结合以下机制:
- 为每个业务操作生成唯一标识。
- 记录操作状态,例如
pending、succeeded、failed。 - 对重复请求使用幂等键或数据库唯一约束。
- 恢复时先核对外部系统的实际执行结果。
- 无法判断结果且重复执行风险较高时,暂停并交给人工处理。
所以,Checkpoint 解决的是图状态持久化和恢复问题;幂等、事务和业务对账解决的是外部副作用的一致性问题。
9. 有副作用的操作能否重试?
不能不加判断地重试,但也不意味着所有有副作用的操作都绝对不能重试。
查询操作通常比较容易安全重试。写入数据库、创建任务、发送邮件和发布文章等操作则需要进一步判断:如果第一次已经成功,只是响应丢失,再次执行会发生什么?
如果具备幂等机制,重复请求可以被识别为同一个业务操作,那么自动重试仍然可能是安全的。如果没有幂等保证,而且无法确认上次操作是否成功,就应该先查询执行结果,而不是直接重放请求。
对于发布文章、发送通知、支付等高风险操作,应该在设计阶段就明确操作标识、执行记录、结果查询和人工确认机制,而不是等到系统发生故障后再补救。
10. 总结
Agent 错误处理需要将程序的确定性控制与 LLM 的策略调整结合起来。程序负责错误分类、有限重试、超时、预算和终止条件;LLM 在允许的范围内调整关键词、工具选择和执行计划;人工介入关键数据冲突、高风险操作或无法可靠自动恢复的情况。
在 LangGraph 中,节点重试、ToolNode 错误处理、条件边和 Checkpoint 可以分别承担不同职责,但它们不会自动构成完整的错误恢复系统。真正的工程难点在于明确错误边界、避免重复执行、维护运行预算,并在恢复流程时确认外部操作的真实状态。