智能体常见六个容错分类案例

容错的核心心智是不是所有错误都该用同一种方式处理。框架按谁来修、怎么修把故障分成六类每一类都有专属中间件或机制。先把这张全景图印在脑子里后面每个中间件都只是这张图的某一个格子。错误类型谁修策略中间件 / 机制瞬时错误网络、限流系统自动指数退避重试ModelRetryMiddleware·ToolRetryMiddlewareLLM 可恢复工具失败、解析错误模型转成错误 ToolMessage 让模型自己调整ToolErrorMiddleware需人介入缺信息、指令不清人暂停等人工补信息interrupt()/ 本章 10.1供应商宕机系统自动切到备用模型ModelFallbackMiddleware调用失控跑飞循环系统自动单次 run 内封顶调用次数ModelCallLimitMiddleware·ToolCallLimitMiddleware未知异常开发者直接抛出暴露 bug不加中间件让异常冒泡错误处理策略全景错误发生 → 分类 → 谁修 → 中间件 → 结果① 错误发生工具/模型/网络② 分类六类见上表③ 谁修系统/模型/人④ 中间件对号入座瞬时 → 自动重试宕机 → 自动降级可恢复 → 转错误ToolMessage 给模型失控 → 自动封顶未知 → 冒泡暴露分流图 5容错的第一性原理——错误先分类再决定谁修、用哪个中间件。六类故障各有归位不要企图用一种 try/except 包打天下生产案例电商订单处理 Agent某电商平台的订单处理 Agent 负责自动处理用户下单后的全流程查询库存、扣减库存、生成订单、发送确认邮件、更新物流状态。以下按六类故障逐一分析该 Agent 在真实生产环境中可能遇到的故障及应对策略。1️⃣ 瞬时错误网络抖动、限流场景Agent 调用物流 API 查询快递单号网络突然抖动请求超时。对策指数退避重试系统自动修from deepagents import create_deep_agent from langchain.agents.middleware import ToolRetryMiddleware agent create_deep_agent( modelopenai:gpt-4.5, middleware[ ToolRetryMiddleware( max_retries3, # 最多重试 3 次 backoff_factor2.0, # 退避系数 initial_delay1.0, # 首次等待 1 秒 tools[query_logistics], # 只对物流查询工具重试 retry_on(TimeoutError, ConnectionError), ), ], )效果第 1 次失败 → 等 1 秒 → 第 2 次失败 → 等 2 秒 → 第 3 次失败 → 等 4 秒 → 仍失败则上报。这种抖一抖就能过的错误系统自动修复用户无感知。2️⃣ LLM 可恢复错误工具失败、解析错误场景Agent 调用库存接口查询商品库存但接口返回了意外格式的数据如 JSON 中缺少stock字段导致模型解析失败。对策ToolErrorMiddleware将错误转成 ToolMessage让模型自己调整from langchain.agents.middleware import ToolErrorMiddleware def on_error(exc, request): return f调用 {request.tool_call[name]} 时返回数据格式异常{type(exc).__name__}。请检查参数后重试。 agent create_deep_agent( modelopenai:gpt-4.5, middleware[ToolErrorMiddleware(on_error)], )效果Agent 收到错误消息后会自动调整参数或换一种方式重试而不是直接崩溃。例如先查商品 ID 再查库存而不是直接查库存。3️⃣ 需人介入信息不足、指令不清场景订单中的商品已下架Agent 无法确定替代方案——是提供同款不同色、还是同品牌不同型号、还是直接取消订单对策interrupt() 暂停等待人工审批from deepagents import create_deep_agent from langgraph.checkpoint.memory import MemorySaver from langgraph.types import Command agent create_deep_agent( modelopenai:gpt-4.5, tools[check_stock, create_order, send_email], interrupt_on{ create_order: { # 订单创建前必须人工确认 allowed_decisions: [approve, reject, edit, respond], when: lambda req: 下架 in req.tool_call[args].get(product_status, ), }, }, checkpointerMemorySaver(), ) # 运行后发现下架商品暂停等待人工决断 result agent.invoke( {messages: [{role: user, content: 帮我下单那个已下架的 iPhone 15}]}, config{configurable: {thread_id: order-001}}, versionv2, ) if result.interrupts: iv result.interrupts[0].value # 人工决定换同款不同色还是取消 decisions [{type: edit, edited_action: { name: create_order, args: {product_id: iPhone15-Pro, color: 黑色, quantity: 1}, }}] result agent.invoke( Command(resume{decisions: decisions}), config{configurable: {thread_id: order-001}}, versionv2, )效果当 Agent 遇到自己无法决策的灰色地带时暂停等待人工介入而不是盲目执行导致客户投诉。4️⃣ 供应商宕机模型不可用场景OpenAI 的 GPT-4.5 突然宕机所有请求都返回 503。对策ModelFallbackMiddleware自动切换备用模型from langchain.agents.middleware import ModelFallbackMiddleware agent create_deep_agent( modelopenai:gpt-4.5, # 主模型 middleware[ ModelFallbackMiddleware( fallback_models[anthropic:claude-sonnet-5, google_genai:gemini-3.6-flash], # 按顺序尝试备用模型直到成功 ), ], )效果GPT-4.5 挂了 → 自动切 Claude → Claude 也挂了 → 自动切 Gemini。整个过程 Agent 无感知订单处理继续。这是供应商级的容错而非单次调用级。5️⃣ 调用失控跑飞循环场景Agent 陷入查库存 → 发现不足 → 查另一款 → 又不足 → 再查...的死循环几分钟内发起了 200 次工具调用烧光预算。对策CallLimitMiddleware封顶 RateLimiter限频from deepagents import create_deep_agent from langchain.agents.middleware import ModelCallLimitMiddleware, ToolCallLimitMiddleware from langchain.rate_limiters import InMemoryRateLimiter agent create_deep_agent( modelopenai:gpt-4.5, middleware[ ModelCallLimitMiddleware(run_limit30), # 单次调用最多 30 次模型调用 ToolCallLimitMiddleware(run_limit100), # 单次调用最多 100 次工具调用 ], checkpointerMemorySaver(), # thread_limit 需要持久化 ) # 另加频率限制防止被供应商限流 rate_limiter InMemoryRateLimiter( requests_per_second5, # 每秒最多 5 个请求 check_every_n_seconds0.1, max_bucket_size20, # 最多突发 20 个 ) model init_chat_model(modelopenai:gpt-4.5, rate_limiterrate_limiter)效果即使 Agent 逻辑炸了最多也只消耗 30 次模型调用 100 次工具调用不会烧掉整个月的预算。同时每秒 5 次限制防止被供应商封 IP。6️⃣ 未知异常开发者未预见的 Bug场景订单系统突然返回了一个奇怪的错误码E_ORDER_FROZENAgent 工具代码里没有处理这种情况。对策不加中间件让异常冒泡暴露给开发者# 不添加 ToolErrorMiddleware 的兜底 on_error # 或 on_error 中不处理该异常 def on_error(exc, request): if isinstance(exc, ValueError): return f参数错误{exc} # 其他异常 return None让异常冒泡 return None效果异常没有被吞掉而是直接抛出到应用的日志中。开发者从日志中看到E_ORDER_FROZEN意识到这是订单冻结场景于是在工具代码中增加处理逻辑在on_error中增加对应的异常处理如果用了except Exception吞掉这个 Bug 会被藏进模型上下文里导致同样的错误反复发生却没人知道原因。总结六类故障在电商 Agent 中的完整配置agent create_deep_agent( modelopenai:gpt-4.5, tools[check_stock, create_order, send_email, query_logistics], interrupt_on{ create_order: { # 订单创建人工审批 allowed_decisions: [approve, reject, edit], when: lambda req: 下架 in str(req.tool_call[args]), }, }, middleware[ # ① 瞬时错误 → 重试 ToolRetryMiddleware(max_retries3, tools[query_logistics]), # ② LLM 可恢复 → 转错误消息 ToolErrorMiddleware(on_error), # ④ 供应商宕机 → 切备用模型 ModelFallbackMiddleware([anthropic:claude-sonnet-5]), # ⑤ 跑飞循环 → 次数封顶 ModelCallLimitMiddleware(run_limit30), ToolCallLimitMiddleware(run_limit100), ], checkpointerMemorySaver(), # ③ 需人介入 → 暂停续跑 ) # ⑥ 未知异常不加兜底让异常冒泡到日志一句话总结六类故障各有各的专用工具——不要试图用一把锤子try/except敲所有钉子而是让每类错误去它该去的地方。