别急着甩锅模型：排查AI Agent故障的7个关键步骤

别急着甩锅模型：排查AI Agent故障的7个关键步骤

上个月，我花了整整一个晚上，看着一个Agent以近乎龟速爬完了一个任务。模型不断返回半截答案，工具调用被截断，表现得像彻底放弃治疗了。我差点就要换供应商了。结果打开仪表盘一看——这任务已经对着一个死掉的路由默默重试了两个小时。模型没毛病，是我的管道烂了。

和人类工程师遇到系统故障一样，AI Agent出问题时最本能的反应是怀疑模型能力不行。但根据多位开发者的实践经验，大多数情况下问题根本不在模型本身。下面是我现在固定使用的排查顺序，按成本从低到高排列。

任务真的在跑吗？

这听起来像是在侮辱智商，但真不是。我曾经花了四十分钟坚信模型在瞎编权限错误，实际上是我的worker在启动时就崩了，队列亮着红灯但根本没有消费者在处理。一个死掉的任务和一个卡住的任务，从外面看一模一样。

先用命令看看你的Agent进程是否还活着：

ps aux | grep -E "worker|agent" | grep -v grep

然后再看队列深度。如果消息在不断堆积但没有消费者接入，那问题出在模型的上游。修好supervisor、重启worker，那个“坏掉的模型”就自己好了。

什么是 worker 与队列？

在 Agent 架构中，worker 是实际执行任务的常驻进程，负责从消息队列（如 Redis、RabbitMQ、Celery broker）里取出待处理的 job 并调用模型、工具完成它。队列本身只是一个缓冲区——它接收生产者投递的任务并排队，但如果没有 worker 消费，任务就会一直堆着。supervisor（如 systemd、supervisord、PM2）则是管理 worker 生命周期、在崩溃时自动重启的守护进程。

文中提到的“队列亮红灯但没有消费者”，正是 worker 崩溃而 supervisor 未成功拉起、或 worker 没能成功注册到队列的典型症状。排查时除了 ps aux 看进程，还应检查 supervisor 状态（如 systemctl status 或 supervisorctl status）以及队列的消费者数量指标（如 Redis 的 LLEN、RabbitMQ 的 consumer count）。只有生产者、broker、消费者三段全部在链路里，任务才算真的“在跑”。

路由还通吗？

你的Agent通过某条路径和模型通信——可能是一个API端点、一个代理、或者负载均衡后面的自托管服务。模型本身完全健康，但这条路径可以挂掉。我遇到过一个DNS记录在周五晚上过期，然后我花了半个周六调试“模型输出退化”——实际上是一个连接超时在被指数退避重试。

用和Agent完全相同的方式直接打端点：

curl -s -o /dev/null -w "%{http_code} %{time_total}s\n" https://your-endpoint/v1/models

返回200说明路由是活的，问题在下游。返回502或超时，那你连模型配置都还没碰就找到元凶了。

指数退避（Exponential Backoff）与连接超时

当 Agent 请求失败时，很多客户端库会采用指数退避重试：第一次失败后等 1 秒，第二次等 2 秒，第三次 4 秒，以此类推并设置上限。这种策略本意是避免雪崩，但在路由层已经挂掉的情况下会产生一个迷惑性副作用：任务看起来“卡住”或“变慢”，日志里却只看到零星的重试记录，让人误以为模型在“思考很久”。

如果底层是连接超时（TCP 层握手未完成或 DNS 解析失败），每次重试都要等完整的 timeout 窗口（常见 30–60 秒），叠加退避倍数，几分钟内实际只发出了几次请求。因此文本建议用 curl -w 直接测量端点，就是为了绕过重试层，看到原始状态码和真实延迟。看到 DNS 过期、502、超时这类错误时，应先修路由，而不是调 prompt 或换模型。

调用链还是最新的吗？

Agent本质上是一条流水线：第一步的输出变成第二步的输入。如果上游某个环节改变了输出格式——比如一个工具从返回纯文本变成返回JSON、一个schema多了一个必填字段——那链条的下一步就会开始噎住。模型没做错，它只是收到了自己没预期的东西。

我是在更新了一个函数调用包装器、但忘了同步更新描述输出格式的system prompt之后才学到这课的。模型花了三个周期试图解析那些已经不再匹配预期格式的响应。修复方式是在prompt文件里改一行。

当输出看起来乱码时，diff一下步骤之间真正传输的payload——不是你以为发出去的东西，而是实际发出去的东西。

工具调用（Function Calling）与 Schema 契约

现代 Agent 普遍依赖函数调用机制：模型被提供一组工具定义（名称、参数 JSON Schema、描述），模型据此产出结构化的 tool_calls，由运行时执行并把结果回填。这条契约有两个关键属性——必填字段和返回格式。任一环节变化而另一端未同步，链条就会在下游“噎住”。

文中提到的“工具从纯文本改成 JSON”“schema 多了必填字段”，属于典型的契约漂移。注意：报错通常不会直接指向根因，而是表现为模型反复解析失败、输出乱码或重试。排查时应 diff 实际传输的 payload（用日志或中间件抓包），而不是阅读代码里“以为会发出”的内容。保持 prompt、schema、工具实现在同一版本控制下联动更新，是避免这类问题的标准做法。

上下文重建吃掉了预算吗？

这个坑让我栽得很惨。Agent有时会在任务中途重建上下文——重新总结之前的对话轮次、重新拉取系统指令、重新组装工具定义。如果你用的是有token上限的方案，那次重建可能一口气吃掉你剩余的全部预算。模型随后开始截断输出，因为它没有空间了。

如果一个任务之前运行良好、突然之间响应变短变蠢，检查你的token账本：

**上下文窗口与 Token 预算**

每个模型都有固定的**上下文窗口**（如 8K、32K、128K tokens），它同时容纳 system prompt、工具定义、历史对话和当前输入。**上下文重建**指的是 Agent 在任务中途重新总结历史、重新拉取系统指令或重组工具定义——这些动作本身会占用大量 token。

当重建消耗掉剩余预算后，模型收到的可用空间被挤压，输出会明显变短、被截断，或在推理中途“失忆”。这不是模型变笨，而是物理上限。常见触发点包括：撞到窗口限制自动摘要、手动重置会话、或框架的重建阈值被触发。应对方式是**监控 token 账本**（区分 prompt/completion/重建开销）、在日志里埋点标记重建事件，并通过拆分子任务、限制历史长度、外置记忆（向量库）等手段提前规避，而不是等预算耗尽后加钱换更大窗口的模型。
# 假设命令——你的追踪器会不同
grep "context_rebuild" jobs.log | tail -5

如果确实触发了重建，看看是什么触发的：撞上了上下文窗口限制、手动重置、还是自动总结阈值。知道触发原因之后，你要么提高上限，要么通过把任务拆小来提前避免重建。

数据源被限流或为空了吗？

你的Agent在拉数据——文件、API、文档，什么都可能。如果那个数据源开始返回429（被限流）或402（需要付费，针对计量API），你的Agent就坐在那里等一个永远不会到来的输入。然后模型超时，或者因为只能凭空脑补而产出垃圾。

盯住数据源的响应码：

# 你的fetch层实际收到了什么？
tail -f agent.log | grep -E "429|402|503"

429意味着你被限流了——退避一下、加大缓存力度、或者加第二个key。计量源上的402意味着账单没付或配额用完了。两个都不是模型的问题。

主路径也被限流了吗？

有时候数据源没问题，但你的Agent到那个源之间的路径退化了。一个被限流的代理、一条拥堵的VPN、一条突然开始质询你请求的Cloudflare规则。Agent无法到达它需要的地方，于是它停滞了，然后你怪模型慢。

我会跑一个简单的健康检查来探测完整路径——不只是端点，而是经过Agent实际使用的代理或隧道：

# 计量经过Agent路由的完整往返时间
time curl -s https://your-proxy/source-endpoint \
  -H "Authorization: Bearer $KEY" \
  -d '{"query":"ping"}' | jq .

如果直接打端点很快，但走完整往返很慢或失败，那就是路由问题。模型是在等网络问题解决，不是思考慢。

最后，才轮到模型

十次里面有六次，我能说服自己问题不在模型。只有当任务在跑、路由活着、调用链是最新的、没有重建吃掉预算、数据源返回真实数据、到数据源的路径也很快——所有这些都检查通过之后，输出依然崩坏（推理不一致、在同一任务上反复失败、拒绝正确使用工具）——这时候你才有资格去看模型本身是不是瓶颈。

最后这一步，恰恰是我以前最先开始怀疑的。它最难诊断、修复成本最高、而且最不可能是真正的问题。

这套排查顺序的核心逻辑很简单：从最便宜、最常见的故障点开始查起。一个死掉的worker、一条过期的DNS记录、一个被限流的API——这些问题的修复成本几乎为零，但它们伪装出来的症状和“模型变笨了”一模一样。在掏出信用卡换供应商之前，先花十分钟检查一下你的管道。