阶段一 · 架构与核心机制
Agent Loop —— 循环如何让模型真正干活
模型只会"回答",不会"干活"。让它干活的那个引擎就是循环:把对话喂给模型,执行模型要求的工具,把结果填回去,再问模型,直到它决定停下。这一章拆开这个循环,讲清它为什么长成这样、每一部分解决了什么问题,最后对照我们自己的两份实现看差异。
具体回答三个问题:为什么需要循环?循环怎么转?什么时候停?
学习目标
- 分清"直接调用模型""写死流程"和"让循环自己转"这三种用法的本质区别:决策权在谁手上。
- 分清两个概念:一次完整运行,和其中的一轮。
- 理解循环什么时候继续、什么时候停:不止看模型的停止原因,还有工具批、排队消息和钩子。
- 看懂终止钩子从"返回布尔值"变成"返回一个决定"意味着什么。
一、问题:模型只说话,不干活
大模型有三种用法,区别全在"决策权在谁手上":
| 用法 | 决策者 | 调用模型次数 | 典型场景 |
|---|---|---|---|
| 直接调用 | 用户 | 1 次 | 翻译、摘要、问答 |
| 写死流程 | 你的代码 | N 次,代码决定 | 文档流水线、检索增强 |
| 循环 | 模型 | 不确定,模型决定 | 编程助手、自动化任务 |
前两种里,流程是你预先写死的:第一步做什么、检查什么、第二步做什么。循环的关键转变是:步骤之间的流转由模型的输出内容驱动。模型说"我要读文件",你就去读;模型说"我知道了",你就停。你的代码只做两件事——把输入和工具结果喂给模型;模型要求调用工具就执行,否则结束。
完整的工具闭环是五步:
声明工具 → 模型请求调用 → 你执行 → 结果回填 → 再问模型 →(回到第二步)
配图说明:一次工具调用的完整往返。模型给出"我要调用"的请求后,控制权交给外壳执行;结果作为一条新消息追加回历史,再随下一次请求一起发回模型。
二、一次运行,与其中的一轮
- 一次运行:从"用户提交一句话"到"模型给出最终答复"的整个过程,中间可能调用很多次模型。
- 一轮:一次模型调用,加上这次调用引发的这一批工具执行。
关键点:模型一口气要求读三个文件,这三个读取在同一轮里执行——它们都是同一次模型调用的产物。把结果填回去再问模型,才进入下一轮。
配图说明:外层是"一次运行",内部按轮切开。注意最后一轮没有工具调用——正是"没有工具请求"让循环收尾,而不是模型说了"我完成了"。
区分两者有实际意义:
- 存档按"运行"组织:一个会话文件记录的是连续多次运行的轨迹。
- 进度按"轮"刷新:每一轮工具调用是一屏进度。
- 结果配对按"轮内调用编号"对齐:结果必须填回产生它的那次调用。
三、跟着一条消息走一遍
概念讲完了,看一次真实的发生过程。你输入"帮我看看这个测试为什么失败",按下回车。
第一轮:循环把"系统提示词 + 历史消息 + 你这句话"打包发给模型。模型回来说:我要读 tests/test_order.py。循环执行读取,把文件内容作为结果填回消息数组。
此刻的消息数组长这样(末尾新增两条):
[ ...历史, 用户消息, 助手消息(我要读文件), 工具结果(文件内容) ]
第二轮:循环再次打包发送——这次多出的两条也会一起发过去,所以模型"看得见"自己刚读到的内容。模型说:我要跑一遍测试。循环执行,填回输出。
第三轮:模型说:问题出在断言里把 100 写成了 1000。循环看这条回复——没有工具调用,说明它不打算再动手了。于是收尾,这次运行结束。
三个观察点:
- 每一轮只调用一次模型。模型一次要了三个工具,那三个工具也在同一轮里执行——它们是同一次调用的产物。
- 消息数组只增不减(除了压缩这种显式机制)。循环不做"删掉中间某条"这种事。
- "停"不是模型宣告的。模型只是没再要工具,循环据此判断"它不打算继续了"。这是人类定的一条工程约定,不是模型的自我认知。
哪些是内核,哪些是产品补丁
这一章后面会讲很多机制,读的时候建议始终分清两类:
| 类型 | 例子 | 能否去掉 |
|---|---|---|
| 内核(任何 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:执行并把结果回填,进入下一轮
三个设计点:
- 最大轮数先于一切校验:防失控是循环的第一道参数检查,参数不合法直接返回一份"运行记录",而不是抛异常——循环的产物是数据,不是副作用,这样测试才能断言它。
- "脚本耗尽"也是一种错误:模型停在没有给出最终答复的地方,循环不能装作正常结束。让这个状态显式可见,比悄悄返回空字符串诚实得多。
- 字符串和最终文本都算终止:这就是"停止原因"最朴素的模拟——工具请求之外的任何一步,都走向终止。
第二份:完整的最小循环
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
边界与安全
- 循环本身不设防:谁提供消息、谁执行工具、谁决定结束,都由外壳控制。拦截、限流、取消必须包在循环外面。
- 最大轮数是防失控的最后防线;真实产品还应支持取消令牌。
- 截断时宁可失败工具调用,也不要执行参数可能被截断的调用——安全优先。
自测三问
- 模型一次性要求读三个文件,这算几轮?为什么?
- 如果模型说"我改好了"但同时还要再跑一次测试,循环会停吗?依据是什么?
- 终止钩子从"返回布尔值"改成"返回决定",解决了什么表达不了的问题?
回顾
- 决策权在模型:步骤流转由模型输出驱动,外壳只负责执行。
- 一次运行包含多轮:存档按运行,进度按轮,结果按轮内调用编号配对。
- 停下是多方合流:停止原因、工具批、排队消息、钩子与取消共同决定;截断时宁可失败也不执行残缺调用。
- 双层循环 + 一组钩子:循环稳定,变化都从钩子发生。
循环只负责"转",工具怎么被管住、结果怎么填回去,是下一章的主题——工具系统。