阶段一 · 架构与核心机制

Agent Loop —— 循环如何让模型真正干活

模型只会"回答",不会"干活"。让它干活的那个引擎就是循环:把对话喂给模型,执行模型要求的工具,把结果填回去,再问模型,直到它决定停下。这一章拆开这个循环,讲清它为什么长成这样、每一部分解决了什么问题,最后对照我们自己的两份实现看差异。

具体回答三个问题:为什么需要循环?循环怎么转?什么时候停?

学习目标

  • 分清"直接调用模型""写死流程"和"让循环自己转"这三种用法的本质区别:决策权在谁手上。
  • 分清两个概念:一次完整运行,和其中的一轮。
  • 理解循环什么时候继续、什么时候停:不止看模型的停止原因,还有工具批、排队消息和钩子。
  • 看懂终止钩子从"返回布尔值"变成"返回一个决定"意味着什么。

一、问题:模型只说话,不干活

大模型有三种用法,区别全在"决策权在谁手上":

用法 决策者 调用模型次数 典型场景
直接调用 用户 1 次 翻译、摘要、问答
写死流程 你的代码 N 次,代码决定 文档流水线、检索增强
循环 模型 不确定,模型决定 编程助手、自动化任务

前两种里,流程是你预先写死的:第一步做什么、检查什么、第二步做什么。循环的关键转变是:步骤之间的流转由模型的输出内容驱动。模型说"我要读文件",你就去读;模型说"我知道了",你就停。你的代码只做两件事——把输入和工具结果喂给模型;模型要求调用工具就执行,否则结束。

完整的工具闭环是五步:

声明工具 → 模型请求调用 → 你执行 → 结果回填 → 再问模型 →(回到第二步)

Agent Loop 时序图

配图说明:一次工具调用的完整往返。模型给出"我要调用"的请求后,控制权交给外壳执行;结果作为一条新消息追加回历史,再随下一次请求一起发回模型。

二、一次运行,与其中的一轮

  • 一次运行:从"用户提交一句话"到"模型给出最终答复"的整个过程,中间可能调用很多次模型。
  • 一轮:一次模型调用,加上这次调用引发的这一批工具执行。

关键点:模型一口气要求读三个文件,这三个读取在同一轮里执行——它们都是同一次模型调用的产物。把结果填回去再问模型,才进入下一轮。

一次运行与一轮的嵌套关系

配图说明:外层是"一次运行",内部按轮切开。注意最后一轮没有工具调用——正是"没有工具请求"让循环收尾,而不是模型说了"我完成了"。

区分两者有实际意义:

  • 存档按"运行"组织:一个会话文件记录的是连续多次运行的轨迹。
  • 进度按"轮"刷新:每一轮工具调用是一屏进度。
  • 结果配对按"轮内调用编号"对齐:结果必须填回产生它的那次调用。

三、跟着一条消息走一遍

概念讲完了,看一次真实的发生过程。你输入"帮我看看这个测试为什么失败",按下回车。

第一轮:循环把"系统提示词 + 历史消息 + 你这句话"打包发给模型。模型回来说:我要读 tests/test_order.py。循环执行读取,把文件内容作为结果填回消息数组。

此刻的消息数组长这样(末尾新增两条):

[ ...历史, 用户消息, 助手消息(我要读文件), 工具结果(文件内容) ]

第二轮:循环再次打包发送——这次多出的两条也会一起发过去,所以模型"看得见"自己刚读到的内容。模型说:我要跑一遍测试。循环执行,填回输出。

第三轮:模型说:问题出在断言里把 100 写成了 1000。循环看这条回复——没有工具调用,说明它不打算再动手了。于是收尾,这次运行结束。

三个观察点:

  1. 每一轮只调用一次模型。模型一次要了三个工具,那三个工具也在同一轮里执行——它们是同一次调用的产物。
  2. 消息数组只增不减(除了压缩这种显式机制)。循环不做"删掉中间某条"这种事。
  3. "停"不是模型宣告的。模型只是没再要工具,循环据此判断"它不打算继续了"。这是人类定的一条工程约定,不是模型的自我认知。

哪些是内核,哪些是产品补丁

这一章后面会讲很多机制,读的时候建议始终分清两类:

类型 例子 能否去掉
内核(任何 Agent 都需要) 调模型、执行工具、把结果填回、看有没有工具调用 去掉就不叫 Agent 了
产品补丁(交互式编程助手的需要) 工作中插话、跑完再追加任务、按轮换模型、快满了先压缩 去掉仍然是能用的 Agent,只是不好用

分清这两类很有用:自己做产品时,先有内核,再按真实需求一块块加补丁;而不是一上来就照抄一个成熟产品的全部复杂度。

四、什么决定继续,什么决定停下

继续还是停,从来不是单一信号说了算。Pi 的判断来自三方合流:模型这次返回的停止原因、这一批工具的执行结果、框架自己注入的状态。

先说模型侧。模型每次回答都会带一个停止原因,可以粗分成四类:

模型说 含义 循环怎么反应
正常说完 我认为任务完成了 看有没有排队消息,没有就结束
我要用工具 我还需要外部信息 执行这一批工具,然后继续
出错了 / 被中断 这次调用没成功 立即结束本轮运行
被长度截断 输出到上限被切断 这一批工具调用全部作废,不冒险执行

最后一条值得单独说:输出被截断时,工具调用的参数可能只写了一半——比如删除路径被切成两段。执行一个参数残缺的删除指令是危险的,所以 Pi 选择整批作废并回填错误,让模型知道"这批没跑成,你重来一次",而不是赌运气。

再说工具侧和框架侧:

  • 如果这一批工具全部声明"调用我之后就该结束",循环会在本轮结束后提前收尾,不再问模型。
  • 用户在你等待期间插话(转向指令),会在两个时机被吸收:外层循环开始时,以及压缩这类耗时准备结束后——避免打字被吞掉。
  • 队列里的跟进消息(follow-up)会在模型本可以停下时被取出,让运行再延续一轮。

双层循环

循环是两层的,两层管的事不一样:

外层(一直转,直到真的该停)
  ├─ 处理跟进消息
  ├─ 判断是不是该结束
  └─ 结束后发出"运行结束"

内层(本轮还有工具要跑,或还有插话没处理)
  ├─ 发出"轮次开始"
  ├─ 请求模型(流式)
  ├─ 看停止原因
  ├─ 执行这一批工具
  └─ 发出"轮次结束"

一句话记:内层管"这一轮还有活没干完",外层管"刚想收工又被塞了新活"。

五、钩子:不改循环也能改行为

产品层经常需要在不碰循环代码的前提下改变行为。Pi 为此留了一组钩子,可以理解成"循环开到一半时给你打的几个电话":

时机 钩子能做什么
每次发请求之前 换上下文、换模型、换思考强度
两轮之间 同上,但发生在上一轮收尾之后
一轮结束、还没发"轮次结束"时 决定"就此结束"还是"再跑一轮"
需要用户插话时 从队列里取转向指令
需要跟进消息时 从队列里取跟进消息

其中"决定结束还是继续"这个钩子,在 1.x 里被重写过一次,值得单独讲。

终止钩子的变化

旧版本里它叫"这轮之后要不要停",返回一个布尔值,而且只对正常回复生效——出错和被中断时会直接跳过它。

新版本改成了"这轮之后怎么走",返回一个决定:结束,或者明确要求"再跑一轮"。几个细节:

  • 它在助手回复和全部工具结果都落地之后、发出"轮次结束"之前被调用。
  • 它对出错和被中断的响应也会调用,但这两类响应本身是硬终止,返回值改变不了结局。
  • 返回"再跑一轮"时,即使这一轮没有工具调用,也会再发一次请求——这是"模型还差一步"这种情况在框架层的表达。

为什么要改?因为"要不要停"是个布尔问题,而实际需求是三种:正常排下一轮、强制再跑一轮、就此结束。布尔值表达不了中间那种。

当前 Pi 行为

  • 循环由核心包提供,与具体模型服务商无关;继续或结束由模型停止原因、工具批、排队消息与钩子共同决定。
  • 工具默认并行执行;只要这一批里有一个工具声明"我需要独占",整批就改成串行。
  • 转向消息在两个时机被吸收:进入外层循环时,以及耗时准备结束后。
  • 跟进消息在内层自然停下之后、外层收尾之前读取。
  • 输出被长度截断时,整批工具调用作废并回填错误结果。
  • 终止钩子返回的是"结束 / 继续"这样的决定,不再是布尔值。

代码里的名字

通俗说法 代码里的名字
一次运行 运行开始 / 运行结束事件
一轮 轮次开始 / 轮次结束事件
模型停止原因 stopReason(正常、要用工具、出错、被中断、被截断)
终止钩子 finishTurn(旧名 shouldStopAfterTurn 已删除)
发请求前的钩子 prepareRequest
两轮之间的钩子 prepareNextTurn
取插话 / 取跟进 getSteeringMessages / getFollowUpMessages

源码位置

  • packages/agent/src/agent-loop.ts:循环本体、工具批调度、截断处理。
  • packages/agent/src/types.ts:钩子与事件的类型定义。

在 Pi 里怎么操作

循环不需要手动触发——启动后输入一句话就进入循环;终端界面里每一轮工具调用、每一条消息更新,都是循环的可见投影。

Python 实验

我们有两份实现,各自说明一件事。

第一份:只讲"谁能决定下一步"

agent_loop.py 用"脚本化的假模型"把循环压到最短:假模型预先写好一串步骤,循环照着走。

for turn in range(1, max_turns + 1):
    step = model.next_step(prompt)
    if step is None:                       # 脚本耗尽:模型没说"我完了"
        errors.append(RunError(code="script_exhausted", ...))
        return _trace(...)
    if isinstance(step, str) or isinstance(step, FinalText):
        return _trace(prompt, step, ...)    # 终止
    # ToolRequest:执行并把结果回填,进入下一轮

三个设计点:

  1. 最大轮数先于一切校验:防失控是循环的第一道参数检查,参数不合法直接返回一份"运行记录",而不是抛异常——循环的产物是数据,不是副作用,这样测试才能断言它。
  2. "脚本耗尽"也是一种错误:模型停在没有给出最终答复的地方,循环不能装作正常结束。让这个状态显式可见,比悄悄返回空字符串诚实得多。
  3. 字符串和最终文本都算终止:这就是"停止原因"最朴素的模拟——工具请求之外的任何一步,都走向终止。

第二份:完整的最小循环

mini_agent.py 的 run_agent_loop 才是真正能跑的版本:它真的调用一个模型接口、真的执行工具、真的把结果填回消息数组。

for turn in range(1, max_turns + 1):
    assistant = _ask_model(provider, model, system, messages, tools)
    messages.append(assistant)                 # 历史由外壳维护
    yield MessageStartEvent(message=assistant)
    yield MessageEndEvent(message=assistant)

    if assistant.stop_reason in {"stop", "error"}:   # 停止原因决定去留
        yield TurnEndEvent(message=assistant)
        yield AgentEndEvent(messages=tuple(messages))
        return

    for call in assistant.tool_calls:          # 一轮内的一批工具
        result = _execute_call(call, tools)    # 未知工具/异常都变成错误结果
        messages.append(ToolResultMessage(...))
        yield ToolExecutionEndEvent(...)

    yield TurnEndEvent(message=assistant)
    yield TurnStartEvent()

对照 Pi 的真实实现,一一对应关系是:_ask_model 对应"流式请求助手回复",_execute_call 对应"执行工具批",yield 事件 对应"发事件"。

而且这份实现刻意简化了三件事:没有转向与跟进钩子、工具只串行、没有取消信号。这不是偷懒——这三件都是产品层问题,不是循环的本质。简化之后,循环的骨架反而更清楚。

有一处语义差异值得记住:我们的教学模型串行执行工具,任一结果声明"到此为止"就结束;而 Pi 是并行批,必须整批都声明终止才提前结束。方向一致,差别在并发程度。

Tau 的 tau_agent/loop.py 是同样的循环,只是异步版,并且完整保留了钩子。

python3 -m learn_pi_lab lab agent-loop   # 脚本化演示:正常终止 / 未知工具 / 工具抛异常
python3 -m learn_pi_lab lab mini-agent

失败与边界实验

lab agent-loop 的三条路径,每条都回答"谁发现错误、错误是否回填、有没有副作用":

场景 谁发现 回填给模型? 副作用
正常终止 模型(停止原因) — 无
未知工具 外壳(注册表里查不到) 是,错误结果回填 无(什么都没执行)
工具执行抛异常 外壳(执行器包裹) 是,标记为错误 可能已产生部分副作用
输出被截断且带工具调用 外壳(参数完整性不可信) 是,整批作废回填 无(宁可全失败)

关键观察:错误回填让模型有机会自救——换个工具、改个参数再试。而直接终止会让一次可恢复的失败毁掉整个任务。截断的处理是反方向的取舍:宁可毁掉这一批,也不执行可能残缺的危险操作。

python3 -m unittest tests.test_01_agent_loop -v

这一模块的核心代码在核心代码导览 · Agent Loop 循环骨架有逐段解读。

验证方式

python3 -m unittest tests.test_01_agent_loop tests.test_13_mini_agent -v

边界与安全

  • 循环本身不设防:谁提供消息、谁执行工具、谁决定结束,都由外壳控制。拦截、限流、取消必须包在循环外面。
  • 最大轮数是防失控的最后防线;真实产品还应支持取消令牌。
  • 截断时宁可失败工具调用,也不要执行参数可能被截断的调用——安全优先。

自测三问

  • 模型一次性要求读三个文件,这算几轮?为什么?
  • 如果模型说"我改好了"但同时还要再跑一次测试,循环会停吗?依据是什么?
  • 终止钩子从"返回布尔值"改成"返回决定",解决了什么表达不了的问题?

回顾

  • 决策权在模型:步骤流转由模型输出驱动,外壳只负责执行。
  • 一次运行包含多轮:存档按运行,进度按轮,结果按轮内调用编号配对。
  • 停下是多方合流:停止原因、工具批、排队消息、钩子与取消共同决定;截断时宁可失败也不执行残缺调用。
  • 双层循环 + 一组钩子:循环稳定,变化都从钩子发生。

循环只负责"转",工具怎么被管住、结果怎么填回去,是下一章的主题——工具系统。