【智能体开发】《LangChain核心技术与LLM项目实践》_80.[第8章 Agent系统] Agent错误处理：异常捕获与重试机制

你的Agent又双叒叕崩了别让一时的网络波动或模型抽风毁掉整个业务流程今天咱们把LangChain Agent的错误处理扒个底朝天从异常捕获到智能重试手把手教你打造打不死的小强级Agent系统让你的LLM应用在异常风暴中依然稳如老狗Agent错误处理核心架构错误类型认知异常捕获机制智能重试策略优雅降级方案监控与日志体系企业级实战案例工具调用失败LLM响应异常逻辑错误try-except包裹回调函数拦截上下文保留指数退避熔断机制条件重试备用模型切换缓存兜底结构化日志链路追踪本文目录Agent错误类型全景扫描先搞清楚敌人是谁异常捕获的艺术别让Agent裸奔重试机制设计给Agent三次机会熔断与降级承认失败也是一种智慧监控与可观测性让错误无所遁形企业级实战构建防弹Agent架构嗨大家好呀我是你的老朋友精通代码大仙。接下来我们一起学习 《LangChain核心技术与LLM项目实践》震撼你的学习轨迹俗话说“常在河边走哪有不湿鞋”。咱们写代码就跟走夜路似的总会踩到坑。特别是最近这波AI热潮大家都在搞LangChain Agent你是不是经常遇到这种让人血压飙升的场景Agent正跑得好好的突然啪一下一个API超时或者模型突然抽风返回一堆乱码整个流程直接崩掉你看着终端那一堆红色的堆栈信息心里一万只草泥马奔腾而过更惨的是这种情况往往发生在半夜三点监控疯狂报警你顶着鸡窝头爬起来修bug那种绝望感懂的都懂。别担心今天咱们就来聊聊怎么让Agent学会自我疗伤。错误处理这个事儿说大不大说小不小但绝对是区分新手和大佬的分水岭。新手写的Agent像玻璃娃娃一碰就碎大佬写的Agent像打不死的小强越挫越勇。看完这篇文章我保证你的Agent能从林黛玉蜕变成终结者。Agent错误类型全景扫描先搞清楚敌人是谁在动手写try-except之前咱们得先明白Agent到底会犯什么病很多人一上来就是一通乱抓结果该处理的没处理不该处理的被吞了留下一堆幽灵bug。LangChain Agent的错误大致可以分为三大类工具调用失败、LLM响应异常、逻辑错误。这三类错误的处理方式完全不同搞混了就是给自己挖坑。工具调用失败是最常见的。你的Agent调了个搜索引擎API结果网络抖动超时了或者调了个计算器工具参数传错了格式。这种错误通常是暂时的重试一下就OK。但新手最容易犯的错误就是一刀切看到异常就抛结果明明只是网络闪了一下整个任务就挂了。LLM响应异常更棘手。有时候模型会返回空内容有时候返回的JSON格式不对还有时候直接给你来个我拒绝回答。这种错误不能简单地重试因为模型可能已经陷入了某种奇怪的思考模式盲目重试只是浪费token。你需要解析错误类型决定是重试、降级还是直接报错。逻辑错误是最隐蔽的。Agent陷入了死循环或者工具返回的结果和预期不符导致后续步骤全部跑偏。这种错误往往不会抛异常但结果却是灾难性的。很多新手在这上面栽跟头还傻傻地以为是模型能力不足。你可能觉得区分这些有什么用不都是报错吗错大了如果你把暂时性网络错误当成逻辑错误处理用户就会看到系统繁忙的提示体验极差如果你把逻辑错误当成网络错误重试三次用户就要等十几秒最后还是一个错更烦躁。正确的姿势是给错误贴标签可重试的、不可重试的、致命的。只有分类清楚你的异常处理策略才能有的放矢。异常捕获的艺术别让Agent裸奔知道了敌人是谁接下来就该穿上盔甲了。很多小伙伴写Agent代码的时候那叫一个勇猛直接裸奔没有任何try-except保护。问就是我代码没问题结果一上生产环境就原形毕露。LangChain提供了非常优雅的回调系统Callbacks这是捕获异常的第一道防线。你可以通过继承BaseCallbackHandler在on_llm_error、on_chain_error、on_tool_error这些钩子方法里统一处理错误。这比你在每个地方写try-except要干净得多。但这里有个大坑很多人喜欢裸吞异常。什么意思就是catch了Exception之后只是print一下或者干脆pass掉。这种做法简直就是给自己埋雷异常被吞了程序继续跑但数据已经脏了你最后得到的结果完全是错的还不知道错在哪。正确的做法是捕获-转换-传递。捕获底层异常转换成业务异常保留完整的上下文信息然后向上传递。比如工具调用失败了不要直接抛个TimeoutError上去而是包装成ToolExecutionError里面包含工具名称、参数、原始异常、时间戳等信息。这样上层处理的时候就能知道这是哪个环节出了问题需不需要重试。还有个小技巧使用上下文管理器。Python的contextlib可以让你写出超级优雅的错误处理代码。比如你可以写一个agent_error_handler的装饰器自动处理所有Agent运行时的异常记录日志决定重试策略。这样你的业务代码可以保持整洁错误处理逻辑全部解耦。记住异常捕获不是目的而是为了更好地处理。每一次捕获都应该有明确的目的是重试是降级还是终止如果没有后续动作那就别捕获让它崩至少你知道崩在哪。重试机制设计给Agent三次机会好了现在咱们来到了重头戏重试。网络不稳定、API限流、模型偶尔抽风这些问题都可以通过重试来解决。但重试是门技术活不是简单的while循环加sleep。首先重试次数要有上限。我见过有人写while True心想一直试总会成功的结果遇到致命错误程序直接死循环把API额度全部烧光账单出来的时候差点心梗。一般来说3-5次重试是合理的范围。其次重试间隔要指数退避Exponential Backoff。第一次等1秒第二次等2秒第三次等4秒以此类推。这样可以避免在API服务刚恢复的时候就被大量重试请求冲垮也就是所谓的 thundering herd 问题。Python的tenacity库是个神器一行代码就能搞定指数退避和 jitter随机抖动。更要命的是不是所有错误都值得重试。4xx错误客户端错误通常重试也没用比如参数错误、认证失败你再试100次还是错。只有5xx错误服务器错误或者网络超时才适合重试。所以你要在重试逻辑里加条件判断根据异常类型决定是否重试。LangChain里怎么实现呢你可以在工具层面包装重试逻辑也可以在AgentExecutor层面统一处理。我建议在工具层面做因为不同的工具可能有不同的重试策略。比如调用内部服务可以重试3次调用外部付费API可能只能重试1次省钱。使用装饰器模式你可以这样写fromtenacityimportretry,stop_after_attempt,wait_exponentialretry(stopstop_after_attempt(3),waitwait_exponential(multiplier1,min4,max10))defsearch_tool(query):# 可能失败的搜索逻辑pass这样写既优雅又解耦业务代码完全不需要关心重试逻辑。而且tenacity还提供了重试前的回调、重试后的统计等功能非常适合生产环境。但是重试也有副作用。它会增加延迟如果Agent链条很长每个环节都重试用户可能要等很久。所以还要设置超时时间重试总时长超过阈值就直接失败避免让用户干瞪眼。熔断与降级承认失败也是一种智慧有时候重试三次还是失败这时候该怎么办继续死磕到底吗不这时候就该熔断器Circuit Breaker登场了。熔断器模式借鉴了电路保险丝的概念。当错误率达到阈值时熔断器打开后续请求直接失败不再调用下游服务。这样可以防止雪崩效应保护系统资源。等过一段时间比如30秒熔断器进入半开状态放少量请求试探如果成功了就关闭熔断器恢复正常。在Agent系统里熔断器特别重要。假设你的Agent依赖某个知识库检索服务这个服务挂了如果没有熔断每个用户请求都会去试这个挂掉的服务超时等待资源被占满整个系统就瘫痪了。有了熔断后面的用户请求会立即收到服务暂不可用的响应系统还能保持部分功能可用比如用缓存数据或者备用模型回答。降级策略是熔断的好搭档。当主模型比如GPT-4不可用时能不能降级到GPT-3.5当实时搜索不可用时能不能用本地缓存的数据当工具调用失败时能不能让Agent直接用内部知识回答虽然可能不够准确但至少能给用户一个交代很多新手不愿意做降级觉得不够完美。但现实是Partial success 比 Total failure 要好得多。用户体验角度一个稍微有点瑕疵但能用的结果远比一个报错页面要强。实现熔断可以用pybreaker库或者自己基于Redis实现分布式熔断。关键是要记录失败次数、时间窗口还有熔断后的兜底逻辑。记得在降级时要给用户适当的提示比如当前使用离线模式信息可能不是最新的管理用户预期。监控与可观测性让错误无所遁形说了这么多防御措施但如果出问题了你都不知道那就是瞎子摸象。生产环境的Agent必须有完善的监控和日志体系。首先是结构化日志。别再用print了用structlog或者标准库的logging输出JSON格式的日志。每条日志要包含trace_id链路ID、agent_id、step_number、tool_name、latency、error_type等字段。这样出了问题你可以通过trace_id把一次完整的Agent调用链条串起来看看到底在哪一步出的问题。LangSmith是LangChain官方提供的观测平台强烈推荐接入。它可以自动记录每次LLM调用的输入输出、token消耗、延迟还有工具调用的详情。你可以设置监控规则比如错误率超过5%就发告警或者某个工具平均响应时间超过2秒就预警。但别只监控技术指标业务指标也很重要。比如Agent的任务完成率、用户满意度、Fallback触发频率。这些数据能帮你判断你的错误处理策略是否有效。如果重试次数设得太高可能完成率上去了但用户体验很差等太久如果熔断太敏感可能系统很稳定但功能可用性下降。还有一个容易被忽视的点错误分类统计。你要定期分析哪些错误最常发生是网络超时还是格式解析错误根据数据优化你的代码。比如如果发现80%的错误都是JSON解析失败那你就要改进Prompt工程让模型输出更稳定的格式。最后建立on-call手册。当告警响起时值班人员应该能快速定位问题查看哪个服务异常、是否需要人工介入、如何快速回滚或降级。没有手册的话半夜收到告警你就抓瞎了。企业级实战构建防弹Agent架构理论说了这么多咱们来实战一下看看怎么把这些东西组织成一个企业级的Agent系统。首先分层架构很重要。最底层是工具层每个工具独立封装包含自己的重试、熔断逻辑。中间是Agent层负责编排工具调用处理Agent级别的异常。最外层是API层处理请求认证、限流、全局错误返回。建议使用责任链模式处理错误。定义一个错误处理器链条先尝试重试不行就降级再不行就返回友好错误。每个处理器决定是否处理该错误不处理就传给下一个。代码组织上创建一个exception_handler模块里面定义所有自定义异常类和处理器。创建一个decorators模块包含with_retry、with_circuit_breaker、with_fallback等装饰器。业务代码保持简洁通过装饰器叠加能力。with_fallback(fallback_funcsimple_qa)with_circuit_breaker(threshold5,timeout60)with_retry(max_attempts3,exceptions(TimeoutError,))defcomplex_research_agent(query):# 复杂的Agent逻辑pass还有别忘了测试要写混沌测试Chaos Engineering故意让某些服务失败看看你的Agent能不能优雅处理。可以用pytest配合respxmock HTTP或者pytest-mock来模拟各种错误场景。最后文档化。把你的错误处理策略写进README包括有哪些降级方案、熔断阈值是多少、怎么查看日志。这样团队其他成员接手时不会一脸懵逼。写在最后看到这里你可能会觉得做个Agent怎么这么多事没办法生产环境就是这么残酷。你在本地跑通demo只是万里长征第一步能让Agent在异常风暴中屹立不倒才是真正的高手。记住错误处理不是锦上添花而是系统稳定性的基石。就像咱们的人生一样不可能一帆风顺关键是有没有 resilience韧性。你的Agent也一样要有韧性能容错能自愈。编程之路不易但每一步成长都算数。今天学会了给Agent穿盔甲明天你就能驾驭更复杂的系统。保持好奇持续学习你也能成为代码高手。相信自己你写的代码值得被世界温柔以待。获取更多学习资料请加微辛备注“资料代找获取”全网计算机学习资料代找例如:《课程2026 年多模态大模型实战训练营》《课程AI 大模型工程师系统课程 (22 章完整版 持续更新)》《课程AI 大模型系统实战课第四期 (2026 年开课 持续更新)》《课程2026 年 AGI 大模型系统课 23 期》《课程2026 年 AGI 大模型系统课 21 期》《课程AI 大模型实战课 8 期 (2026 年 2 月最新完结版)》《课程AI 大模型系统实战课三期》《课程AI 大模型系统课程 (2026 年 2 月开课 持续更新)》《课程AI 大模型全阶课程 (2025 年 12 月开课 2026 年 6 月结课)》《课程AI 大模型工程师全阶课程 (2025 年 10 月开课 2026 年 4 月结课)》《课程2026 年最新大模型 Agent 开发系统课 (持续更新)》《课程LLM 多模态视觉大模型系统课》《课程大模型 AI 应用开发企业级项目实战课 (2026 年 1 月开课)》《课程大模型智能体线上速成班 V2.0》《课程JavaAI 大模型智能应用开发全阶课》《课程PythonAI 大模型实战视频教程》《书籍软件工程 3.0: 大模型驱动的研发新范式.pdf》《课程人工智能大模型系统课 (2026 年 1 月底完结版)》《课程AI 大模型零基础到商业实战全栈课第五期》《课程Vue3.5Electron 大模型跨平台 AI 桌面聊天应用实战 (2025)》《课程AI 大模型实战训练营 从入门到实战轻松上手》《课程2026 年 AI 大模型 RAG 与 Agent 智能体项目实战开发课》《课程大模型训练营配套补充资料》