Agent排查指南：别再让模型背锅，用失败链定位真实错误

上周末我在调试一个客服 Agent它连续三次报了同一个错Tool execution failed。组里新来的同学第一反应是是不是这模型太笨了换个更强的。我拦住他把三次交互的全链路日志全部捞出来逐环节回放了一遍。结果发现每一次模型决策、参数解析、工具选择都是对的真正的坑埋在下游物流服务的返回数据里。这已经不是第一次遇到这种事了。做 Agent 开发这一年多我越来越确定一个结论Agent 的失败模型往往是最冤枉的那个背锅侠。报错信息越粗糙大家越容易把注意力集中在模型身上。这篇就聊聊我自己从看错误码到看失败链的排查思路转变以及一套可以直接落地的排查方案。1. Agent失败模型往往是最后一个背锅的1.1 我遇到的这个客服Agent是什么先交代一下背景。我维护的这个客服 Agent主要职责是辅助客服人员处理订单查询、物流跟踪和退换货操作。整体技术栈是 Python底层跑在一套通用的 Agent 框架上模型用的是大家熟悉的通用大模型工具侧接了 8 个内部服务接口。它在业务上的工作链路大概是这样的客服人员输入用户的问题原文。Agent 系统拼接上下文系统提示词、历史会话、当前可用工具清单。模型基于上下文做决策输出包含 thought 和 action 的结构化内容。Agent 调度器解析模型输出提取工具名和入参。调度器调用对应工具。工具执行内部逻辑访问下游服务。工具返回结果Agent 把结果回填给模型进入下一轮决策。任何一个环节出问题最后都可能被包装成一行笼统的错误码。这也是我这次排查踩坑的起点。1.2 最初的错误码有多粗糙我当时看到的生产日志是这样的[ERROR] 2025-05-31 14:23:07 | task_id8f3a2c | Tool execution failed就这一行。没有工具名没有入参没有异常栈没有 trace_id。如果你只看这行日志你能做的判断只有一个工具执行挂了。至于为什么挂、挂在哪、是谁导致的完全不知道。这种粗错误码在 Agent 框架里非常常见。很多框架在发布模式下会刻意把底层异常吞掉对外只暴露一个聚合后的状态。理由是避免把内部实现细节泄露给终端用户但副作用就是排障时的信息几乎为零。我当时看到这个报错第一反应就是去怀疑模型。1.3 我一开始也走了冤枉路说实话我一开始也踩进了怪模型的坑里。我以为是模型在生成工具参数时格式不对于是连续做了几件事在系统提示词里加了大量 few-shot 示例告诉模型参数一定要按这个格式输出。把温度从 0.7 降到 0让模型输出更稳定。换了两个参数结构化能力更强的模型做对比测试。结果呢连续调了两天错误码还是那个错误码一点面子都不给。恰好那段时间又是新版本上线前的联调窗口整个组都被这个报错卡住了。后来冷静下来我把模型原始输出打印出来对着看了一遍才发现模型生成的 thought 完全正常action 选对了action_input 里的字段也齐全。问题根本不在模型这边。从那一刻起我开始怀疑是排查方法本身出了问题。2. 为什么看错误码会带偏从结果定位到过程定位2.1 Agent的调用链任何一环断了都会报Tool failedAgent 的每一次交互都不是一个单点操作而是一条完整链路。我一般把它拆成 8 个环节用户输入入口。上下文组装系统提示词、历史消息、RAG 结果、工具列表。模型决策生成原始输出。输出解析从文本提取 JSON、校验字段合法性。工具调度选择工具、构建入参。工具执行。结果解析对工具返回值做清洗和转换。回填下一代模型输入。这 8 个环节里任何一个环节抛异常如果在外层只 catch 到一个 Exception然后打印 Tool execution failed里面 7 个环节的现场信息就全丢了。我后来复盘时想过如果当时我能早一点画出这张链路图就不会浪费两天时间去调 Prompt。排查的第一步不是看模型是看清整个 Agent 的执行链路。2.2 粗错误码为什么会吃掉真相粗错误码吃掉真相我认为有两个核心原因。第一个原因框架主动隐藏细节。为了不做过度堆栈泄露框架在 catch 异常时只记录str(e)也就是异常的消息部分。但 Python 里最关键的排查信息往往在traceback里比如具体是哪个文件哪一行出的错。只保留消息基本等于把定位线索引擎盖住了。第二个原因异步与并发导致的异常聚合。Agent 框架为了效率工具调用经常会放入线程池或协程中执行。子任务里抛出的异常在传递到主任务时有些框架只传递一个聚合异常状态原始 traceback 扔在子任务日志里如果没有统一的 ID 关联你根本捞不回来。这时候看错误码就像看一辆车的仪表盘只显示车辆异常但不告诉你哪个轮胎爆了、水温是不是高了。你只能瞎猜而猜的第一个对象往往是发动机质量不行——对应到 Agent 开发里就是模型能力不行。2.3 引入失败链Failure Chain分析我后来把排查思路做了一个根本性的调整不再盯着最后一个错误码而是看一次 Agent 交互从输入到输出的全链路状态记录。我管这套记录叫失败链。失败链的核心概念很简单它不是一个数字或字符串而是一条完整的事件流。这条事件流记录了用户输入了什么。系统给模型看了什么。模型输出了什么原始文本。解析器从中提取了什么。调度器给工具传了什么参数。工具内部做了什么、耗时多久、在哪一步抛了异常。工具返回了什么原始数据。模型下一轮拿到的上下文是什么。如果说错误码是事故现场的一张照片那失败链就是整条路线的行车记录仪。照片可能被裁剪过行车记录仪不会。有了这套思路接下来的问题就变成了失败链怎么搭3. 失败链要怎么搭埋点、记录、可视化3.1 我搭的失败链日志长什么样失败链不是玄学本质就是在 Agent 链路的每个关键环节加一层埋点。我做了一个非常轻量的采集器核心就一个数据结构和一个收集器。先定义一个环节记录from dataclasses import dataclass, field from typing import Any, Optional dataclass class LinkRecord: stage: str # 环节名称如 model_output / tool_execute duration_ms: float # 该环节耗时 input_value: str # 该环节的输入序列化 output_value: str # 该环节的输出序列化 error: Optional[str] # 异常信息无异常为 None trace_id: str # 全链路追踪ID meta: dict field(default_factorydict) # 附加信息再定义一个收集器class TraceCollector: def __init__(self, trace_id: str): self.trace_id trace_id self.records [] def record(self, stage, input_value, output_value, errorNone, duration_ms0.0, **meta): self.records.append( LinkRecord( stagestage, duration_msduration_ms, input_valueinput_value, output_valueoutput_value, errorerror, trace_idself.trace_id, metameta, ) ) def dump(self) - list[dict]: return [r.__dict__ for r in self.records]每个环节的埋点返回值统一塞进这个收集器最后再决定是打到本地文件、标准输出还是上报到日志平台。3.2 各环节具体记录什么只写一个数据结构是不够的关键是每个环节要记录完整的信息。我整理了一张表基本就是我埋点的字段清单环节必须记录的核心信息备注user_input用户原始输入不要只记录脱敏后的用脱敏字段单独处理context_build系统提示词版本、工具列表、历史消息条数用于判断是不是上下文拼接引入的问题model_output模型返回的原始字符串完整保留不要只保留解析后的 JSONparse_result解析出的 action 和 action_input如果解析失败记录原始文本和解析异常tool_dispatch被调用的工具名、实际入参注意这是模型输出解析后的入参要做序列化tool_execute工具执行耗时、异常栈、内部日志异常栈必须完整记录包括 tracebackresult_parse工具返回原始数据、清洗后的数据如果清洗失败记录原始返回结构context_update下一轮模型的输入情况记录回填的字段和大小有一个细节我必须强调记录模型输出的原始字符串。很多框架默认只记录解析后的 Python 字典但如果你能看到模型输出的原始文本第一次定位格式问题可能就只需要几秒钟。我因为只记录了解析后的内容而多花半天时间去复现这种亏吃过不止一次。3.3 关键用 trace_id 串起整条链失败链如果散落在不同日志流里跟没记录一样。所以我每次 Agent 会话启动时都会生成一个 trace_idimport uuid def new_trace_id() - str: return uuid.uuid4().hex[:12] # 示例 trace_id new_trace_id() # 如 a1b2c3d4e5f6这个 trace_id 会贯穿当前会话的所有日志。模型调用的日志带上它工具执行的日志带上它下游 HTTP 请求的 header 里也带上它。这样排查时只要拿 trace_id 一搜整条失败链就全部浮出水面。如果没有 trace_id排查时只能按用户 ID 时间窗口去捞日志日志量一大就非常费劲。所以我把 trace_id 当成 Agent 日志的第一等公民任何埋点都必须携带。3.4 别忘了 agent 安全日志脱敏既然要记录原始输入输出就必然会碰到用户隐私数据。客服 Agent 里尤其明显订单号、手机号、地址哪个都敏感。我的做法是在采集器里加一层脱敏逻辑。import re def mask_sensitive(text: str) - str: # 手机号脱敏 text re.sub(r(1[3-9]\d)\d{4}(\d{4}), r\1****\2, text) # 订单号中段脱敏 text re.sub(r(ORD_)\w{4}(\w{4}), r\1****\2, text) return text注意脱敏要在序列化之后、落地存储之前做。但排查时如果需要查看原始内容我会在本地开发环境通过环境变量开关临时关闭脱敏生产环境永远保持开启。这一点也是 Agent 安全里最容易被忽视的基础要求。4. 实盘排查一次真实失败链的逐步定位4.1 故障现场信息下面还原一次完整的排查过程。用户问题很简单帮我查一下订单 20250531001 的物流信息日志里的粗错误码依然是熟悉的那一行Tool execution failed。但这次我们有了 trace_id我直接用 trace_id 把整个失败链拉了出来。4.2 加载失败链记录捞出来的链路记录如下做了脱敏和精简trace_id: a1b2c3d4e5f6 [user_input] 输入: 帮我查一下订单 20250531001 的物流信息 [context_build] 系统提示词v1.7工具8个历史消息2条 [model_output] 原始输出: {thought:用户需要查询物流应使用QueryLogistics工具, action:QueryLogistics, action_input:{order_id:20250531001}} [parse_result] 解析成功, actionQueryLogistics, action_input{order_id:20250531001} [tool_dispatch] 派发成功, 目标工具QueryLogistics, 入参order_id20250531001 [tool_execute] 耗时204ms, 异常: AttributeError: NoneType object has no attribute strip [result_parse] 未执行只看这一条记录问题焦点一下子就缩小到了tool_execute这个环节。模型输出没问题解析没问题调度没问题工具执行时崩了。4.3 定位过程一步步追到底看到AttributeError: NoneType object has no attribute strip我第一反应是这个工具内部对某个字段做了.strip()操作但字段值是 None。我打开 QueryLogistics 工具的源码找到对应位置events resp.json().get(logistics_events) for ev in events: desc ev.get(description).strip() ...问题就出在ev.get(description)返回了 None直接.strip()就炸了。但到这里还没结束——准确的追问是为什么 description 会是 None于是我又沿链路往上游查。发现这个物流接口是最近刚升级过的新版本正常情况返回数组但如果物流信息还在初始化阶段logistics_events字段整体返回的是 None而不是空数组。下游服务的返回值结构违反了工具代码的预期。整个责任链清晰了模型正确。参数解析正确。工具调度正确。工具内部代码缺少对异常数据的防御性处理。下游服务在初始化状态下返回违反预期的字段类型。这和模型有什么关系完全没有。如果当时只盯着粗错误码去调 Prompt调到天荒地老也修不好。4.4 修复与验证修了两处。第一处工具内部做容错把无事件当成正常状态处理events resp.json().get(logistics_events) or [] if not events: return {status: initializing, events: []}第二处下游物流服务针对初始化中的场景返回明确的空数组和一个状态码initializing避免用 None 这种语义模糊的值表达还没有数据。修复之后我用同一个用户问题重新跑了一遍。失败链日志显示全部通过[tool_execute] 耗时156ms, 成功, 返回 {status:initializing,events:[]} [result_parse] 解析成功 [context_update] 上下文回填完成然后压测跑了一整晚十几个小时没有再出现一次Tool execution failed。5. 快速排查Tool call failed的通用方法踩过这次坑之后我自己总结了一套通用排查流程。如果你也被Tool call failed或者类似的粗错误码反复折磨可以直接按这套方法来。5.1 第一步把错误码变完整这是最便宜的一步。找到框架里 catch 异常的位置把logger.error(str(e))改成logger.exception(e)或者至少把traceback.format_exc()打出来。import traceback import logging logger logging.getLogger(__name__) try: result tool.execute(**action_input) except Exception: # 不要只打印 str(e)完整栈才有定位价值 logger.error(tool execute failed, trace_id%s\n%s, trace_id, traceback.format_exc())很多粗错误码其实就是当初写代码时图省事只打了str(e)。把这个改掉几个小时后你可能就能解决过去一周都查不出来的问题。5.2 第二步用 trace_id 捞全链路如果改了错误码还是不够那就进入失败链视角。要求每次 Agent 会话都有 trace_id然后按 trace_id 聚合所有环节日志。如果没有 trace_id退而求其次按用户 ID 时间窗口捞。但优先级低很多因为并发场景下同一用户的多个请求可能交错在一起区分成本很高。5.3 第三步区分责任边界捞到全链路之后最关键的判断就是这个 failure 到底该算在哪一环我整理了一张速查表排查时直接对照典型症状可能根因排查方向模型选错工具工具描述不清、工具列表太长、prompt 指令弱检查工具清单与提示词模型生成了不存在的参数名工具 schema 与模型训练数据中的惯例不一致检查参数名和描述解析器报 JSON 解析失败模型输出包裹了 markdown、多余字符检查解析器和模型输出原始文本调度器报参数校验失败模型输出与 schema 类型不完全匹配检查校验器、补充格式转换工具执行内部异常工具代码 bug、下游接口报错、数据格式异常打开工具内部日志和下游链路结果解析失败返回值结构与解析代码预期不一致检查工具返回的原始数据上下文更新失败回填数据过大、字段冲突检查 context 大小和字段拼接逻辑这个表不复杂但很实用。每次排查的时候先把症状归类顺着方向走基本不会跑偏。5.4 第四步做最小复现最后一步把失败链中的输入、上下文、工具结果固定下来构造一个最小用例不断重放。def test_repro(): user_input 帮我查一下订单 20250531001 的物流信息 context build_context(user_input) output mock_model_output(context) # 用失败链中记录的原始输出固定 action, action_input parse_output(output) result QueryLogistics(**action_input) # 直接调工具 assert result[status] initializing重放能稳定复现就逐步删减环节看到底删掉哪一环问题消失范围就锁定了。重放不出来就要怀疑是环境差异或者并发条件比如下游服务抖动、连接池耗尽、缓存过期。这类问题往往需要加并发压测才能暴露。6. 给Agent开发同学的几个排查习惯这套方法跑通之后我养成了几个固定的习惯写下来给同行参考。第一个习惯新项目第一天就埋好失败链而不是出了问题再补。之前有项目组犯过这个错上线第一周就遇到粗错误码结果发现日志里连 trace_id 都没有只能靠猜。补埋点比写功能还耗时。所以我现在的原则是Agent 项目启动时就把失败链日志的方案定下来宁可先不做界面也要先把链路日志打通。第二个习惯日志里同时记录原始输入和解析后结果。解析后结果方便看语义原始输入方便排查解析器问题。两者缺一不可。我见过太多只记录我给模型看什么模型回什么的日志中间那一层解析、传输、调度的过程全是黑盒。第三个习惯定期回放失败案例当作 Agent 体检。我大概两周会把生产环境最近的失败案例捞出来按失败链回放一遍。回头统计的时候会发现一个规律真正模型背锅的失败占比往往不到一半其余全是下游接口数据格式、字段类型不匹配、缓存设计缺陷、校验规则冲突这些编外因素。模型其实一直在背黑锅。关于这一条再多说两句。做 Agent 开发最大的成本往往不是模型 API 的费用而是排查链路的成本。模型输出的黑盒已经够让人头疼了如果连调用链、工具执行、下游依赖也是黑盒那整个系统就变成了一个多重黑盒。失败链排查本质上就是逐个打开这些黑盒让每个环节都变成白盒。你打开得越早背锅侠就越少。我个人的体会是Agent 排障的第一原则是归因要准归因不准调什么都是白调。别再把 Agent 失败都算给模型了。下一次看到Tool execution failed的时候冷静一下先把失败链日志拉出来看看。凶手很可能不在输出层而是藏在第三个环节的某个字段里。