Agent任务失败时从哪里开始查？按调用链顺序定位故障

Agent 出错时，第一反应往往是调参数或换模型，但多数故障并不是模型本身的问题。
排查的正确起点是按调用链顺序缩小范围：先看请求有没有进入 Agent，再看模型调用是否返回，然后看工具执行是否成功，最后看状态存储有没有写对。
下面按这个顺序讲清楚每一步查什么、看哪里、怎么判断。

先收集请求入口的线索

在动任何配置之前，先拿到一次失败任务的完整标识。
Agent 一般会在入口生成一个请求 ID 或 trace ID，后续模型调用和工具执行都应该带着它。
如果没有，先用现有日志把同一时间段的记录关联起来。

需要收集的信息：

• 失败任务的请求 ID 和触发时间
• 用户输入原文，确认不是输入格式导致解析失败
• 任务最终返回的错误码或异常信息
• 同一时间段是否有其他任务也失败

判断条件：如果只有单个用户或单条输入失败，优先怀疑输入解析或工具参数；
如果同一时间段多条任务同时失败，优先怀疑下游服务不可用或限流。

检查模型调用是否正常返回

模型调用层最常见的问题是超时、限流和返回内容无法解析。
打开 Agent 的调用日志，找到失败任务对应的模型请求记录，重点看三个字段：

• status 或 error_code：是否出现 429、5xx 或超时
• latency_ms：耗时是否明显高于正常值
• finish_reason：是否因为长度限制被截断

如果日志里只有最终失败，没有单次调用记录，说明可观测性不足，需要先在调用入口补充 trace ID 和耗时字段，再继续排查。
这一步不解决根因，但能让后续定位有依据。

一个常见误区是把所有模型返回异常都归为模型质量问题。
实际上，429 通常是调用频率超过配额，超时可能是网络或下游排队，返回内容解析失败则多半是提示词格式或输出结构约束不够明确。
分别处理，不要混在一起改。

工具执行失败要看参数和返回

Agent 的工具调用是故障高发区。
日志里应该能看到工具名、入参和返回结果。
排查时按以下顺序看：

1. 工具名是否正确，有没有调用了不存在的工具
2. 入参字段是否齐全，类型是否匹配接口要求
3. 工具返回是否包含业务错误，而不是只看 HTTP 状态码
4. 工具执行耗时是否拖长了整个任务

如果工具返回 200 但业务字段表示失败，Agent 可能把它当成成功继续执行，最终结果就会异常。
这类问题在日志里表现为任务完成但输出不对，而不是任务直接报错。
遇到这种情况，先核对工具返回结构和 Agent 的判断逻辑是否一致。

状态存储和会话数据别漏查

有些故障不在调用链上，而在状态存储。
典型现象是任务重试后重复执行、上下文丢失、或者结果写入后查不到。
检查点包括：

• 会话 ID 是否在重试时保持不变
• 写入操作是否幂等，重复写入有没有覆盖正确数据
• 存储服务的连接和权限是否正常

如果任务失败后自动重试，而重试没有携带原会话 ID，就会出现上下文断裂。
这类问题看日志不一定明显，需要对比同一任务多次执行的记录。

修复后怎么确认问题真的解决

改完配置或代码后，不要只看一次成功就结束。
用同一类输入重复执行几次，确认：

• 失败任务使用的请求 ID 能查到完整调用链
• 模型调用、工具执行、状态写入三个阶段都有记录
• 相同输入不再触发原来的错误码
• 任务耗时和资源消耗没有明显上升

如果条件允许，保留一份失败时的日志样本，和修复后的日志对比字段差异，这比凭感觉判断更可靠。

几个容易踩的坑

• 只改超时时间不查原因：超时可能是下游变慢，盲目调大只会让故障更晚暴露。
• 忽略工具返回的业务错误：HTTP 200 不代表业务成功，Agent 需要显式判断返回结构。
• 重试不带会话标识：会导致上下文丢失或重复执行，排查时容易误判为模型问题。
• 日志字段不统一：请求 ID、工具名、耗时字段命名不一致，跨服务关联时非常费力。

Agent 故障排查的核心不是记住某个报错，而是建立从入口到存储的检查顺序。
先确认失败发生在哪一层，再针对该层看日志和参数，最后用重复执行验证修复效果。
这样即使遇到没见过的错误，也能按链路逐步缩小范围。