Agent 跑不起来,多半不是软件坏了。你要先分清:请求到底卡在中转站那一层,还是卡在 agent 自己的配置、工具调用或上下文管理上。分不清这两层,重装三遍也白费。这篇给一条从下往上的排查顺序,每一格告诉你查什么、看到什么现象算过、什么情况下不适用。
Agent 跑不起来,第一反应往往是重装。装完还是报错,又开始怀疑中转站是不是跑路了。其实多数时候你连是哪一层出的问题都没分清。中转站和 agent 是两个独立的东西,一个只负责把请求转发出去,一个负责读任务、拆步骤、调工具。哪层坏了,现象不一样,处理方式也不一样。
下面这条顺序是从下往上走的:先把接口这层验通,再回头查 agent 的配置和工具调用。每一格都告诉你查什么、看到什么算过关。别跳步,跳步最容易白折腾。
先分清:一边供接口,一边干活
中转站干的事很单纯:你发请求,它转发到上游,再把结果拿回来。它不懂你的业务,也不会替你想下一步该干啥。Agent 是外面那层壳,它要的是一个能稳定回话的接口,接口不稳,它上面的逻辑写得再好也白搭。所以排查的第一步不是看 agent 日志里那句「调用失败」,而是把这两层拆开看。
有个很省事的判断口诀:拿一条最简单的单轮请求去打中转站,能通,说明接口这层基本没问题,问题多半在 agent 的配置或工具调用;连这条都通不了,就先别碰 agent 的任何设置,老老实实查地址、Key、模型名。
| 现象 | 大概率在哪一层 | 先查什么 |
|---|---|---|
| 单条请求能通,agent 跑不动 | agent 这层 | 上下文长度、超时、工具调用参数 |
| 单条请求就报错 | 中转站或网络这层 | base url、Key、模型名 |
| 跑到一半断掉 | 两边都可能 | 是否流式、输入是否太长 |
| 时好时坏 | 网络或限速 | 自己这端并发和重试逻辑 |
从下往上排查:四格逐个过
这四格按顺序过,前一格不过就别看下一格。很多人一上来就翻 agent 的提示词模板,其实前面三格里随便一个填错,后面怎么调都是白费。
- 第一格:地址和 Key看 base url 尾部有没有多写斜杠,模型名和站点后台列出来的对不对得上,Key 复制时有没有带上首尾空格。这三样错一个,请求就发不出去。
- 第二格:单轮请求打一次用最简单的请求打一发,把返回的报错原文整段记下来。agent 日志里那句「调用失败」什么信息都没有,原始报错才看得出是权限、模型名还是超时。
- 第三格:agent 侧参数对齐重点看上下文长度上限、超时秒数、并发数、是否强制流式。这几项和中转站的口径对不上时,最容易出现「单条能通、agent 就是不行」。
- 第四格:工具调用和模板前面三格都过了才轮到这层。看工具调用的入参格式、返回解析、提示词模板里的占位符有没有漏填。这层的问题表现为「能回话但结果不对」,不是「连不上」。
报错原文对号入座
拿到原始报错之后,别急着搜,先对号。下面这几类是最常见的,现象和处理方向差别不小。
- 连不上或超时:先量一下自己网络到站点的延迟基线,再排除是不是站点那头在限速或临时不稳,别一上来就换 Key
- 提示模型不存在或无权限:九成是模型名写错,或者这把 Key 所在的分组没开这个模型,去后台核对分组权限
- 跑到中途断流:多半是上下文超了,或者站点流式输出不稳,把输入缩短再打一次就能分辨是哪一种
- 偶发失败但重试就好:记下频次和发生的时段,先排除自己这端的并发和重试逻辑,再考虑换站
记报错的时候多留一步:原文、时间、当时用的模型名和参数,一起存下来。后面要拿去找站点客服或者自己复盘,这几样缺一样都得重来。
什么情况下这套顺序不管用
这套顺序的前提是 agent 通过中转站调远程模型。前提一变,前面几格查的对象就变了,硬套只会浪费时间。
- agent 用的是本地模型或自建服务:前面三格的对象换成查本地进程有没有起来、端口通不通、显存够不够
- 站点刚发过公告调整分组或限速:先去看公告,别翻配置,你改半天可能人家那头本来就在调整
- 团队多人共用一把 Key:先确认是不是别人把额度跑光了或触发了风控,再谈技术排查
- agent 框架自身有已知 bug:查框架的 issue 和版本说明,这种情况下接口是好的,错在框架解析
还有种情况容易误判:换了个新模型名,请求通了但结果答非所问。这不叫中转站坏了,是模型能力和你的提示词没对上,属于 agent 这层的活,别拿去烦站点客服。
判断标准说到底就一句:先证明接口这层能稳定回话,再谈上面的业务逻辑。接口没验通就去调 agent,等于地基没打就装修。想省事,平时把站点状态和价格变动留意着,出问题时才好排除是不是外部因素。
下一步把常用中转站的状态和价格变动放在一个页面盯着,出问题时能快速排除是不是站点那头在调整,比自己瞎猜快得多。→常见问题
agent 报「连接失败」就一定要换中转站吗?
不急。先用最笨的方式单独打一次接口,能通就说明站没问题,问题在 agent 的地址写法、超时设置或代理配置上。只有单打也连续失败、并且换个工具同样失败时,才值得考虑换站。
中转站和 agent 到底哪个容易出问题?
看现象。稳定输出但内容答非所问,偏 agent 侧;请求本身报错、断流、超时,偏接口侧。实际用下来,新手卡住的地方大多在配置那几格,而不是站点本身有多差。
怎么确认是站点限速还是自己的问题?
把并发降到一、把重试关掉,用同一个请求连打几次看间隔。全部成功说明是自己这端压太狠;仍然失败就换个时段再试一次,两个时段都不行再去找站点的状态页或客服核对。