我的 AI Agent 调用工具失败了,可它毫不知情、继续假装成功往下走,最后给用户编了一通根本没发生的操作结果:一次 Agent 工具错误没回传给模型的深度复盘

那个 bug 是用户说"Agent 告诉我已经帮我改好了,可我这边根本没变"才暴露的:我做了个能调用工具办事的 AI Agent,其中一个工具是"更新用户配置"。流程本该是:Agent 调用这个工具→工具去改配置→把结果告诉 Agent→Agent 回复用户。功能大体能用,可线上偶尔出现极其诡异的情况:工具其实执行失败了(比如下游服务报错、权限不足),可 Agent 却像没事人一样,继续往下走,最后还信誓旦旦地告诉用户"已经帮您更新好了"——而实际上啥也没改成。我追着日志查,才看明白,后背发凉:问题出在我处理"工具执行失败"的方式上。我的工具函数里 try-catch 了异常,可catch 之后,我要么静默返回了一个空结果/默认值,要么只在自己的日志里记了一笔错误,却没有把"这次工具调用失败了、失败原因是什么"以模型能理解的方式回传给 Agent(LLM)。于是在 Agent(模型)的视角里:它发起了一次工具调用,收到的"工具结果"是一个看起来正常的(空的或默认的)返回,它完全不知道这次调用其实失败了;模型是基于"它收到的信息"来推理的——既然没有任何信息告诉它"失败了",它就默认这步成功了,然后基于"操作已成功"这个错误前提继续往下走、生成了"已帮您更新好了"的回复。问题的根,是工具执行失败后,错误没有以模型能理解的方式回传给 Agent;模型不知情,就会基于"默认成功"的错误前提继续,产出与现实不符的结果。这篇就把这次"工具错误没回传给模型"的坑,从头到尾复盘一遍。

故障现场:工具失败了,模型却不知道

问题在于工具执行失败后,错误被吞掉或没回传给模型,模型以为成功:

# ✗ 出问题的工具实现: 失败后没把错误回传给模型
def update_config_tool(user_id, config):
    try:
        result = downstream.update(user_id, config)
        return {"status": "ok", "data": result}
    except Exception as e:
        log.error(f"更新配置失败: {e}")   # ✗ 只记在自己的日志里
        return {}                          # ✗ 静默返回空! 模型看到的是个"空结果", 不知道失败了
        # (或更糟: 直接 raise 让整个Agent流程崩掉, 模型也无从得知发生了什么)

# 在Agent(模型)的视角:
# - 它发起了 update_config_tool 调用;
# - 它收到的"工具结果"是 {} (空) —— 看起来人畜无害, 没有任何"失败"的信号;
# - 模型据此推理: "调用返回了, 没报错信息, 那应该是成功了吧";
# - → 基于"成功"的错误前提, 继续生成 "已帮您更新好了" 的回复。

# 现象: 工具实际失败, 但Agent告诉用户"成功了" → 与现实不符的、误导性的回复。

# 为什么会这样? 因为模型【只能基于它收到的信息推理】:
# - 模型看不到你的日志、看不到那个被catch吞掉的异常;
# - 它对"工具调用结果"的全部认知, 就是你【回传给它的那段内容】;
# - 你回传一个空的/正常样子的结果, 它就以为成功; 你不告诉它失败, 它就不知道失败;
# - → "没有错误信息" 在模型看来 ≈ "没有错误"。

# 另一个极端: 直接 raise 异常中断整个Agent循环
#   → 模型同样没机会"知道并应对"这个失败(它连重试/换方法/告知用户的机会都没有)。

# 关键: 模型只基于"回传给它的工具结果"推理; 工具失败后若把错误吞掉/返回空/直接崩,
#       模型就不知道失败、会默认成功并基于错误前提继续 → 产出与现实不符的结果。

第一次想明白"模型根本不知道工具失败了、它只看见我回传的那个空结果"时,我又懊恼又恍然:"我一直把 Agent 当成一个'能看到一切、自己会判断对错'的智能体,完全忘了它其实是个'只能根据我喂给它的信息来推理'的模型——我没告诉它失败,它当然不知道。"这个坑最危险的地方在于:它让 Agent "一本正经地胡说八道"——基于一个它并不知道是错的前提(操作成功了),它会非常自信地给出与事实不符的回复;而这种"自信的错误"对用户的误导和信任伤害极大。下面就来拆解,工具的执行结果(尤其是失败)该怎么正确地回传给模型。

第一件事:搞懂"模型只基于回传给它的信息推理"

我顺着这次事故,把 Agent 与工具之间的信息流彻底理清了。

为什么工具失败后, Agent 会"假装成功"继续往下走?

【核心: 模型只能基于"回传给它的工具结果"推理; 工具失败若不把错误以模型能懂的方式回传, 模型就不知道失败、默认成功、基于错误前提继续】

1. 关键认知: 模型是"基于它收到的上下文"推理的, 仅此而已
   - LLM不会"自己去观察真实世界", 它对工具调用结果的全部认知 = 你回传给它的那段文本;
   - 它看不到你的服务器日志、看不到被catch的异常、看不到下游的真实状态;
   - → "你没把失败告诉它" 在它看来就等于 "没失败"。

2. Agent调用工具的标准循环(ReAct式):
   - 模型决定调用某工具(给出工具名+参数) → 系统执行工具 → 把【工具结果】回传给模型 →
     模型基于这个结果, 决定下一步(继续/调别的工具/回复用户);
   - 这个循环的命脉, 是"工具结果回传"这一步——它是模型感知"行动后果"的唯一通道。

3. 本文的错: 切断/污染了"工具结果回传"这条通道
   - 失败后返回空/默认值: 模型收到一个"看似正常"的结果 → 误以为成功;
   - 失败后只记日志不回传: 模型啥也没收到失败信号 → 误以为成功;
   - 失败后直接raise中断: 模型连"知道失败并应对"的机会都没有, 整个流程崩掉。

4. 后果: 基于错误前提的连锁推理
   - 模型一旦"误以为某步成功了", 后续所有推理都建立在这个错误前提上;
   - → 它会自信地报告"已完成"、或基于"假数据"继续下一步 → 错误层层放大。

5. 正确的做法: 把工具结果(成功/失败)都如实、清晰地回传给模型
   - 失败时, 回传一个【模型能理解的、说明失败及原因的结果】(而非空/异常);
   - 让模型"知道"失败了 → 它才能做出合理反应: 重试、换个方法、向用户说明、请求人工;
   - → 把模型当成一个"需要被如实告知行动结果"的决策者, 给它完整、真实的反馈。

一句话: 模型只基于"回传给它的工具结果"推理, 看不到你的日志和被吞的异常; 工具失败若返回空/只记日志/直接崩,
   模型就不知道失败、默认成功、基于错误前提连锁推理; 必须把失败及原因如实清晰地回传给模型。

这套认知,是整个坑的根。关键认知:模型只基于"它收到的上下文"推理——它不会自己观察真实世界,对工具调用结果的全部认知=你回传给它的那段文本;它看不到你的日志和被 catch 的异常,"你没把失败告诉它"在它看来就等于"没失败"。Agent 调用工具的标准循环:模型决定调工具→系统执行→把工具结果回传给模型→模型据此决定下一步;"工具结果回传"是模型感知行动后果的唯一通道。本文的错:切断/污染了这条通道——失败返回空/只记日志/直接 raise 中断,模型要么误以为成功、要么连应对机会都没有。后果:模型一旦误以为某步成功,后续所有推理都建立在错误前提上,错误层层放大。正确做法:把工具结果(成功/失败)都如实清晰回传,失败时回传模型能理解的、说明失败及原因的结果,让模型知道失败后能重试/换方法/向用户说明/求助。一句话:模型只基于"回传给它的工具结果"推理,看不到你的日志和被吞的异常;工具失败若返回空/只记日志/直接崩,模型就不知道失败、默认成功、基于错误前提连锁推理;必须把失败及原因如实清晰地回传给模型。

第二件事:正解——把工具的成功与失败都如实、清晰地回传给模型

搞懂了原理,正解就清晰了:工具执行无论成功失败,都返回一个结构化、模型能理解的结果;失败时明确告知"失败了、为什么失败、可以怎么办";别吞异常、别返回空、别直接崩。

# ====== 正解: 把失败也作为"一个明确的、模型能理解的结果"回传 ======
def update_config_tool(user_id, config):
    try:
        result = downstream.update(user_id, config)
        return {"success": True, "data": result}      # 成功: 明确告知成功+数据
    except PermissionError as e:
        # ★ 失败: 返回一个"模型能读懂的、说明失败及原因"的结果(不是空、不是raise)
        return {"success": False,
                "error": "权限不足, 无法更新该用户的配置",
                "hint": "请确认用户有修改权限, 或向用户说明需要管理员操作"}
    except Exception as e:
        return {"success": False,
                "error": f"更新配置失败: {type(e).__name__}: {e}",
                "hint": "可以重试一次; 若仍失败, 请如实告知用户操作未成功"}

# 现在模型收到的工具结果, 清清楚楚地写着"success: False"和失败原因:
# - 模型"知道"了这步失败了 → 它会据此做出合理反应:
#   * 按hint重试一次;
#   * 或换一个方法;
#   * 或【如实告诉用户】"抱歉, 因为权限不足, 没能帮您更新, 建议...";
# - 而不再是"误以为成功、谎报已完成"。

# ====== 给Agent工具结果设计的要点 ======
# 1. 成功失败都返回结构化结果: 用 success/error 字段明确标识, 别用"空"暗示失败;
# 2. 失败信息要"模型友好": 用自然语言说清"失败了、为什么、建议怎么办", 而非堆栈/错误码;
#    (模型靠读这段文本来决策, 写得让它能理解、能据此行动);
# 3. 别吞异常、别返回空、别直接raise中断: 这三种都让模型"感知不到失败"或"无从应对";
# 4. 区分"可重试"和"不可重试"的失败, 在结果里给出提示, 引导模型合理反应;
# 5. 在系统提示里教模型: "工具可能失败, 失败时要如实告知用户、不要编造成功";
# 6. 配合人在回路: 关键操作失败/反复失败时, 升级给人工(同541篇), 别让Agent硬扛。

# ====== 更普适: 把模型当成"只能靠你喂信息的决策者" ======
# - 模型的每一个决策, 都只基于"它能看到的上下文"; 你给它什么信息, 决定了它能做出什么决策;
# - 所以: 凡是"模型需要知道才能正确决策"的信息(工具结果、失败、约束、状态), 都要【显式、清晰地喂给它】;
# - 别假设它"自己会知道"——它不会, 它只知道你告诉它的。

# 核心: 工具的成功与失败都用结构化、模型能懂的方式如实回传(失败说清原因和建议, 别吞别空别崩);
#   把模型当"只靠你喂信息决策的决策者", 凡是它正确决策需要的信息都显式清晰地给它。

修复的核心,是"把工具的成功与失败都如实、清晰地回传给模型"。正解:失败也作为一个明确的、模型能理解的结果回传——返回 {"success": False, "error": "...", "hint": "..."},用自然语言说清"失败了、为什么、建议怎么办";模型读到后能重试/换方法/如实告诉用户,而不再谎报成功。要点:成功失败都返回结构化结果(别用空暗示失败)、失败信息要"模型友好"(自然语言说清而非堆栈码)、别吞异常别返回空别直接 raise、区分可重试与否、系统提示里教模型失败要如实告知别编造、关键操作反复失败升级人工。更普适:把模型当成"只能靠你喂信息的决策者"——凡是它正确决策需要的信息都要显式清晰地喂给它,别假设它自己会知道。归根结底:工具的成功与失败都用结构化、模型能懂的方式如实回传(失败说清原因和建议,别吞别空别崩);把模型当"只靠你喂信息决策的决策者",凡是它正确决策需要的信息都显式清晰地给它。

第三件事:AI Agent 工具集成中其他常见的坑

排查后我把 Agent 工具集成相关的其他坑也系统梳理了一遍。

AI Agent 工具集成的其他常见坑

# 1. 工具错误没回传(本文): 模型不知失败、谎报成功。→ 成功失败都如实回传。

# 2. 工具描述含糊(同529篇): 模型不知何时/如何用、填错参数。→ 清晰的工具描述与参数说明。

# 3. 工具有副作用没幂等(同541篇): 重试/重复调用重复执行。→ 幂等键+确认。

# 4. 工具返回结果过大: 塞爆context/挤掉任务/烧token。→ 分页/摘要/截断/存引用按需取。

# 5. 没有循环终止边界(同505篇): Agent反复调工具不停。→ 步数上限+终止条件。

# 6. 上下文无限膨胀(同517篇): 历史和工具结果越积越多。→ 裁剪/摘要历史。

# 7. 工具参数未校验就执行: 模型填的参数可能非法/越界。→ 执行前校验参数。

# 8. 模型对工具结果的"幻觉": 即使回传了结果, 模型也可能曲解/编造。→ 结果清晰+关键处校验。

# 共同根源: Agent = "LLM(决策) + 工具(行动)"的循环; 而"决策"和"行动"之间的【信息传递】(我让它调啥、
#   它调用啥、调用结果是啥)是整个系统的命脉; 这个信息传递的任何一环模糊/失真/缺失, Agent就会出错。

# 核心: 把Agent的"工具调用循环"中的信息传递做扎实——工具描述清晰、参数校验、结果(含失败)如实清晰回传、
#   控制循环和上下文; 始终记住"模型只基于它收到的信息行动", 把它需要的信息准确完整地给它。

排查让我把 Agent 工具集成的其他坑也梳理清了。一、工具错误没回传(本文)。二、工具描述含糊。三、工具有副作用没幂等。四、工具返回结果过大。五、没有循环终止边界。六、上下文无限膨胀。七、工具参数未校验。八、模型对工具结果的幻觉。它们的共同根源是:Agent = "LLM(决策)+工具(行动)"的循环;而"决策"和"行动"之间的信息传递(我让它调啥、它调用啥、调用结果是啥)是整个系统的命脉;这个信息传递的任何一环模糊/失真/缺失,Agent 就会出错。核心是:把 Agent 的"工具调用循环"中的信息传递做扎实——工具描述清晰、参数校验、结果(含失败)如实清晰回传、控制循环和上下文;始终记住"模型只基于它收到的信息行动",把它需要的信息准确完整地给它。下面这张图,是这次工具错误没回传坑的成因与解法:

第四件事:工具失败的几种处理方式对比表

这次踩坑后,我把工具执行失败的几种处理方式对比成一张表。

这张表把几种方式钉清了。核心是:处理工具失败的关键,不在于"把异常 catch 住别让程序崩"(那只是传统编程的思路),而在于"让作为决策者的模型,知道发生了什么、从而能做出合理的下一步"——对 Agent 来说,"把失败如实告诉模型"比"悄悄处理掉失败"重要得多;因为模型是这个系统里"做决策的大脑",蒙蔽它的认知,就是让整个系统盲目决策。它给我的最大启发是:在一个"有决策者(人或 AI)参与"的系统里,"让决策者获得真实、完整的信息" 是比 "悄悄替它把问题处理掉" 更重要的事——因为决策的质量, 取决于决策者掌握的信息的质量;蒙蔽或误导决策者(哪怕是出于"不想让它操心"的好意), 都会导致糟糕的决策;"对决策者隐瞒坏消息", 往往比"坏消息本身"危害更大。这给了我一种设计"人机/信息系统"的清醒:设计任何"给决策者(人或 AI)提供信息"的环节时,要确保"真实、及时、完整地反馈",尤其是坏消息(失败、异常、风险)绝不能隐瞒或粉饰——而要让决策者清楚地知道"真实发生了什么",再由它(基于完整信息)去决策;"如实反馈、不蒙蔽决策者",是一切依赖正确决策的系统(无论决策者是人还是 AI)健康运转的前提。认清让决策者获得真实信息比悄悄处理更重要、坏消息绝不隐瞒——是这个坑带给我的认知。

第五件事:这次事故暴露的"AI 会自信地编造"的特性

这次让我反思更深一层:Agent 不是"沉默地出错",而是"自信地编造了一个成功的结果"。我把传统程序出错和 LLM 出错的表现对比成表。

这张表道出了 LLM 出错的独特危险。核心是:LLM/Agent 出错时,最危险的不是"它出错了",而是"它会用一种流畅、自信、像模像样的方式把错误结果呈现出来"——它不会像传统程序那样"明明白白地报错",而是会"一本正经地胡说八道";这种"自信的错误",极具迷惑性,用户很容易信以为真。它给我的深刻启发是:使用 LLM/AI 时,必须时刻警惕它"会自信地产出错误/虚构内容(幻觉)"这一固有特性——"它回答得很流畅、很笃定" 完全不代表 "它是对的";它的"自信"和它的"正确性"是解耦的(不像人,通常没把握时会犹豫);所以不能把"它说得很肯定"当作"可以信任"的依据。这给了我一种使用 AI 的根本审慎:凡是 AI 产出的、且"错了会有实际后果"的结果,都不能因为它"说得自信"就盲信,而要建立"验证/兜底"机制——给它真实的反馈(别让它在错误前提上裸奔)、对关键结果做程序化校验、对重要操作加人工确认、在 prompt 里要求它"不确定就说不确定、别编造";"不被 AI 的'自信'迷惑、对其产出建立验证而非盲信",是安全地使用 AI 的核心心态。认清 AI 会自信地编造、其自信与正确性解耦、对关键产出验证而非盲信——是这个 Agent 坑带给我的工程态度。

第六件事:给 Agent 写工具时,我现在的自检习惯

现在每当我给一个 AI Agent 写或接入一个工具,我都会先按这张图问自己:

这张图的精髓,是"工具的成功失败都如实清晰回传,让模型知情并合理应对"。失败别吞别空别 raise、回传结构化+原因+建议、信息模型友好的自然语言、反复失败升级人工。这套习惯,让我从"工具失败悄悄处理掉"变成了"把失败如实告诉模型让它应对"——核心始终是:工具的成功与失败都用模型能懂的方式如实回传(失败说清原因和建议,别吞别空别崩),让只靠回传信息推理的模型知道失败、做出合理反应。

我立下的几条规矩

这场"工具失败了,Agent 却谎报成功"的事故,换来了我做 AI Agent 时,刻进骨子里的几条铁律:

1. 模型只基于"回传给它的工具结果"推理,看不到你的日志和被吞的异常。
2. 工具失败若返回空/只记日志/直接崩,模型就不知道失败、会默认成功。
3. 工具的成功与失败都要结构化、如实回传。失败用 success:False+原因+建议。
4. 失败信息要"模型友好"——自然语言说清失败原因和怎么办。而非堆栈/错误码。
5. 别吞异常、别返回空、别直接 raise 中断流程。这三种都让模型无从感知/应对。
6. 关键操作反复失败要升级人工,别让 Agent 硬扛或瞎编。
7. AI 会自信地编造,它的自信与正确性解耦,对关键产出要验证而非盲信。

写在最后

回头看,这场由"工具失败没回传给模型"引发的、Agent 谎报成功的事故,真正教给我的,远不止"失败也要返回结构化结果"这一个技巧。它让我对"一个'决策者'的判断质量, 完全取决于它'所掌握的信息'的质量; 蒙蔽了它的认知, 再聪明的决策者也只会做出愚蠢的决策",有了一次刻骨的体会。我栽跟头,是因为我下意识地把那个 Agent 当成了一个"无所不知、能自己看清一切"的智能体——我以为"它那么聪明,工具失败了它自然会知道"。可我忘了:它再聪明,也只是一个"关在房间里、只能通过我递进去的纸条来了解外界"的大脑;它对"工具调用到底成功没成功"的唯一信息来源,就是我回传给它的那张"纸条";而我递进去的是一张"看似一切正常"的空白纸条(吞掉了失败),于是这个聪明的大脑,基于这张被我污染了的信息,做出了"成功了"的错误判断;错的不是它的智能,而是我喂给它的信息。这让我领悟到一个关于"智能与信息"的深刻认知:任何决策者(无论是 AI、是人、还是一个程序模块)的决策质量,有一个无法逾越的上限——它所获得信息的质量;"垃圾进, 垃圾出(garbage in, garbage out)" 不仅适用于计算, 更适用于决策;给一个决策者残缺、失真、被粉饰的信息, 然后期待它做出正确决策, 是缘木求鱼;很多"看起来是决策者愚蠢"的错误, 根子其实在"它被喂了错误的信息"。这给了我一种构建"智能系统/协作系统"的根本原则:想让一个决策者(AI 或人)做出好的决策,首要的不是把它变得更"聪明",而是确保它能获得"真实、完整、及时"的信息——建好"信息如实流向决策者"的通道,尤其不要让坏消息在半路被吞掉、被粉饰;"把保证信息质量, 看得和提升决策者能力同等重要",是构建任何依赖正确决策的系统的根本。认清决策质量受限于信息质量、保证信息如实流向决策者比让它更聪明更重要——这,是我用一次 Agent 谎报成功的事故,换来的、关于 AI Agent、也关于如何让一切决策者做出好决策的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次给 Agent 写工具时,把失败也老老实实、清清楚楚地回传给模型,那我对着那条"谎报已完成"的回复排查的这段时间,就值了。

—— 别看了 · 2026