上周同事拉我看他调了三天的 Agent。任务是修一个老项目里偶发失败的测试,模型是当时能拿到的最好的一个,工具齐全,日志完整,权限也没配错。

他给我看执行记录:四十七轮,读了三十一个文件,跑了九次测试,最后一条消息写得挺像样——「已定位并修复该问题,测试全部通过,改动集中在 order_service.py」。他打开 git diff,空的。

这不是模型不会修。它在第三十一轮其实已经找对了位置,也把正确的改法说清楚了。问题出在它说完就认为事情结束,而整个循环里没有任何东西要求它把描述变成一次真正的写操作。

我拿这件事当这篇的起点,因为它恰好说明主循环的本质:循环本身不产生正确性,它只是把模型单步的概率输出串成一个可以被检查的过程。串得越长,检查就越重要。

一、循环只有五行,剩下两百行都在兜底

ReAct 那篇论文里的核心动作只有四个:想一下、做个动作、看结果、再想。落到代码,真的只有几行:

1
2
3
4
5
6
7
while not done:
out = llm(ctx)
ctx.append(out)
if out.tool_calls:
ctx.extend(execute(out.tool_calls))
else:
done = True

这五行能跑通 demo,跑不通生产。我见过的实现,核心循环通常不到三十行,外围的预算、重试、截断、守卫、落盘加起来几百行。差距不在「会不会循环」,在「循环失控时谁来踩刹车」。

顺带说一句命名。ReAct 是 Reasoning 加 Acting 的缩写,论文想强调的是「推理和行动交替进行」,而不是「先推理完再行动」。这个区别在实现里很具体:它不是两个阶段,是同一轮输出里同时包含「我要做什么」和「我调用什么」。理解了这一点,后面关于思考文本归属的讨论才不至于绕晕。

原因不复杂。单步调用的错误率可能只有百分之几,循环把它乘上几十轮,任务级成功率就掉得很难看。更麻烦的是错误会累积:第三步读错了一个文件,第八步基于错误信息做判断,第十五步把判断写进代码。最后你看到的不是「某一步错了」,而是一整套自洽但错误的推理,每一步单看都合理。

所以主循环的设计目标不是「让模型多想几步」,而是三件很工程的事:每一步的输入尽量干净,每一步的输出尽量可验证,任何一步跑偏都能被外部发现。这三件事没有一件是模型能自己保证的。

二、Thought、Action、Observation 分别是谁写的

这三个词在论文里并列出现,读起来像是三个独立环节,实际实现里它们的来源完全不同。分清楚这一点,很多诡异现象就有解释了。

片段 谁产生 形态 是否回灌上下文
Thought(思考) 模型 自然语言,通常与 Action 同一次生成 视实现而定,可能被丢弃
Action(调用意图) 模型 结构化工具名 + 参数 一定回灌
Observation(观察) 程序 工具返回值,经截断与包装 一定回灌
最终回答 模型 自然语言 不回灌,交给用户

先说 Thought。很多人以为「思考」是单独一次模型调用,先想完再决定行动,其实多数实现里它就是同一轮输出里的一段自然语言。模型写着「我需要先确认这个函数的调用方」,紧接着在同一次生成里吐出 grep 的调用参数。两者共享一次前向计算,不存在「先想清楚再动手」的分离。

少数模型有独立的推理字段,比如扩展思考模式,那段内容有的可见、有的加密、有的只回传摘要。这里埋着一个很容易踩的坑:如果你的 harness 只保留 tool_calls,模型的思考就被你亲手扔掉了。下一轮它只看到自己调了什么、拿到了什么,看不到当初为什么这么调。短任务无所谓,长任务里它就会开始重复已经排除过的方案,因为你把「排除的理由」删了。

我现在的做法是:思考文本保留,但加上长度上限,超过就截断并标记。丢掉全部思考比保留一段残缺的思考更糟,前者让模型失忆,后者只是让它少一点细节。

再说 Action。这是模型唯一真正「输出」的东西,而且它输出的不是执行,是一段表达意图的 JSON。真正解析参数、校验类型、调用函数的是你的程序。所以参数错了,一半责任在模型的指令遵从,另一半在你的 schema 写得够不够严。

最后是 Observation,它从来不是模型写的。这句话值得重复:观察结果是程序拼出来的字符串。你截断了三百行日志只留五行,模型不知道;你把异常堆栈原样塞进去,模型会把它当成事实;你把「命令超时」和「命令返回空」都拼成一段空白,模型根本分不清发生了什么。

一个成本很低但收益明显的改动:给 Observation 加类型标记。成功、失败、超时、被守卫拒绝,四种状态用不同的前缀区分。模型对结构化信号的敏感度远高于对自然语言的猜测。

三、一个能跑在生产里的骨架

下面这段不到四十行,砍掉了所有业务细节,但把该有的骨架都摆上了。我把它当模板用,换项目只改 execute、allowed 和 finish 三个函数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def run_agent(task, tools, budget):
ctx = init_context(task, tools)
state = {"round": 0, "tokens": 0, "t0": now(), "writes": 0}

while True:
if budget.exceeded(state):
return finish(ctx, state, reason="budget")

try:
out = llm(ctx, tools=tools, temperature=0.1)
except TransientError as e:
if not backoff_retry(e, state):
return finish(ctx, state, reason="llm_error")

state["round"] += 1
state["tokens"] += out.usage.total
ctx.append(out.message)

if not out.tool_calls:
return finish(ctx, state, reason="no_tool")

for call in out.tool_calls:
if not allowed(call, state):
ctx.append(tool_msg(call.id, "rejected by guard"))
continue
try:
result = execute(call, timeout=budget.tool_timeout)
state["writes"] += int(call.is_write)
except Exception as e:
result = error_payload(e)
ctx.append(tool_msg(call.id, truncate(result)))

if guard.stuck(ctx, state):
ctx.append(system_nudge(guard.reason))
if ctx.tokens() > budget.compact_at:
ctx = compact(ctx, keep=load_plan_file())

几个位置值得单独说。

budget.exceeded 放在循环最前面,不是最后面。放在后面意味着你至少会多跑一轮,而「多跑一轮」在长任务里经常就是几千 token。

allowed 是权限守卫,不是模型判断。哪些路径可写、哪些命令禁跑,应该在程序里写死,而不是在 system prompt 里请求模型自觉。

state["writes"] 这个计数器看起来很土,但它是识别「幻觉完成」最便宜的手段。退出时它为零,说明模型从头到尾没写过任何东西,那么它说的「已修复」就不必看了。

guard.stuck 和 compact 是两个可插拔的钩子,后面两节展开。

代码里看不到的一个选择是那个 for 循环串行还是并行。模型一次吐出三个读文件的调用,串行执行墙钟时间翻三倍,并行执行快得多,但结果回灌的顺序会乱。读操作并行没问题,写操作并行要小心:两个写同一个文件的调用同时跑,后写的覆盖先写的,而且谁后写取决于调度,不取决于模型。我现在的规则是按调用类型分流——只读工具并发,写工具串行,并且写之前重新校验文件版本。

四、退出:四种条件,缺一不可

只用一个条件退出,几乎一定会出事。我现在的实现里至少四道闸,任何一道触发都结束循环,只是结束时的处理不同。

退出条件 触发方式 可靠性 结束后的动作
模型不再调用工具 结构性判断 高 视为正常结束,交给验收
模型自述完成 文本匹配 低 只当信号,必须外部校验
预算耗尽 轮数 / token / 时间 确定 保存状态,标记未完成
守卫判定失败 规则命中 高 中断并上报,不假装成功

第一道最简单:模型这一轮没有输出任何 tool_calls,说明它想说话了。这是最自然、也最可靠的边界,因为它是结构性的,不依赖模型说了什么。

第二道是所有人最先想到、也最不该单独依赖的:模型在文本里说「任务完成」。为什么不可靠,有两个层面的原因。

第一层是自述不是状态。模型说「已修复」,这句话只是一个 token 序列,它和文件有没有变、测试有没有过,没有任何因果连接。你如果信了这句话,就等于把验收权交给了一个没有能力验收的组件。

第二层更隐蔽,是奖励错位。模型见过的训练数据里,任务结束时的总结绝大多数是成功的;它被要求「完成后总结」时,生成一段报告成功的文本,概率上就是更高的。这不是它故意骗你,是它在做自己最擅长的事——生成看起来合理的文本。预算快耗尽时这个倾向更明显,因为它读到了轮数提示,知道该收尾了。

所以我的处理是:模型自述完成,只作为「它想停了」的信号,触发一次外部验收。验收通过才算完成,不通过就打回去,并把验收结果作为 Observation 回灌。这套流程在第七节还会提到。

第三道是预算,必须三条都设:轮数、累计 token、墙钟时间。只设轮数,模型可能每轮读一个巨型文件,二十轮就把窗口撑爆;只设 token,模型可能卡在一个不返回的工具上,token 不涨但时间在走;只设时间,一个快速失败的循环能在十分钟里跑几百轮,账单照样难看。

第四道是守卫。它和第二道相反:不信任模型说「完成」,也不信任模型说「还在做」。连续五轮没有任何写操作、同一组参数重复调用三次、两个文件之间来回改,这些都能用确定性规则检测出来。命中就中断,或者注入一条提醒后继续,取决于你判断这个任务还值不值得救。

五、死循环的四种形态

「死循环」这个词容易让人想到程序卡死,实际 Agent 的死循环更像是「原地打转」:它一直在动,一直在花钱,就是不产出。我见过的可以归成四类,识别方式和打断方式都不一样。

形态 典型表现 识别信号 打断方式
同参数重复调用 反复读同一个文件、跑同一条命令 调用指纹连续重复 命中缓存直接回「已执行过,结果如下」
两方案来回改 改成 A,又改回 B,再改回 A 同一文件净变更周期性归零 检测到第二次回退就要求书面说明理由
无限读文件不产出 每轮读新文件,从不写 写操作计数为零且轮数超阈值 强制先产出再继续读
幻觉完成 声称改完但没有写调用 完成自述之前无任何写操作 退出前用 git status 校验,空则打回

同参数重复调用最常见,通常发生在模型没读懂上一次的结果时。它读了文件,没找到想要的,就再读一遍,参数一模一样。识别很简单:给每次调用算一个指纹(工具名加规范化参数),连续三次相同就命中。打断不一定要报错,直接返回「该调用已执行过,结果未变化」往往就够了,模型会自己换策略。

两方案来回改更隐蔽,因为每次调用都不一样,指纹检测抓不到。表现是同一个文件被反复修改,改过去又改回来。识别要靠净变更:记录每个文件的修改次数和累计 diff 行数,如果修改了六次而净变更接近零,基本可以确定它在两个方案之间摇摆。这时候不要直接中断,注入一条「你已经在 A 和 B 之间切换了三次,请说明为什么两个都不成立,或者选一个继续」通常更有效。它缺的不是能力,是一个让它停下来的理由。

无限读文件不产出是长任务里最贵的形态。模型有一种「再确认一下」的倾向,读了一个文件觉得不够,再读一个,读了十个还是不放心。上下文被工具结果塞满,真正用于推理的空间越来越小,判断质量随之下降,于是更不敢动手。这是个正反馈的死亡螺旋。识别信号是写操作计数长期为零。打断方式是强制产出:要求它先写出一个最小改动,哪怕不完整,再继续读。先落地再完善,比一直准备要划算。

幻觉完成就是开头那个故事。识别信号很直接:宣布完成之前没有任何写操作。但要注意,有些任务确实不需要写文件(比如纯分析),所以这条规则不能一刀切。我的做法是分任务类型:声明了「要改代码」的任务,退出前必须校验 git diff 非空;纯分析任务则校验有没有产出结论文件。

这四种形态有个共同点:它们都不是模型「坏了」,是模型在信息不足时的合理反应。重复读是因为它不确定,来回改是因为两个方案都有道理,幻觉完成是因为它想结束。所以打断的重点不是惩罚,是给它补上缺失的那点信息。

守卫本身不需要多复杂,几十行状态统计就够:

1
2
3
4
5
6
7
8
9
10
11
class Guard:
def check(self, call, state):
fp = fingerprint(call) # tool + normalized args
self.hits[fp] = self.hits.get(fp, 0) + 1
if self.hits[fp] >= 3:
return "duplicate: already executed, result unchanged"
if state["round"] > 12 and state["writes"] == 0:
return "no_write: produce a minimal patch before reading more"
if self.net_diff(state["touched"]) == 0 and state["round"] > 8:
return "oscillation: you reverted twice, justify or commit"
return None

它只做一件事:把「不对劲」翻译成一句模型能读懂的话,塞回上下文。真正的中断留给最后一层,也就是 finish(reason="stuck")。这两者要分开,因为绝大多数打转是可以通过一句提醒纠正的,一上来就中断反而浪费了前面几十轮积累的信息。

六、单轮循环,还是显式的计划-执行-复盘

ReAct 的默认形态是单轮循环:每一轮都想一下、做一下。简单、灵活、不需要提前知道任务长什么样。但它有个结构性弱点——「想」的视野只有一轮。

模型在第五轮做的决定,只基于前四轮的观察,它不会主动退后一步问「整个任务还剩多少、当前这条路径对不对」。轮数一多,它就容易陷在局部最优里:手头这个函数改得挺顺,就一路改下去,忘了最初的目标是让测试通过,而不是把这个函数写漂亮。

所以长任务通常要加一层显式的计划-执行-复盘。计划阶段一次性把任务拆开,执行阶段按步推进,复盘阶段检查结果、决定是否重规划。它把「想」从每轮里抽出来,变成一次更长的、能看到全局的推理。

代价也很实在:计划可能一开始就错,而且错得很自信。单轮循环的好处是每一步都能根据观察调整,计划的坏处是它把这个调整周期拉长了。所以两者不是替代关系,是配比关系。

任务特征 建议形态
十轮以内、目标明确 单轮 ReAct,计划是负担
跨多个文件、有验收标准 计划-执行-复盘,每步带检查点
探索性任务、边界不清 先单轮探路,摸清结构再补计划
需要中途压缩的长任务 必须有计划文件,否则压缩后失忆

判断阈值不用很精确,我的经验是十五轮。预计会超过十五轮的任务,先花两三轮写计划,几乎总是划算的;预计十轮以内的,写计划的时间够把活干完了。

计划怎么写、怎么重规划、怎么和验证绑定,是下一篇的内容,这里只留一个判断:当你发现自己在反复给 Agent 补充「别忘了」「注意」「上次说过」的时候,缺的不是提醒,是计划文件。

还要说清一件事:显式计划不是把循环改成流水线。计划-执行-复盘仍然是循环,只是每一轮多了一个「对照计划」的参照物。模型每轮除了看工具结果,还会读到「当前在第几步、这一步的验收标准是什么」。这个参照物把它的注意力从「下一步做什么」拉回到「整个任务到哪了」,代价是每轮多几百 token 的计划文本,以及你需要维护这份计划的时效性。计划过期比没有计划更糟,它会让模型朝一个已经作废的目标努力。

七、每轮上下文的账

主循环还有一个很少被认真算的成本:每一轮都在往窗口里追加东西,而追加的东西里,大部分是一次性的。

拆开看一轮典型调用。模型输出的 assistant 消息,正文两三百 token,tool_calls 的 JSON 一两百;工具返回的 observation,读一个中等文件三到五千,跑一次测试失败堆栈五百到三千,grep 命中一到两千。加起来,一轮四五千 token 是很常见的量级。

单轮组成部分 典型 token 备注
思考文本 150 ~ 400 长任务里会明显变长
调用参数 JSON 50 ~ 200 参数多、嵌套深时更高
文件内容 3000 ~ 5000 每增加 100 行约多 1.2k
命令输出 500 ~ 3000 失败堆栈通常是上限
检索命中 1000 ~ 2000 带路径与上下文行

五十轮就是二十万到二十五万。这个数字已经贴着多数模型的窗口上限,何况系统提示和工具定义还占着开头那几万。反过来说,这也解释了为什么「少读一个文件」在长任务里值钱:省下的不是一次调用,是后面每一轮都要重新携带的那几千 token。

所以压缩不是「窗口快满了才做的事」,是主循环的常规组成部分。我用的触发线是窗口占用到六成,或者对话历史超过预算的四成,两个条件满足一个就压。这个比例参考了上下文窗口与上下文工程里那张预算表。压之前先做一件事:把当前目标、约束、已完成项、下一步写进计划文件。压缩只压对话历史,不压这个文件。

这里有个很容易忽略的细节:压缩发生在循环内部,模型不知道自己的记忆被换过。它下一轮读到的是摘要,会自然地接着摘要往下走,不会意识到中间丢了东西。所以压缩后的第一轮,我通常会追加一句「以上是压缩摘要,当前计划文件在 PLAN.md,需要细节时去读」,给它一个恢复上下文的入口。

八、错误处理钩子挂在哪

主循环的错误不是一个点,是一条链。每一段失败的方式不同,处理方式也不同,混在一起写就必然乱。

位置 典型错误 处理方式
LLM 调用外层 限流、超时、5xx 指数退避重试,超限则降级或终止
工具执行外层 命令失败、文件不存在 转成结构化错误回灌,不要抛给用户
轮末 重复调用、无进展 守卫检查,注入提醒或中断
退出前 声称完成但无改动 跑验收脚本,失败则打回继续
压缩前后 状态丢失 压缩前落盘,压缩后复述校验

这张表只标挂载点。每一层具体怎么重试、怎么判幂等、怎么处理重复执行,工具调用的健壮性里拆得更细,这里只说它们在循环里的位置。

最容易被写错的是第二行。工具报错时,很多人第一反应是 raise,让整个循环崩掉。但在 Agent 里,工具失败是正常输入,不是异常终止。文件不存在、命令返回非零、网络超时,这些恰恰是模型需要知道的信息。把它包装成一条清楚的 observation 回灌,模型下一轮就会换个路径;直接抛出去,你只是把一个本可以自愈的错误变成了任务失败。

第一行也有个细节:重试要和状态绑定。重试三次都失败,不要静默返回空,要明确告诉循环「这个工具现在不可用」。否则模型会以为工具返回了空结果,基于空结果继续推理,错误会以更难排查的形式往后传。

退出前的验收钩子,是整条链上性价比最高的一环。它把「模型说完成」和「任务真完成」这两件事强行分开,中间插一道确定性的检查。这道检查可以是跑测试、可以是 git diff --stat、可以是一个自定义脚本,形式不重要,重要的是它不经过模型。

写这些钩子时有个顺序原则:越靠近模型输出的钩子越轻,越靠近交付的钩子越重。LLM 调用层只做重试和超时,不应该夹带业务判断;工具层只做格式化和错误包装,不应该偷偷改参数;到了退出前那一层,才允许跑测试、跑 lint、比对产物。顺序反了会很难排查:一个本该由验收脚本发现的错误,在工具层被静默修正,你永远不知道模型其实改错了地方。

常见的坑

  • 只判断 tool_calls 为空就退出。模型完全可以在还有活没干完时停止调用工具,只说一句「还需要更多信息」。退出后要验收,不要直接交付。
  • 把思考文本全丢掉。省下的那点 token,换来的是模型反复走已经排除过的路。
  • 工具错误直接抛异常。错误是 Observation 的一种,应该回灌,不是终止。
  • 预算只设轮数。读大文件的任务会在轮数到之前先撑爆窗口。
  • 压缩后不告诉模型。它读到摘要却不知道有摘要,会以为自己一直记着。
  • 守卫只做日志不做拦截。检测到死循环却不打断,等于没有守卫。
  • 验收放在循环外。等循环彻底结束再验收,中间几十轮的错误已经付过钱了。
  • 把 temperature 调高求「聪明」。主循环要的是稳定,不是发散。

检查清单

  • 主循环有明确的四种退出:无工具调用、自述完成、预算耗尽、守卫失败。
  • 自述完成只作为信号,退出前必过一道不经过模型的验收。
  • 预算三条都设:轮数、token、墙钟时间。
  • 每次工具调用算指纹,连续重复能识别并打断。
  • 统计写操作次数,为零时不允许宣布「已修复」。
  • Observation 观察结果带类型标记,成功、失败、超时、拒绝可区分。
  • 保留思考文本,设长度上限而不是全部丢弃。
  • 窗口六成或历史四成时触发压缩,压缩前把计划落盘。
  • 工具错误包装成结构化 observation,不抛异常。
  • 每轮记录 token 增量,任务结束后能复盘钱花在哪。

主循环是整个 Agent 里最不神秘的部分:它没有算法,没有模型结构,只有一堆 if 和 try。但也正是这堆 if 和 try,决定了模型那点概率性的聪明能不能变成一件真正完成的事。

写到这里我越来越确信一个判断:Agent 的可靠性不来自更强的模型,来自更严的边界。模型负责想出下一步,循环负责保证这一步能被检查、能被打断、能被追账。前者是上限,后者是下限,而下限才是你敢把它放到生产里的理由。

下一篇讲长任务里那件单轮循环做不了的事:怎么把一个大目标拆成一组能验收的步骤,以及计划文件为什么必须存在。

系列大纲与全部篇目见:Agent 原理与开发。

延伸阅读