如何在生产环境中处理 AI Agent 错误：实用错误处理指南

在生产环境中运行的 AI Agent 面临着一组独特的故障模式。与传统软件不同，Agent 结合了 LLM 调用、工具执行、外部 API 交互和记忆管理——每一层都引入了各自的错误面。一个工作流可能因 API 超时、格式错误的工具响应、提示注入、速率限制或推理链中意外的边缘情况而失败。

有效的错误处理并非阻止所有故障——那是不可能的。而是构建能够优雅失败、自动恢复，并为操作员提供清晰可见性的系统。本指南涵盖了生产 AI Agent 所需的实用错误处理模式，按故障层组织。

为什么 AI Agent 错误处理有所不同

传统应用程序具有可预测的故障模式。数据库查询失败，你可以重试或返回错误。HTTP 请求超时，你实现指数退避。AI Agent 引入了几个复杂因素：

• 非确定性输出：相同的提示在不同调用中可能产生不同的结果，使得错误预测更加困难。
• 组合性故障：Agent 工作流链接多个 LLM 调用和工具调用。第 3 步的故障可能需要撤销第 1 和第 2 步的副作用。
• 部分成功歧义：Agent 是否产生了可用的结果，还是输出存在细微错误？验证 LLM 输出需要不同于检查布尔返回值的策略。
• 成本敏感的重试：每次重试都会消耗 token。盲目重试根本性故障的工作流会浪费预算并延迟恢复。

理解这些差异是构建在生产环境中真正有效的错误处理系统的基础。

按故障层的错误处理

第 1 层：LLM API 故障

最常见的故障点是 LLM API 调用本身。这些包括速率限制、超时、部分响应和内容策略拒绝。

速率限制

LLM 提供商在多个级别实施速率限制：每分钟请求数、每分钟 token 数和并发连接限制。当你达到限制时，API 返回 429 状态码并附带 retry-after 信息。

最佳实践：实现自适应速率限制，跟踪你自己的使用情况与提供商限制，而不仅仅依赖 retry-after 头。缓存这些头信息，但维护自己的计数器，以避免多个 Agent 同时重试时的惊群问题。

超时和部分响应

LLM API 可能超时或返回部分响应，尤其是对于长生成任务。部分响应可能包含一个在参数中间被截断的有效函数调用，或一个在完成前被截断的推理链。

最佳实践：始终验证响应的结构，而不仅仅是 HTTP 状态码。对于函数调用，验证必需参数是否存在且格式正确。对于文本补全，检查响应是否自然结束或检测截断标记。为每个工作流步骤设置超时预算，当 API 确实缓慢时快速失败，而不是无限轮询。

内容策略拒绝

安全过滤器可能拒绝触发内容策略的提示或响应。这些拒绝有时是模糊的——提示可能因良性主题上的误报而被拒绝。

最佳实践：将内容策略错误与其他故障分开分类。实现一种重试策略，在可能时重新表述提示，并对同一主题的重复拒绝升级到人工审查。记录完整的提示和拒绝原因以供分析。

第 2 层：工具执行故障

Agent 执行工具——API、数据库、文件系统、Web 浏览器——这些工具因与 LLM 无关的原因而失败。工具可能返回意外数据、超时，或抛出 Agent 无法恢复的异常。

工具响应验证

工具应有明确的契约：输入模式、输出模式和错误语义。当工具返回的数据与预期模式不匹配时，Agent 需要决定是否重试、跳过或中止。

最佳实践：在每个工具调用周围包装一个验证层，在 Agent 处理结果之前检查返回类型、必需字段和值范围。记录验证失败及其上下文，说明 Agent 试图完成什么。这有助于区分工具 bug 和 Agent 误解。

工具超时策略

不同工具具有不同的适当超时配置。数据库查询可能需要 30 秒；Web 抓取任务可能需要 60 秒；文件操作应在毫秒内完成。

最佳实践：按工具类型分配超时预算，而非按 Agent 调用。按预期延迟配置对工具进行分组并相应配置超时。对于长时间运行的工具，考虑实现进度报告，以便 Agent 在等待时向用户报告状态。

第 3 层：工作流和状态故障

Agent 工作流在多个步骤之间维护状态。当故障在工作流中间发生时，Agent 需要理解哪些状态已提交、哪些待处理以及如何恢复。

检查点和回滚

对于产生副作用的工作流——发送邮件、更新数据库、创建文件——故障必须通过显式的检查点和回滚语义来处理。在第 4 步（共 6 步）之后失败的工作流应该要么完成剩余步骤，要么撤销第 1-4 步所做的操作。

最佳实践：尽可能实现幂等操作。如果工作流步骤可以安全地重新执行而不重复，则在每个步骤后检查点，并在失败时从最后一个检查点重试。对于非幂等操作，实现显式回滚逻辑，按相反顺序撤销每个副作用。

记忆和上下文故障

Agent 通常在多轮之间维护工作记忆或上下文。记忆存储可能因配额限制、序列化错误或数据损坏而失败。丢失记忆可能导致 Agent 失去对话状态或任务进度的跟踪。

最佳实践：将记忆视为尽力而为的优化，而非可靠性保证。设计工作流，使丢失记忆时优雅降级而非导致硬故障。实现记忆备份和定期检查点。当记忆不可用时，Agent 应通过向用户请求上下文来恢复，而不是盲目继续。

错误分类和响应策略

并非所有错误都值得相同的响应。将错误分类为类别并分配响应策略：

瞬时错误：带退避的重试

瞬时错误是预期且可恢复的。关键是实现智能重试逻辑，不浪费资源。使用带抖动的指数退避来分散重试尝试。设置最大重试次数和超时预算。如果重试耗尽，升级到更高优先级的故障类别，而不是无限循环。

可转换错误：修复并重试

某些错误可以通过修改输入来修复。格式错误的函数调用可能通过提取部分数据并完成缺失字段来修复。被拒绝的提示可能通过重新表述来修复。实现错误检查逻辑，识别可修复的故障，并在重试之前应用针对性修正。

永久错误：中止并升级

永久错误表明重试无法修复的根本问题。Agent 应记录带有完整上下文的错误，通知操作员，并中止工作流或切换到降级模式。永久错误后切勿静默继续——用户有权知道出了什么问题且无法恢复。

系统性错误：备用系统

当整个提供商或服务不可用时，备用系统保持 Agent 功能。这可能意味着切换到备用 LLM 提供商、回退到缓存响应或路由到人工操作员。备用策略应按故障模式配置并定期测试，以确保它们在需要时真正有效。

可观测性：使错误可见

没有可观测性的错误处理是不完整的。当错误发生时，操作员需要理解发生了什么、为什么发生以及系统做了什么来恢复。仅靠日志是不够的——你需要结构化追踪，跟随错误贯穿整个工作流。

结构化错误日志

以一致的结构记录错误：错误类型、时间戳、工作流 ID、步骤上下文、输入值（已清理）和已采取的恢复操作。包含编程错误的完整堆栈跟踪和业务逻辑错误的清理摘要。切勿记录 PII、API 密钥或敏感工具输出。

错误率仪表板

按类型、工作流和时间跟踪错误率。对异常发出警报：速率限制错误的突然激增可能表明配置错误的重试循环；可转换错误的逐渐增加可能表明提示漂移。使用这些仪表板在问题影响用户之前检测问题。

事后模板

当发生重大错误时，记录事件：什么失败了、为什么失败、如何检测、如何解决以及应添加哪些预防措施。使用这些事后分析来持续改进错误处理，而不是将每个事件视为孤立事件。

实际实现模式

模式 1：熔断器

当特定工具或提供商开始持续失败时，熔断器模式防止 Agent 在重复失败上浪费资源。在连续错误达到阈值后，熔断器打开，后续调用立即失败而无需尝试操作。经过冷却期后，熔断器半开以测试底层问题是否已解决。

此模式对于防止级联故障至关重要，其中一个缓慢或失败的依赖项会降级整个 Agent 的性能。

模式 2：降级链

对于关键操作，实现按顺序尝试多种方法的降级链。如果主 LLM 提供商超时，尝试备用提供商。如果备用也失败，回退到缓存响应或更简单的模型。每个降级都应评估质量和成本权衡。

降级链应配置明确的优先级和超时预算，以便降级不会使整体延迟比原始故障更差。

模式 3：优雅降级协议

当错误阻止完整工作流完成时，优雅降级确保 Agent 仍提供某些价值。如果工具失败，Agent 可能使用缓存数据继续或要求用户补充缺失信息。如果 LLM 不可用，Agent 可能为简单查询回退到基于规则的响应。

始终向用户传达降级情况。他们应该知道 Agent 何时在降低能力模式下运行以及哪些功能不可用。

需要避免的常见陷阱

陷阱 1：静默失败

最糟糕的错误是无人注意到的错误。如果 Agent 因错误被吞没而静默返回错误输出，用户会失去信任，系统以最危险的方式失败。始终暴露错误，即使它们被自动处理。记录的错误应对操作员可见，而非隐藏在无人阅读的日志中。

陷阱 2：过度重试

重试根本性故障的工作流会浪费 token 并延迟恢复。如果错误被分类为永久或不可修复的可转换错误，立即停止重试并升级。设置重试次数和总重试时间的硬性限制。

陷阱 3：将所有错误同等对待

速率限制错误和 Agent 输出中的语法错误需要完全不同的响应。一个需要耐心的重试逻辑；另一个需要提示修正或人工干预。投资于错误分类，使响应策略与错误类型匹配。

常见问题

瞬时错误我应该使用多少次重试？

从 3 次重试开始，使用带抖动的指数退避。这可以处理大多数瞬时故障而不会过度延迟。对于关键操作，考虑 5 次重试。始终设置总超时预算——3 次重试不应超过 30-60 秒的 API 调用总时间。

我应该为错误调试记录完整的 LLM 提示和响应吗？

为错误调试记录提示和响应，但首先清理敏感数据。移除 PII、API 密钥、密码和专有信息。存储清理后的版本用于调试，如果需要合规或法律原因，在安全、访问控制的存储中保存完整版本。

我如何处理多 Agent 工作流中的错误？

多 Agent 工作流增加了协调复杂性。每个 Agent 应处理自己的本地错误，但编排器需要跨所有 Agent 的错误可见性。实现一个共享错误报告通道，Agent 在其中发布错误，编排器决定是否重试失败的 Agent、切换到备用 Agent 或中止整个工作流。

错误处理和错误恢复有什么区别？

错误处理是对失败的即时响应：记录、分类和决定是否重试或中止。错误恢复是失败后恢复正常运行状态的过程：回滚副作用、重新建立连接并从最后一个检查点恢复工作流。两者对于生产可靠性都是必要的。

我如何测试我的错误处理逻辑？

通过故障注入测试错误处理：在测试期间故意引入故障，模拟 API 超时、速率限制、格式错误的响应和网络错误。使用混沌工程原则在类生产条件下测试恢复。如果你无法在测试中模拟故障，你可能无法在生产中处理它。

我何时应将错误升级到人工操作员？

当错误是永久且不可修复时，当工作流已耗尽所有重试策略时，当错误表明潜在的安全问题时，或当错误影响高价值操作时，应升级。根据错误严重程度、业务影响和重试耗尽设置升级阈值。切勿升级瞬时错误——这些应由自动处理。

开始生产错误处理

为 AI Agent 构建强大的错误处理是迭代的过程。首先通过测试和生产中遇到的故障模式进行分类。按类型对每个进行分类并分配响应策略。首先实现最高优先级的处理器，然后随着新故障模式的出现扩展覆盖范围。

目标不是阻止所有错误——而是确保当错误发生时，系统以可预测的方式响应、高效恢复，并提供清晰的可见性。善于处理错误的 Agent 建立用户信任。静默或不可预测失败的 Agent 会失去它。

需要帮助为你的 AI Agent 实现错误处理？ 探索 SmaugBrain，获取内置可靠性模式的即用型 Agent 基础设施。