4.2 错误处理与异常管理

4.2 错误处理与异常管理

本节摘要：智能体应用会出错——模型超时、工具失败、解析异常。本节讲清错误处理的三层策略（重试、降级、兜底）、常见异常的类型与处理方式，以及"让系统在错误中存活"的设计原则。

本节地图

阅读完本节，你应当能够：

1. 说出错误处理的三层策略
2. 识别常见异常类型
3. 设计重试与降级
4. 实现兜底回复
5. 让系统在错误中存活

一、问题与直觉

"模型超时了怎么办？工具挂了怎么办？"——生产环境，错误是常态不是意外。智能体的错误处理思路与普通软件不同：不是"避免错误"，而是"优雅降级"——出错了，系统依然能给出合理回应，而不是崩溃或报错。

智能体系统的错误源比普通软件多得多：模型服务超时、限流、返回格式异常；工具依赖的外部 API 挂掉；上下文超长被截断；多智能体交接失败。任何一个环节出错，用户面对的都是"对话框失灵"。设计的目标不是"永不报错"（不可能），而是"任何错误都有体面的出口"。

二、核心原理

2.1 三层错误处理

• 重试：瞬时错误（超时、限流）再试一次
• 降级：降能力（不用工具、换小模型）
• 兜底：给安全默认回复（"服务暂不可用"）

三层是递进关系：先重试，重试解决不了就降级，降级也不行就兜底。每一层都有一句潜台词——重试说"再给一次机会"，降级说"换个方式干"，兜底说"承认失败但要体面"。

2.2 常见异常类型

三、工程实践要点

3.1 重试设计

次数：2-3 次为宜
退避：指数退避（等 1s、2s、4s）
上限：超过上限进入降级
​

重试不是越多越好：模型限流时，重试太频繁只会继续触发限流；退避加随机抖动，让请求错开高峰。另外要区分"值得重试的错误"和"不值得重试的错误"——参数错误重试一万次也没用。

3.2 降级设计

💡 关键直觉：降级是"优先级排序"——想清楚哪些能力最核心、哪些可以牺牲，出错时按序降级。核心功能保命，边缘功能先退。

3.3 兜底设计

兜底回复："我暂时遇到点问题，请稍后再试"
兜底动作：记录错误、告警、转人工
兜底原则：宁可说"不知道"，不编造
​

3.4 一个完整的错误处理示例

from agents import Agent, Runner, function_tool

@function_tool
def query_stock(code: str) -> str:
    """查询股票行情。"""
    try:
        return stock_api.get(code)
    except Exception as e:
        # 错误转文本，让模型决定怎么回应，而不是中断
        return f"行情服务暂时不可用: {e}"

agent = Agent(
    name="投资助手",
    instructions=(
        "查询股票时调用工具。"
        "如果工具返回'不可用'，要如实告诉用户稍后再试，"
        "绝不编造行情数据。"
    ),
    tools=[query_stock],
)

result = Runner.run_sync(agent, "帮我查一下某股票的收盘价")
print(result.final_output)
​

这个示例同时演示了工具层错误处理和指令层兜底：工具把异常转成文本，指令要求模型"宁可说不知道也不编造"。两层配合，用户永远不会得到"看起来很真、其实是编的"数据。

⚠️ 常见坑：出错时模型硬答。工具挂了，模型可能"编一个结果"混过去——指令里明确"工具失败必须说明"，让诚实成为兜底。

⚠️ 常见坑：只做重试不做兜底。重试会耗尽，兜底才是最后防线——把三层完整设计出来，而不是只写一层。

3.5 错误监控

记录：错误类型、频率、影响
告警：高频错误触发告警
复盘：定期分析错误原因
​

错误处理的设计不是一次性的：上线后要持续看错误数据，哪种错误最多、哪类用户受影响最大、降级后满意度如何。数据会告诉你下一轮优化该投在哪。

一节小结

• 要点一：三层策略——重试、降级、兜底
• 要点二：错误是常态，目标是优雅降级
• 要点三：重试 2-3 次，指数退避
• 要点四：降级是优先级排序
• 要点五：兜底宁可说不知道，不编造
• 要点六：错误要监控、告警、复盘

扛得住了，下一节跑得好——性能优化与资源管理。