第23章 错误处理与容错：智能体执行失败时的兜底策略

错误处理与容错：让智能体在异常中优雅生存

智能体应用是一个复杂的系统，涉及大模型调用、工具调用、网络请求、数据处理等多个环节。任何一个环节都可能出错——大模型返回格式错误、工具调用超时、网络中断、API限流、数据缺失、用户输入异常……如果没有完善的错误处理和容错机制，智能体应用会频繁崩溃，用户体验极差。

本章将系统学习智能体应用的错误处理与容错设计——常见错误类型、错误检测、重试机制、降级策略、熔断机制、人工介入、优雅失败。

一、智能体应用的常见错误类型

1.1 大模型相关错误

• 格式错误：大模型没有按要求的格式输出（如要求JSON但输出了自然语言），导致下游解析失败
• 内容错误：大模型输出了错误的内容（如编造事实、错误推理、答非所问）
• 超时：大模型响应时间过长，超过了设置的超时阈值
• 限流：调用频率超过了API的限流阈值，返回429错误
• 服务不可用：大模型服务宕机或维护，返回5xx错误
• 上下文超长：输入的上下文超过了模型的最大窗口限制，返回错误
• 内容过滤：输出触发了内容安全过滤，被截断或拒绝

1.2 工具调用相关错误

• 参数错误：大模型生成的工具调用参数不符合要求（类型错误、缺少必填参数、参数值越界）
• 工具不存在：大模型调用了一个不存在的工具
• 执行超时：工具执行时间过长，超过超时阈值
• 执行失败：工具内部执行出错（如数据库查询失败、API调用失败、文件读写失败）
• 返回格式错误：工具返回的数据格式不符合预期，导致大模型无法理解
• 权限不足：工具需要特定权限，但当前用户或智能体没有权限

1.3 网络与系统错误

• 网络中断：网络连接断开，无法访问外部服务
• DNS解析失败：域名无法解析
• 连接超时：无法建立连接
• 数据库故障：数据库连接失败、查询超时、死锁
• 内存溢出：处理大量数据时内存不足
• 磁盘满：存储空间不足，无法写入文件

1.4 用户输入相关错误

• 输入为空：用户没有输入任何内容
• 输入过长：用户输入超过了最大长度限制
• 输入格式错误：用户输入的格式不符合要求（如要求数字但输入了文字）
• 输入包含恶意内容：用户输入包含提示词注入、SQL注入、XSS等恶意内容
• 需求不明确：用户的需求模糊不清，智能体无法理解

1.5 业务逻辑错误

• 数据不存在：查询的数据不存在（如用户输入了错误的设备编号）
• 状态冲突：当前状态不允许执行该操作（如工单已关闭，不能再修改）
• 业务规则违反：操作违反了业务规则（如库存不足、超出权限范围）
• 并发冲突：多个用户同时操作同一资源，导致冲突

二、错误处理的核心原则

原则一：快速失败（Fail Fast）

在错误发生的第一时间就检测到并处理，不要让错误传播到下游，导致更严重的问题。

实践：在每个环节都做输入校验和错误检查，发现错误立即处理或上报，不要"带病运行"。

原则二：优雅降级（Graceful Degradation）

当某个功能不可用时，不要整个应用都崩溃，而是降级到一个更简单但仍可用的状态。

实践：大模型API不可用时，降级到基于规则的简单回答；高级功能不可用时，降级到基础功能。

原则三：用户友好（User Friendly）

错误信息要对用户友好——不要暴露技术细节（如堆栈跟踪、数据库错误），要用用户能理解的语言说明发生了什么、该怎么办。

实践：内部记录详细的错误日志（方便开发排查），对用户显示简洁友好的错误提示（如"抱歉，服务暂时不可用，请稍后重试"）。

原则四：可观测性（Observability）

所有错误都要被记录和监控，方便开发人员发现问题、排查原因、持续优化。

实践：记录错误日志（时间、类型、消息、堆栈、上下文），设置错误告警（错误率超过阈值时通知开发），建立错误仪表盘（实时查看错误情况）。

原则五：自动恢复（Auto Recovery）

对于临时性错误（如网络抖动、API限流），自动重试恢复；对于永久性错误，降级或转人工。

实践：网络错误自动重试（指数退避），限流错误等待后重试，永久性错误降级处理。

原则六：安全可控（Safe and Controllable）

错误处理不能引入安全风险——不能因为错误处理而泄露敏感信息、不能绕过安全检查、不能执行未授权的操作。

实践：错误信息中不包含敏感数据，降级功能仍然遵守安全规则，高风险操作即使出错也不能自动执行。

三、重试机制

3.1 哪些错误可以重试

不是所有错误都适合重试。需要区分临时性错误和永久性错误：

• 可重试的临时性错误：网络超时、连接中断、API限流（429）、服务暂时不可用（503）、数据库死锁、并发冲突
• 不可重试的永久性错误：参数错误（400）、未授权（401）、禁止访问（403）、资源不存在（404）、业务规则违反、输入格式错误

对于永久性错误，重试没有意义，应该直接报错或降级处理。

3.2 重试策略

策略一：固定间隔重试

每次重试之间等待固定的时间（如每次等待1秒）。简单但不够智能——服务端压力大时，固定间隔重试可能加剧压力。

策略二：指数退避（Exponential Backoff）

重试间隔按指数增长（如1秒、2秒、4秒、8秒），给服务端更多恢复时间。这是最常用的重试策略。

公式：等待时间 = min(基础间隔 × 2^(重试次数-1), 最大间隔)

示例：基础间隔1秒，最大间隔30秒 → 1秒、2秒、4秒、8秒、16秒、30秒、30秒……

策略三：指数退避 + 抖动（Jitter）

在指数退避的基础上，增加随机抖动（如±20%的随机值），避免多个客户端同时重试导致"惊群效应"。这是生产环境推荐的策略。

公式：等待时间 = min(基础间隔 × 2^(重试次数-1) × (1 + random(-0.2, 0.2)), 最大间隔)

3.3 重试的最佳实践

• 设置最大重试次数：不要无限重试，一般重试3-5次。超过最大次数后，降级或报错。
• 设置超时：每次调用都有超时限制，避免长时间等待。整体重试也有超时限制。
• 幂等性保证：重试的操作必须是幂等的——多次执行的结果和一次执行相同。非幂等操作（如创建订单、发送邮件）重试时要小心，可能导致重复执行。
• 重试日志：记录每次重试的原因、次数、间隔、结果，方便排查问题。
• 区分错误类型：只对临时性错误重试，永久性错误直接报错。
• 用户感知：如果重试时间较长，给用户一个提示（如"正在努力处理中，请稍候…"），不要让用户以为系统卡死了。

四、降级策略

4.1 什么是降级

降级是指当系统的某个功能不可用或性能下降时，主动关闭或简化该功能，保证核心功能仍然可用。降级不是"出错了"，而是"主动牺牲次要功能，保证主要功能"。

4.2 常见的降级策略

策略一：功能降级

关闭非核心功能，只保留核心功能。

示例：大模型API限流时，关闭智能诊断功能，只保留基础的FAQ问答；搜索服务不可用时，关闭搜索功能，只保留分类浏览。

策略二：精度降级

降低处理精度，用更简单的方法处理。

示例：大模型不可用时，用基于关键词匹配的简单方法回答；复杂分析不可用时，只返回基础统计数据。

策略三：缓存降级

当后端服务不可用时，返回缓存的数据（即使数据不是最新的）。

示例：数据库查询失败时，返回缓存的上一次查询结果，并标注"数据可能不是最新的"。

策略四：静态降级

当动态内容不可用时，返回预先准备好的静态内容。

示例：个性化推荐不可用时，返回预先准备好的热门内容列表。

策略五：人工降级

当自动处理不可靠时，转人工处理。

示例：智能客服无法解决用户问题时，转人工客服；智能诊断置信度低时，建议联系专业维修人员。

4.3 降级的最佳实践

• 明确核心功能：事先明确哪些是核心功能（必须保证），哪些是非核心功能（可以降级）。
• 降级开关：每个可降级的功能都有开关，可以手动或自动开启降级。
• 降级提示：降级时给用户明确提示，说明当前功能受限，不要让用户以为是bug。
• 自动恢复：故障恢复后，自动关闭降级，恢复正常功能。
• 降级监控：监控降级状态和降级次数，及时发现和处理问题。
• 降级演练：定期进行降级演练，验证降级策略的有效性。

五、熔断机制

5.1 什么是熔断

熔断（Circuit Breaker）是一种保护机制——当某个服务的错误率超过阈值时，自动"熔断"（停止调用该服务），避免连锁故障和资源耗尽。一段时间后，尝试"半开"（允许少量请求通过），如果成功则"关闭"（恢复正常），如果失败则继续"打开"（继续熔断）。

熔断的概念来自电路中的保险丝——电流过大时保险丝熔断，保护电路不被烧毁。

5.2 熔断的三种状态

• 关闭（Closed）：正常状态，请求正常通过。统计错误率，当错误率超过阈值时，切换到打开状态。
• 打开（Open）：熔断状态，请求直接失败（不调用服务），立即返回降级结果。持续一段时间后，切换到半开状态。
• 半开（Half-Open）：试探状态，允许少量请求通过（如每秒1个请求）。如果这些请求成功，则切换到关闭状态（恢复正常）；如果失败，则切换回打开状态（继续熔断）。

5.3 熔断的关键参数

• 错误率阈值：错误率达到多少时触发熔断（如50%）。
• 统计窗口：统计错误率的时间窗口（如最近10秒）。
• 最小请求数：窗口内至少有多少个请求才计算错误率（如至少10个请求，避免少量请求误触发）。
• 熔断持续时间：打开状态持续多久后进入半开状态（如30秒）。
• 半开请求数：半开状态允许通过的请求数（如1个）。

5.4 熔断的最佳实践

• 配合降级：熔断时配合降级策略，返回降级结果，而不是直接报错。
• 粒度适中：熔断的粒度要适中——太粗（整个服务熔断）影响大，太细（每个接口熔断）管理复杂。一般按服务或接口粒度熔断。
• 参数调优：根据服务的实际情况调优熔断参数，不要盲目使用默认值。
• 熔断告警：熔断触发时通知开发人员，及时排查问题。
• 熔断监控：监控熔断状态、熔断次数、恢复时间，评估服务健康状况。

六、人工介入（Human-in-the-loop）

6.1 什么时候需要人工介入

不是所有问题都能自动解决。以下情况需要人工介入：

• 高风险操作：涉及安全、资金、隐私的操作（如修改生产数据、发送正式邮件、调用付费API），需要人工审批。
• 低置信度：智能体对结果不确定（置信度低于阈值），需要人工确认。
• 异常情况：遇到未预料到的异常，自动处理无法解决，需要人工判断。
• 用户要求：用户明确要求人工处理。
• 复杂决策：涉及多维度权衡、价值判断的复杂决策，需要人工参与。
• 连续失败：自动重试多次仍然失败，需要人工排查。

6.2 人工介入的方式

方式一：审批（Approval）

智能体在执行高风险操作前，暂停并请求人工审批。人工批准后继续执行，拒绝则取消。

示例：智能体生成了维修方案，在创建正式工单前，请求维修主管审批。

方式二：确认��Confirmation）

智能体给出结果后，请求人工确认是否正确。确认后提交，不确认则修改。

示例：智能体诊断出故障原因，给出维修方案，请求维修工确认是否正确。

方式三：纠错（Correction）

人工在智能体执行过程中，发现错误并纠正，智能体根据纠正继续执行。

示例：智能体在分析故障时，人工指出"这个设备不是这个型号"，智能体根据纠正重新分析。

方式四：接管（Takeover）

人工完全接管任务，手动完成，智能体退出。

示例：智能客服无法解决用户的复杂问题，转人工客服接管。

方式五：反馈（Feedback）

任务完成后，人工对结果给出评价和反馈，用于优化智能体的后续表现。

示例：维修完成后，维修工对诊断结果评价"准确/不准确"，并给出实际原因，用于优化诊断模型。

6.3 人工介入的最佳实践

• 明确介入点：事先明确哪些环节需要人工介入，介入的条件和方式是什么。
• 最小化介入：只在必要时介入，能自动处理的就自动处理，不要过度依赖人工。
• 提供充分上下文：请求人工介入时，提供充分的上下文信息（任务背景、已做的操作、当前结果、需要人工做什么），让人工快速理解情况。
• 超时处理：人工长时间未响应时，有超时处理机制（如自动取消、升级通知、降级处理）。
• 介入记录：记录每次人工介入的时间、人员、操作、原因，用于审计和优化。
• 反馈闭环：人工介入的结果反馈给智能体，用于持续优化，减少未来的人工介入需求。

七、优雅失败

7.1 什么是优雅失败

优雅失败（Graceful Failure）是指当系统遇到无法自动恢复的错误时，不是崩溃或卡死，而是以一种可控、友好、安全的方式失败——告知用户发生了什么、该怎么办，保证数据不丢失、系统不崩溃、安全不泄露。

7.2 优雅失败的设计要点

• 友好的错误提示：用用户能理解的语言说明错误，不要暴露技术细节。如"抱歉，服务暂时不可用，请稍后重试。如问题持续，请联系客服。"
• 明确的下一步：告诉用户该怎么办——重试、返回、联系客服、查看帮助。不要只说"出错了"，让用户不知所措。
• 数据保护：失败时保护用户已输入的数据——不要让用户重新填写表单，可以保存草稿、支持恢复。
• 状态一致：失败时保证系统状态一致——不要出现"部分成功部分失败"的情况。用事务或补偿机制保证一致性。
• 安全不泄露：失败时不泄露敏感信息——错误信息中不包含密码、密钥、个人隐私、系统内部结构。
• 资源释放：失败时释放占用的资源——关闭数据库连接、释放文件锁、清理临时文件。
• 错误记录：详细记录错误信息（日志），方便开发排查，但不要展示给用户。

7.3 错误信息的设计

好的错误信息应该包含三个要素：

1. 发生了什么：简洁明了地说明错误。如"无法连接到服务器"
2. 为什么会这样：简要说明原因（用户能理解的层面）。如"可能是网络连接不稳定"
3. 该怎么办：给出明确的行动建议。如"请检查网络连接后重试，或联系客服"

反例："Error 500 - Internal Server Error"（用户看不懂，也不知道该怎么办）

正例："抱歉，服务器暂时无法响应。这可能是由于系统维护或网络波动。请稍后重试，如问题持续，请联系客服（电话：400-xxx-xxxx）。"

八、实战：设备故障诊断智能体的错误处理设计

下一章，我们将学习评估与优化体系——如何建立智能体应用的评估指标体系，持续评估和优化智能体的表现。

📝 本章练习（5题）

答案与解析请在 互动学习看板 中作答查看。

📚 AI智能体实战训练营 课程目录（33 章）

1. 第1章 什么是AI智能体：从聊天机器人到自主决策系统
2. 第2章 智能体的四大核心能力：感知·思考·行动·记忆
3. 第3章 范式转移：智能体与传统软件的本质区别
4. 第4章 2025年主流智能体平台全景对比与选型
5. 第5章 智能体应用场景地图：从个人效率到企业级落地
6. 第6章 编排思维：如何把大模型变成可执行的业务流程
7. 第7章 Prompt工程实战：写出让智能体精准执行的指令
8. 第8章 工作流编排入门：节点、连线、条件分支与循环
9. 第9章 知识库RAG实战：让智能体拥有你的专业数据
10. 第10章 工具调用实战：搜索·计算·API·数据库全掌握
11. 第11章 多智能体协作：角色分工、任务分发与结果汇总
12. 第12章 Coze/扣子入门：30分钟搭建你的第一个智能体
13. 第13章 Coze进阶：插件开发、工作流深度编排与知识库优化
14. 第14章 Dify入门：开源可私有化部署的智能体平台搭建
15. 第15章 Dify进阶：RAG管道优化、Agent模式与工作流编排
16. 第16章 LangChain入门：用代码构建可定制的智能体应用
17. 第17章 LangChain实战：自定义Agent、工具链与记忆系统
18. 第18章 Agent Harness与新一代框架：2025年智能体开发趋势
19. 第19章 平台选型决策树：不同业务场景下的最优平台选择
20. 第20章 任务拆解方法论：把复杂问题变成智能体可执行的步骤
21. 第21章 提示词编排艺术：System·User·Function的三层协同
22. 第22章 记忆系统设计：短期记忆、长期记忆与向量数据库选型
23. 第23章 错误处理与容错：智能体执行失败时的兜底策略
24. 第24章 评估与优化体系：如何量化衡量智能体的效果并持续改进
25. 第25章 安全与合规：智能体应用的数据安全、隐私保护与风险防控
26. 第26章 实战项目一：企业知识库智能问答助手（全流程实操）
27. 第27章 实战项目二：制造业设备故障诊断智能体
28. 第28章 实战项目三：供应链采购智能分析与比价助手
29. 第29章 实战项目四：多智能体协同的项目管理办公室（PMO）
30. 第30章 实战项目五：智能体与MES/ERP系统的深度集成
31. 第31章 智能体落地路线图：从POC验证到规模化应用的完整路径
32. 第32章 AI智能体工程师/产品经理的能力模型与成长路径
33. 第33章 作品集打造与面试准备：如何拿到AI智能体岗位Offer