工具调用错误处理：Agent的兜底哲学

可视化演示

展示工具调用错误三分类（网络/API/业务）、自动重试与指数退避策略、以及降级兜底链路七环节闭环。切换模式探索Agent错误处理的兜底哲学。

错误分类识别

后厨的意外五花八门。“石斑鱼卖完了”——通知客人换菜；“烤箱温度上不去”——等五分钟再试；“把少辣做成了特辣”——重做一份。领班老张的每一句决策都建立在一个动作上：先判断这是什么性质的意外。这个动作，就是错误处理的第一步，也是最重要的一步。

Agent 调用工具时面对的也是同样的问题。工具返回的 HTTP 状态码、抛出的异常、超时的提示……所有异常信息首先都要被分类。最常见的分法有四类：可重试错误（如网络瞬时抖动、服务短暂过载）、不可重试错误（如参数非法、权限不足）、超时类错误（请求发出但没等到响应）、格式类错误（响应收到了但结构不对，比如 JSON 解析失败）。分类决定策略：可重试的才值得重试，不可重试的重试一百次也是浪费。

判断错误的类型，最直接的技术手段是检查异常的类别、错误码和响应体的状态字段。比如一个 HTTP 429（限流）或 503（服务不可用）响应，通常意味着等一会儿就恢复，值得重试；而一个 HTTP 400（参数错误）响应，无论重试多少次都不会成功。理解这一点，我们就能用一个概率公式来说明“重试的意义”：

回到领班老张的视角：分类不是目的，而是为了给每一种意外匹配正确的行动。可重试的，等一等再来一次；不可重试的，别浪费感情；超时的，先确认是否真的失败；格式不对的，记录上报让对端修复。四类错误，四条路，各有各的走法。

异常捕获机制

后厨地面上永远有油和水，经验丰富的厨师会在灶台边铺上防滑垫。领班老张深知：防滑垫不是用来“杜绝滑倒”的，而是用来“滑倒了也不至于摔断腿”的。异常捕获机制，就是 Agent 代码里的防滑垫。

在 Python 中，try-catch（准确说是 try-except）是拦截异常的基本手段。Agent 调用外部工具时，网络库可能抛超时异常，HTTP 客户端可能抛连接错误，JSON 解析可能抛格式错误——每一步都值得一个 try-except 去接住。捕获之后，再根据异常类型走不同分支，而不是让异常一路冒泡，把整个 Agent 进程打崩。这就是“拦截”的意义：把崩溃变成分支。

更进一步，成熟的 Agent 框架会定义自定义异常体系。比如 ToolTimeoutError、DataFormatError、ServiceUnavailableError，它们都继承自 ToolError 基类。这样一来，每个分支都能精确匹配异常类型，代码可读性也大大提升。同时要注意异常传播链的处理：Agent 往往需要依次调用多个工具，内层工具抛出的异常需要被包装成“带上下文信息”的新异常继续向上传播，方便上层决策。而防御式编程则是提前一步——在调用工具之前，先校验参数是否合法、格式是否符合预期，把能拦在门外的错误提前拦下，从根本上减少异常触发。

用领班的话说：防滑垫铺在三个位置——灶台边（try-catch）、通道上（异常传播链）、门口（防御式校验）。多铺一道，意外就少一分。但防滑垫只能防止摔倒，摔倒之后怎么记录、怎么对客人解释，才是接下来要解决的问题。

日志记录规范

老张有一个别人看不到的习惯：每天收工后，他都会在后厨的台账本上记几笔——今晚哪道菜出过问题、是什么原因、花了多久解决。这不是为了写工作总结，而是为了下周如果再遇到同样的意外，他能三分钟找到对策。日志系统，就是 Agent 的台账本。

一份合格的 Agent 日志，首先要做到结构化。不要写“报错了”这种模糊句子，而要输出 {"event": "tool_call_failed", "tool": "weather_api", "code": "TIMEOUT", "latency_ms": 3021}——机器可以解析，检索起来也高效。其次要有上下文追踪：一条请求从进入 Agent 到调用多个工具，整个过程应该共用一个 trace_id。这样排查问题时，就能顺着 trace_id 把散落在各处的日志串成一条完整的时间线，看清到底哪一步出了问题。

日志还要讲究级别。DEBUG 记开发细节，INFO 记正常流程，WARNING 记值得注意的单次失败，ERROR 记重试耗尽或兜底触发。级别分清楚了，告警和排查才能各取所需。最后是敏感信息脱敏：日志里不能出现用户手机号、API Key、token 等敏感字段。工具调用参数中的关键信息，写入日志前要用星号打码。否则台账记下来了，信息安全也泄露出去了。

老张的台账上，每一笔都清清楚楚：几号灶台、什么菜品、出了什么岔子、怎么解决的。Agent 的日志同样要形成这样的闭环——异常发生、记录归因、优化修复，从每一次故障中沉淀出系统的韧性。台账记好了，接下来就是怎么跟客人开口解释。

错误提示设计

客人不会关心“17 号蒸锅温度传感器读数异常”这样的技术细节。客人只想知道：我的菜要等多久？能不能换个菜？老张对客人说的话永远是“这道菜需要稍等几分钟，我帮您催一下后厨”或“这道菜今天备料不够，推荐您试试我们的招牌焖鸡”——原因清楚、建议明确、态度诚恳。Agent 面向用户的错误提示，也应该这么说。

设计错误提示的第一原则是用户友好措辞：把“{error_code: 500, stack_trace: ...}“翻译成”天气服务暂时不稳定，请稍后再试“。第二是给出错误恢复建议。比如”网络超时了，请检查网络连接后重试“——告诉用户接下来可以做什么，而不是让用户面对一个冰冷的失败。第三是状态可见反馈：如果 Agent 在重试，要明确显示”正在重试第 2 次，已等待 3 秒”，让用户感知到系统还在努力，而不是卡死。第四是隐藏技术细节：堆栈跟踪、内部 IP、数据库表名等，永远只进日志，不进用户界面。

这里有一条清晰的边界：技术细节给日志看，恢复建议给用户看。用户不是开发者，他们需要的是方向感。老张从不对客人背诵后厨的设备手册，但他一定会告诉客人“您的菜马上好”。Agent 也是一样——对外保持体面，对内保持透明。当错误已经无法通过话术掩盖时，就到了动用真刀真枪策略的时刻。

重试降级策略

如果一道菜连做两次都失败，老张会怎么做？他不会让厨师闷头做第三遍，而是先判断：是食材问题还是火候问题？有没有别的窗口能做这道菜？实在不行，推荐客人换成另一道招牌菜。这就是重试与降级的智慧——重试不是机械重复，而是有节奏、有边界的迂回。

技术上最经典的重试策略是指数退避：每次重试的等待时间按指数增长。第一次失败等 0.5 秒，第二次等 1 秒，第三次等 2 秒。这个“越来越慢”的设计是为了避免所有请求在同一时刻疯狂重试，把已经宕机的服务彻底压垮——也就是“雪崩效应”。公式如下：

除了指数退避，还有熔断器模式：当某个工具连续失败达到阈值（比如 5 次），熔断器“跳闸”，后续请求直接快速失败，不再进入重试循环。给故障服务一段冷静期，等它恢复后再逐步放行试探。熔断器与指数退避是一对黄金搭档：退避管重试节奏，熔断管全局开关。

降级则是更进一步的退让。如果主工具调用失败，Agent 可以调用备选工具——查天气的主服务挂了，就切到备用天气源；支付主通道拥塞，就切到备选支付通道。再不行，用缓存兜底：返回上一次成功获取的旧数据，虽然新鲜度差一点，但总比没有强。每一级降级都是向现实妥协，但妥协得有计划、有章法。

兜底预案设计

菜做了三次，换了两个窗口，客人等的菜还是没有着落。这时候老张会亲自走到桌前，先给客人送上一碗热汤，然后诚恳道歉，最后端上店长的名片：“这顿算店里请，下次您来提前说，我们给您留最好的位置。”这碗热汤、这张名片，就是兜底预案。它不是解决所有问题的万能药，而是让最坏的情况也不至于失控。

Agent 的兜底预案有几件必须准备的东西。第一是默认响应：当所有工具都失败时，返回一个结构完整、内容保守的默认结果。比如天气查询失败时，返回“今日天气未知，建议出门携带雨具”，而不是让响应字段缺失导致下游解析崩溃。第二是人工接管通道：当自动处理无法解决时，把请求升级给人工客服或运维团队，同时把所有上下文打包传过去，让人能无缝续接。第三是完整性检查：兜底响应发出之前，要校验它的结构是否符合下游预期——字段齐全吗？类型对吗？宁可给保守的默认值，也不能给一个缺胳膊少腿的残缺响应。第四是告警通知：兜底一旦触发，必须立刻通知开发团队。兜底只是权宜之计，根本问题没有被消灭，团队需要被拉响警报去修复根源。

这些预案的最终目标，是提升系统的整体可用性。可用性可以用一个经典公式衡量：

老张那碗热汤的价值，不在于汤本身，而在于它稳定了局面、争取了时间、给出了交代。Agent 的兜底预案也一样——当所有防御都被击穿，最后一道防线不是任何招数，而是“让系统还在呼吸、让用户还有人管、让团队还能得到预警”的秩序感。有了这份兜底哲学，你的 Agent 才算真正成年。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""Agent 工具调用错误处理演示：天气查询服务的抖动与兜底"""import jsonimport loggingimport randomimport time logging.basicConfig(    level=logging.INFO,    format="%(asctime)s %(levelname)s %(message)s",)  class ToolError(Exception):    """工具调用自定义异常基类"""     def __init__(self, message, code, retriable=False):        super().__init__(message)        self.code = code        self.retriable = retriable  class ToolTimeoutError(ToolError):    """超时错误，可重试"""     def __init__(self):        super().__init__("工具响应超时", code="TIMEOUT", retriable=True)  class DataFormatError(ToolError):    """返回数据格式错误，不可重试"""     def __init__(self):        super().__init__("工具返回数据格式异常", code="BAD_FORMAT", retriable=False)  class ServiceUnavailableError(ToolError):    """服务暂时不可用，可重试"""     def __init__(self):        super().__init__("服务暂时不可用", code="SERVICE_DOWN", retriable=True)  class WeatherTool:    """模拟外部天气工具：有 70% 概率抛出各类错误"""     def __init__(self):        self.fail_rate = 0.7     def fetch(self, city):        r = random.random()        if r < self.fail_rate:            pick = random.random()            if pick < 0.4:                raise ToolTimeoutError()            if pick < 0.7:                raise DataFormatError()            raise ServiceUnavailableError()        return {"city": city, "temp": random.randint(15, 35), "condition": "cloudy"}  class BackupTool:    """降级备选工具：返回保守的默认天气数据"""     def fetch(self, city):        return {"city": city, "temp": 24, "condition": "unknown", "cached": True}  class Agent:    """带错误处理与兜底策略的 Agent 客户端"""     def __init__(self):        self.tool = WeatherTool()        self.backup = BackupTool()        self.max_retry = 3        self.base_delay = 0.5     def call_weather(self, city):        delay = self.base_delay        for attempt in range(1, self.max_retry + 1):            try:                data = self.tool.fetch(city)                logging.info("第 %s 次调用成功: %s", attempt, json.dumps(data))                return data            except ToolError as e:                logging.warning("第 %s 次调用失败 [%s]: %s", attempt, e.code, e)                if not e.retriable or attempt == self.max_retry:                    break                time.sleep(delay)                delay *= 2        logging.info("重试耗尽，切换到兜底备选工具")        data = self.backup.fetch(city)        data["degraded"] = True        return data  if __name__ == "__main__":    random.seed(42)    agent = Agent()    result = agent.call_weather("shanghai")    print("最终结果:", json.dumps(result, ensure_ascii=False))

1. class ToolError(Exception)自定义异常基类，为所有工具错误提供统一的 code 和 retriable 属性
2. self.retriable = retriable标记“这个错误是否值得重试”，是分类逻辑的核心字段
3. raise ToolTimeoutError()抛出携带分类信息的异常，让上层捕获后精准决策
4. for attempt in range(1, self.max_retry + 1)控制重试次数上限，防止无限重试
5. except ToolError as e:只捕获工具错误，其他异常继续上抛，守住异常边界
6. if not e.retriable or attempt == self.max_retry:不可重试或次数耗尽，立即停止重试
7. time.sleep(delay)指数退避的时间等待，给故障服务喘息空间
8. delay *= 2等待时间翻倍，实现 0.5 秒 → 1 秒 → 2 秒的退避曲线
9. self.backup.fetch(city)调用兜底工具，返回保守默认数据
10. data["degraded"] = True标记兜底结果，让下游知道这份数据不是实时返回的

常见误区

面试题