---
title: 第3章:Agent Loop —— 让模型转动起来的引擎
module: M03
displayOrder: 3
status: published
variant: python
counterpart: ch03-agent-loop
slug: ch03-agent-loop.python
summary: Agent Loop 是 Pi 的引擎。本章看模型如何被循环调用、停止条件如何决定下一轮。
prev: ch02-three-layer-arch
next: ch04-model-call
diagrams:
- id: 260702-ch03-trace-turn-nesting
file: /assets/260702-ch03-trace-turn-nesting.svg
caption: Trace 与 Turn 的嵌套结构
- id: 260702-ch03-stopreason-flowchart
file: /assets/260702-ch03-stopreason-flowchart.svg
caption: stopReason 驱动的循环决策流程
- id: 260702-ch03-streaming-replace
file: /assets/260702-ch03-streaming-replace.svg
caption: 流式响应原地替换的时间线
- id: 260702-ch03-steering-vs-followup
file: /assets/260702-ch03-steering-vs-followup.svg
caption: steering vs followUp 对比
- id: 260702-ch03-kernel-onion
file: /assets/260702-ch03-kernel-onion.svg
caption: Agent Loop 内核与叠加设计
---
import Diagram from '../../components/Diagram.astro';
> 前一章我们看了 Pi 的分层架构。架构只是"骨架"——Agent 真正的生命力来自"循环"。这一章,我们从最基础的问题出发:**为什么需要循环?循环怎么转?什么时候停?** 然后追踪一条用户消息的完整旅程,看清 Agent Loop 的每一次心跳。
---
## 一、引子:大模型的三种用法
在聊 Agent Loop 之前,我们先退一步,看看"使用大模型"这件事本身有几种模式。这对理解"为什么需要循环"至关重要。
### 模式 1:直接调用 —— "模型,回答我"
最原始、最直觉的用法。你构建好提示词,调用一次 API,拿到结果,完事。
```
用户输入 → 构建提示词 → 调模型 → 模型输出 → 展示结果
```
代码大概长这样:
```python
# ============================================================
# 【Python 改写】直接调用 LLM 的最简形态
# 原文 TS:
# const response = await llm.chat({
# messages: [
# { role: "system", content: "你是一个翻译助手" },
# { role: "user", content: "把这段代码翻译成 Python" },
# ],
# });
# console.log(response.content);
# ============================================================
# 概念对照:TS 的 await → Python 的 await;messages 是同样的 role+content 字典列表
response = await llm.chat(messages=[
{"role": "system", "content": "你是一个翻译助手"},
{"role": "user", "content": "把这段代码翻译成 Python"},
])
print(response["content"])
```
**核心工作在于"构建提示词"**。提示词写得好,结果就好。一次调用,一次输出,没有来回。
适用场景:翻译、摘要、问答、代码补全——凡是"一问一答"能搞定的事。
### 模式 2:Workflow —— "模型,你先做第一步,我检查一下,再做第二步"
当任务变复杂,你发现一次性很难得到满意结果。于是你把大任务拆成多步,每步调一次模型,步骤之间由**你的代码**控制流转。
```
用户输入 → [步骤1: 调模型分析] → [你的代码: 提取关键信息]
→ [步骤2: 调模型生成草稿] → [你的代码: 检查质量]
→ [步骤3: 调模型润色] → 最终输出
```
每一步模型只负责自己的那份工作,**决策权在你手上**——你知道什么时候该进入下一步,模型只是流水线上的一环。
适用场景:文档生成流水线、代码审查自动化、RAG(检索增强生成)。
### 模式 3:Agent Loop —— "模型,你自己决定怎么做"
到了 Agent 模式,你把决策权交给了模型。
```
用户输入 → 调模型 → 模型说"我需要读文件" → 执行读文件 → 模型看结果
→ 模型说"还需要搜索代码" → 执行搜索 → 模型看结果
→ 模型说"我知道了,答案是..." → 输出 → 结束
```
关键区别:**步骤之间的流转不再由你写死,而是由模型的输出内容来驱动。** 你的代码只做两件事:
1. 把用户的输入和工具执行结果喂给模型
2. 如果模型输出的内容里包含了工具调用请求,就执行它;如果没有,就认为任务完成了
至于"该调什么工具"、"该调几次"——这些由模型的输出内容决定。"什么时候该停"——这是**人类定义的规则**:当模型的一次输出中不再包含工具调用时,我们就认为循环可以结束了。
用一个对比表格,三种模式的区别一目了然:
| 维度 | 直接调用 | Workflow | Agent Loop |
|------|---------|----------|------------|
| 决策者 | 用户 | 你的代码 | 模型 |
| 模型调用次数 | 1 次 | N 次(由代码控制) | 不确定(由模型控制) |
| 核心工作 | 写提示词 | 设计流程 | 定义工具和循环 |
| 模型角色 | 执行者 | 流水线环节 | 自主决策者 |
| 典型场景 | 翻译、摘要 | 文档流水线、RAG | 编程助手、自动化任务 |
---
## 二、先搞清楚几个概念:Trace、Turn
在深入源码之前,有两个概念必须分清楚。它们经常被混用,但在 Pi 的代码里,每个都有精确的含义。
### Trace(一次完整运行)
一个 Trace 是从用户按下回车、到 Agent 彻底停下来、发出 `agent_end` 事件的**整个过程**。一个 Trace 包含多个 Turn。
```
一个 Trace(一次 agent_start 到 agent_end)
│
├── Turn 1:调模型 → 模型返回 toolUse(要读文件)→ 执行 read 工具
│
├── Turn 2:带着工具结果再调模型 → 模型返回 toolUse(还要改文件)→ 执行 edit 工具
│
└── Turn 3:带着工具结果再调模型 → 模型返回 stop(改好了,没有工具调用)→ agent_end
```
### Turn(一个轮次)
一个 Turn 的定义非常精确:**一次模型调用 + 这次调用触发的所有工具执行。**
每个 Turn 由一对 `turn_start` 和 `turn_end` 事件包裹。关键点:**一个 Turn 只有一次模型调用。** 模型返回了 toolUse → 执行那批工具 → 发送 turn_end → 这个 Turn 就结束了。把工具结果喂回去再调模型,那是**下一个 Turn**。
看代码就更清楚了。内层循环每一圈的结构(后面会详讲):
```python
# ============================================================
# 【Python 改写】内层循环每一圈的结构(伪代码)
# 原文 TS:
# while (hasMoreToolCalls || ...) {
# if (!firstTurn) emit(turn_start); // ← 新 Turn 开始
# 处理 pendingMessages
# streamAssistantResponse() // ← 一次模型调用
# 检查 stopReason
# executeToolCalls() // ← 执行这个 Turn 触发的一批工具
# emit(turn_end); // ← 这个 Turn 结束
# prepareNextTurn / shouldStopAfterTurn / 检查 steering
# }
# ============================================================
while has_more_tool_calls or pending_messages:
if not first_turn:
emit({"type": "turn_start"}) # ← 新 Turn 开始
handle_pending_messages(pending_messages)
message = stream_assistant_response() # ← 一次模型调用
check_stop_reason(message)
tool_results = execute_tool_calls(message) # ← 执行这个 Turn 触发的一批工具
emit({"type": "turn_end"}) # ← 这个 Turn 结束
prepare_next_turn() # 叠加钩子
if should_stop_after_turn(): break
pending_messages = get_steering_messages() # 再次检查 steering
```
**一圈内层循环 = 一个 Turn = 一次 turn_start → 一次模型调用 → 工具执行 → 一次 turn_end。**
如果模型在一个 Turn 中一口气要求了 3 个工具(read + grep + find),那这 3 个工具都在同一个 Turn 里执行——因为它们都是同一次模型调用的产物。但执行完毕后把结果喂回去再调模型的那一刻,就已经进入下一个 Turn 了。
### 所以 Trace 和 Turn 的关系就是
```
Trace(一次完整运行)
│ agent_start
│
├── Turn 1
│ │ turn_start
│ ├── 调模型 → toolUse → 执行工具(read + grep)
│ │ turn_end
│ │
├── Turn 2
│ │ turn_start
│ ├── 调模型 → toolUse → 执行工具(edit)
│ │ turn_end
│ │
├── Turn 3
│ │ turn_start
│ ├── 调模型 → stop → 没有工具
│ │ turn_end
│ │
│ agent_end
```
> 注意:首轮 Turn 的 `turn_start` 是在 `runAgentLoop()` 入口就发出的,然后 `runLoop()` 内用 `firstTurn` 标志跳过首圈的 turn_start,避免重复。
<Diagram file="/assets/260702-ch03-trace-turn-nesting.svg" caption="Trace 与 Turn 的嵌套结构" id="260702-ch03-trace-turn-nesting" />
**配图说明**:一个 Trace 外壳内嵌 3 个 Turn,每个 Turn 都是"模型调用 + 工具执行"的完整闭环。注意 Turn 3 没有 ToolCall(虚线框),它的 stopReason = stop 触发循环退出。
---
## 三、全景:一条消息的旅程,以及循环怎么转
你输入了"帮我读一下 src/main.ts"并按下回车。从这一刻起发生了什么?让我们站在高处看一遍全过程,同时把"循环怎么转起来的"和"循环什么时候停"一并讲清楚。**不必纠结每个细节**——后面会逐段拆解源码。
> 途中你会遇到四个反复出现的"实体":你的输入变成**消息(Message)**;Loop 调用**模型(Model)**来思考;模型要求的操作用**工具(Tool)**完成;每一步通过**事件(Event)**通知外部。驱动这四者反复运转的机制就是本章主角——**Agent Loop**。
### 流程全景
```
你按下回车:"帮我读一下 src/main.ts"
│
│ ① 你的输入变成一条消息
│
UserMessage { role: "user", content: "帮我读一下 src/main.ts" }
│
│ ② 进入循环(agentLoop 入口)—— agent_start(一个 Trace 开始了)
│
└── runLoop()
│
│ ③ 消息转换(AgentMessage → LLM 认识的 Message)
│
│ ┌── Turn 1 ──────────────────────────────────────────┐
│ │ turn_start │
│ │ ④ 调用 Model(每 Turn 仅一次模型调用) │
│ │ streamSimple(model, { systemPrompt, messages }) │
│ │ ↓ 逐 token 流式返回 │
│ │ AssistantMessage { │
│ │ content: [ ..., ToolCall { name: "read", ... } ],│
│ │ stopReason: "toolUse" ← 有工具调用,继续转 │
│ │ } │
│ │ ⑤ 执行 Tool(工具的五步管道,详见第5章) │
│ │ ToolResultMessage { content: [{ text: "文件内容" }] }│
│ │ turn_end │
│ └─────────────────────────────────────────────────────┘
│
│ 循环判断:stopReason 是 toolUse → hasMoreToolCalls = true → 继续
│
│ ┌── Turn 2 ──────────────────────────────────────────┐
│ │ turn_start │
│ │ ⑥ 第二次调用 Model(工具结果已追加到消息列表) │
│ │ streamSimple(model, { messages: [..., toolResult] })│
│ │ ↓ 模型看到文件内容,开始解释 │
│ │ AssistantMessage { │
│ │ content: [ TextContent { text: "这个文件..." } ],│
│ │ stopReason: "stop" ← 没有工具调用,准备停 │
│ │ } │
│ │ turn_end │
│ └─────────────────────────────────────────────────────┘
│
│ 循环判断:hasMoreToolCalls = false,pendingMessages 为空
│ → 内层循环退出
│ → 外层循环检查 followUp → 空 → 外层循环退出
│
└── agent_end(一个 Trace 结束,共 2 个 Turn)
```
### 循环怎么转:stopReason —— 唯一的信号灯
整个循环的"油门和刹车"集中在**一个字段**上:`stopReason`。模型每次返回的 `AssistantMessage` 里都带着它。
但在此之前,必须澄清一个关键认知:**模型不会说"我要停了"。** 模型只是个 token 预测器——给定上下文,猜下一个 token,如此反复。它不"知道"任务做完了没有。`stopReason` 这个字段虽然挂在模型的返回值上,但它的值来自**两个不同的地方**:
**模型 API 真正返回的三种:**
| stopReason | 含义 |
|------------|------|
| `"toolUse"` | 模型输出了工具调用 JSON,API 检测到后返回 |
| `"stop"` | 生成自然终止(遇到了结束标记),没有工具调用 |
| `"length"` | token 数达到 maxTokens 上限,被截断 |
**框架的流式层注入的两种**(模型 API 本身不会返回这两种值):
| stopReason | 含义 | 谁注入的 |
|------------|------|----------|
| `"error"` | 调用过程异常(网络断了、API 报错等) | 流式层的 catch 块:`output.stopReason = "error"` |
| `"aborted"` | 用户主动中止(AbortSignal 触发) | 流式层的 catch 块:`output.stopReason = "aborted"` |
> 代码证据(`packages/ai/src/`):当 `streamSimple` 内部的 API 调用抛出异常时,catch 块执行 `output.stopReason = options?.signal?.aborted ? "aborted" : "error"`。这不是模型说的,是框架替它"兜底"的。
### 一条规则驱动整个循环
Loop 实际上只看一件事——**模型输出里有没有工具调用**。这背后是一条**人类定义的工程约定**:
> 如果模型一次输出中没有工具调用,就认为本轮不需要更多操作,循环可以停了。
这不是模型的"智能决策"。换个说法:**不是模型在说"我完成了",而是我们在说"你没要工具,那就当你完成了"。**
代码里最精炼的判断就是这个(伪代码示意,实际见 `agent-loop.ts:202-216`):
```python
# ============================================================
# 【Python 改写】简化逻辑(实际见 agent-loop.ts:202-216)
# 原文 TS:
# const toolCalls = message.content.filter(c => c.type === "toolCall");
# hasMoreToolCalls = false;
# if (toolCalls.length > 0) {
# const executedToolBatch = await executeToolCalls(...);
# hasMoreToolCalls = !executedToolBatch.terminate;
# }
# ============================================================
# 概念对照:TS 的 array.filter → Python 列表推导;
# TS 的 `arr.length > 0` → Python 的 `len(arr) > 0`;
# 任何一个工具 terminate 则 has_more_tool_calls 为 False
tool_calls = [c for c in message.content if c.type == "toolCall"]
has_more_tool_calls = False
if len(tool_calls) > 0:
executed_tool_batch = await execute_tool_calls(...)
has_more_tool_calls = not executed_tool_batch.terminate # 任何一个工具 terminate 则停止
```
> **注意**:实际驱动循环的不是 `stopReason === "toolUse"`,而是 `toolCalls 数组长度 > 0 && !terminate`。这意味着:即使 `stopReason === "length"`(被截断),只要 content 里有 toolCall 块,循环仍会执行工具;反之,即使 `stopReason === "toolUse"`,如果所有工具结果都设置 `terminate: true`,循环也会停。
内层循环的条件是 `while (hasMoreToolCalls || pendingMessages.length > 0)`:
- 模型返回 toolCall 且工具未 terminate → `hasMoreToolCalls = True` → **继续转**:执行工具,把结果喂回去再调模型
- `stopReason === "stop"` 或 `"length"` 且无 toolCall → `hasMoreToolCalls = False` → **准备停**(看有没有 pendingMessages)
- `stopReason === "error"` 或 `"aborted"` → **硬停止**:立即退出整个循环,不检查 followUp
```
┌──────────────────────────────────┐
│ │
▼ │
┌─────────┐ toolUse ┌──────────┐ │
│ 调模型 │ ─────────→ │ 执行工具 │ │
└─────────┘ └──────────┘ │
│ │ │
│ stop / length │ 结果追加 │
│ ▼ 到消息 │
▼ 重新调模型 ──────┘
┌─────────┐
│ 准备停 │ ← 不是模型决定的,是我们的规则
└─────────┘
error / aborted → 直接跳出整个循环(硬停止)
```
**为什么不让代码更智能地判断"任务完成没"?** 因为这正是 Agent 和 Workflow 的本质区别。Workflow 里你知道流程有几步,可以用代码判断进度。但 Agent 模式下,你不知道模型要读几个文件、改几处代码——你唯一能稳定依赖的信号就是:**输出里有没有工具调用。** 这既是局限,也是优雅——不需要任何"任务完成度"判断逻辑,代码只做最简单的那层判断。
### 循环的所有退出路径
<Diagram file="/assets/260702-ch03-stopreason-flowchart.svg" caption="stopReason 驱动的循环决策流程" id="260702-ch03-stopreason-flowchart" />
**配图说明**:五种 stopReason 分三路处理——toolUse 让循环继续转;stop/length 准备正常停(仍检查 followUp);error/aborted 硬停止(不检查 followUp)。注意 stopReason 的两个来源:三种来自模型 API,两种是框架流式层注入的兜底。
| 退出路径 | 触发条件 | 原因 |
|----------|----------|------|
| **正常退出** | `stop` / `length` + 无 followUp + 无 pendingMessages | 最常见。模型没要工具,也没追加任务 |
| **硬停止** | `error` / `aborted` | 模型调用本身出了问题,继续跑没意义,不检查 followUp |
| **外部钩子停** | `shouldStopAfterTurn()` 返回 true | 上下文快满了、达到最大 Turn 数等 |
| **工具终止** | 一批工具的执行结果全部 `terminate: true` | 所有工具都同意停止(是 `every` 不是 `some`) |
---
## 四、源码详解:基础 Loop 与 coding-agent 的叠加设计
§三 给了你概念全景:消息怎么流动、stopReason 怎么驱动循环、什么时候停。但那都是"**是什么**"。这一节走进代码,回答"**怎么做到的**"。
在看 Pi 的源码之前,先搞清楚一件事:**最简单的 Agent Loop 其实极其简短。**
### 最简 Loop:所有 Agent 的最小公约数
剥掉所有产品特性,一个能用的 Agent Loop 只需要这些:
```python
# ============================================================
# 【Python 改写】最简 Agent Loop(伪代码)
# 原文 TS:
# async function simpleLoop(messages, model, tools) {
# while (true) {
# const response = await callModel(model, messages, tools);
# messages.push(response);
# if (response.stopReason !== "toolUse") return messages;
# for (const toolCall of response.toolCalls) {
# const result = await executeTool(toolCall);
# messages.push(result);
# }
# }
# }
# ============================================================
# 概念对照:TS 的 while(true)+return → Python 同样写法;
# TS 的 for...of → Python 的 for...in;TS 的 !== → Python 的 !=
# TS 的数组 push → Python 的 list append
async def simple_loop(messages, model, tools):
while True:
# ① 调模型
response = await call_model(model, messages, tools)
messages.append(response)
# ② 没有工具调用 → 结束
if response.stop_reason != "toolUse":
return messages
# ③ 有工具调用 → 执行,把结果喂回去
for tool_call in response.tool_calls:
result = await execute_tool(tool_call)
messages.append(result)
```
十几行代码。一个 while 循环,调模型、执行工具、再调模型,直到模型不再要求工具。这就是 §三 讲的那套逻辑的最小实现——**任何 Agent 都需要这个内核**。
### Pi 的 coding-agent 在此基础上叠加了什么
Pi 的 coding-agent 是一个**交互式编程助手**——用户在终端里跟它对话,它可能要读好几个文件、改代码、跑测试。这种产品场景比"最简 Loop"多出了真实的需求:
| 真实需求 | 叠加的设计 | 源码位置 |
|----------|-----------|----------|
| 用户在 Agent 工作期间又输入了新指令 | **steering 消息注入**:紧急消息可以在 Turn 之间插队 | 内层循环开头 |
| 系统在 Agent 完成后想追加后续任务(如"顺便跑个测试") | **外层 followUp 循环**:内层停了但外层可以重启内层 | 外层 while(true) |
| 不同复杂度的任务想用不同档次的模型 | **prepareNextTurn 钩子**:每个 Turn 结束时可切换模型/上下文 | turn_end 之后 |
| 上下文窗口快满了需要触发压缩 | **shouldStopAfterTurn 钩子**:外部判断是否该停 | prepareNextTurn 之后 |
**关键认知**:这些叠加设计都是 coding-agent 的**功能选择**,不是 Agent 的通用法则。如果你做的是一个"一问一答带工具"的简单 Agent,上面这张表全是多余的——你只需要最简 Loop。
但理解 coding-agent 怎么叠加这些设计很有价值——你自己的产品场景很可能也需要类似机制。接下来,我们以 coding-agent 的完整源码为例,逐段走这些设计。跟着那条"帮我读一下 src/main.ts"的消息,走完从入口到结束的整段旅程。
### 4.1 入口:runAgentLoop() 收到了什么
> §三简要展示了流程全景,这里展开看代码细节——同一个过程,更深入的视角。
你按下回车后,调用链是:`Agent.prompt()` → `runPromptMessages()` → `runAgentLoop()`。停在入口:
```python
# ============================================================
# 【Python 改写】agent-loop.ts:95-118 入口函数签名
# 原文 TS:
# async function runAgentLoop(
# prompts: AgentMessage[],
# context: AgentContext,
# config: AgentLoopConfig,
# emit: AgentEventSink,
# signal?: AbortSignal,
# streamFn?: StreamFn,
# ): Promise<AgentMessage[]>
# ============================================================
# 概念对照:TS 的可选参数 `?` → Python 的默认 None;
# TS 的 AbortSignal → Python 的 asyncio.Event 或 cancellation;
# TS 的 `Promise<T>` → Python 的 `Coroutine[..., T]` / awaitable
from typing import Optional, Awaitable
async def run_agent_loop(
prompts: list[AgentMessage], # 你的消息
context: AgentContext, # 当前对话上下文(快照副本)
config: AgentLoopConfig, # 循环配置(模型、钩子、队列回调)
emit: AgentEventSink, # 事件发射器
signal: Optional[AbortSignal] = None, # 中止信号
stream_fn: Optional[StreamFn] = None, # 流式函数(可替换)
) -> list[AgentMessage]: ...
```
六个参数中最重要的三个:
**`prompts`** — 你的消息已经被包装成了标准格式:
```python
# ============================================================
# 【Python 改写】prompts 数据结构
# 原文 TS:
# [{ role: "user",
# content: [{ type: "text", text: "帮我读一下 src/main.ts" }],
# timestamp: 1748000000000 }]
# ============================================================
# 此时 prompts 的数据结构:
[{
"role": "user",
"content": [{"type": "text", "text": "帮我读一下 src/main.ts"}],
"timestamp": 1748000000000,
}]
```
**`context`** — 对话上下文快照。注意是**副本**(`agent.ts:414-420` 的 `createContextSnapshot()` 创建),Loop 运行期间对 context 的修改不会影响 Agent 类的原始状态:
```python
# ============================================================
# 【Python 改写】context 数据结构——Agent 对话状态的完整快照
# 原文 TS:
# {
# systemPrompt: "You are a helpful coding assistant...",
# messages: [ /* 之前的对话历史 */ ],
# tools: [
# { name: "read", description: "...", parameters: Type.Object({...}), execute: ... },
# { name: "bash", description: "...", parameters: Type.Object({...}), execute: ... },
# ]
# }
# ============================================================
{
"system_prompt": "You are a helpful coding assistant...",
"messages": [/* 之前的对话历史 */],
"tools": [
{"name": "read", "description": "...", "parameters": {...}, "execute": ...},
{"name": "bash", "description": "...", "parameters": {...}, "execute": ...},
],
}
```
**`config`** — Loop 的行为配置。这里有一组关键钩子(都是函数,不是数据):
```python
# ============================================================
# 【Python 改写】AgentLoopConfig 的关键字段
# 原文 TS:
# {
# model: Model,
# convertToLlm: Function,
# transformContext?: Function,
# getSteeringMessages?: Function,
# getFollowUpMessages?: Function,
# shouldStopAfterTurn?: Function,
# beforeToolCall?: Function,
# afterToolCall?: Function,
# toolExecution: "parallel",
# }
# ============================================================
# 概念对照:TS 的可选字段 `?:` → Python 的 Optional[T];TS 的函数类型 → Python 的 Callable
from typing import Callable, Optional
{
"model": Model, # 用哪个 LLM
"convert_to_llm": Callable, # list[AgentMessage] → list[Message] 转换
"transform_context": Optional[Callable], # 调 LLM 前的上下文预处理(如压缩)
"get_steering_messages": Optional[Callable], # 获取"紧急插队"消息
"get_follow_up_messages": Optional[Callable], # 获取"追加任务"消息
"should_stop_after_turn": Optional[Callable], # 每轮结束后是否该停
"before_tool_call": Optional[Callable], # 工具执行前钩子
"after_tool_call": Optional[Callable], # 工具执行后钩子
"tool_execution": "parallel", # 工具执行模式
}
```
这些钩子都是**函数**而非数据——Loop 在运行时调用它们来"拉取"最新状态。这让 Loop 和外部消息来源彻底解耦。
入口函数只做了三步准备:
```
Step 1: 创建 new_messages 数组
→ 收集本轮 Trace 产生的所有新消息
Step 2: 把 prompts 追加到 context.messages
→ context.messages = [...context.messages, ...prompts]
Step 3: 发初始事件
→ emit("agent_start") ← Trace 开始
→ emit("turn_start") ← 首轮 Turn 开始(入口就发,后续 Turn 在内层循环里发)
→ 对每条 prompt:emit("message_start") + emit("message_end")
→ 调用 runLoop()
```
数据变化:
```
入口前:
context.messages = [user1, asst1, toolResult1] ← 之前的对话
new_messages = []
入口后:
context.messages = [user1, asst1, toolResult1, user2] ← 你的消息被追加
new_messages = [user2] ← 收集器开始记录
```
---
### 4.2 runLoop() 的骨架:先看内核,再看叠加
现在进入 `runLoop()`——整个系统最核心的代码。别被它的长度吓到,我们先看**内核**,再看**叠加**。
#### 内核:内层循环
如果只保留最简 Loop 的逻辑,`runLoop` 长这样:
```python
# ============================================================
# 【Python 改写】只保留内核的 run_loop(伪代码)
# 原文 TS:
# while (hasMoreToolCalls) {
# // 步骤 B:调 LLM
# // 步骤 C:检查 stopReason → error/aborted 就退出
# // 步骤 D:执行工具
# // 步骤 E:emit turn_end
# }
# // 结束 → emit agent_end
# ============================================================
while has_more_tool_calls:
# 步骤 B:调 LLM
# 步骤 C:检查 stop_reason → error/aborted 就退出
# 步骤 D:执行工具
# 步骤 E:emit turn_end
...
# 结束 → emit agent_end
```
这就是最简 Loop——调模型、执行工具、turn_end,循环往复。内层循环的退出条件 `hasMoreToolCalls` 由 `toolCalls 数组长度 > 0 && !terminate` 驱动(§三讲过)。**这段是所有 Agent 都需要的内核。**
#### 叠加:coding-agent 加了两层外壳
但 coding-agent 作为交互式编程助手,需要在内核外面加两样东西:
**叠加 1:steering 消息注入**(内层循环开头 + 每圈结尾各检查一次)。用户在 Agent 工作时输入了新指令——这些消息不能等当前任务跑完,得在下一圈开头紧急注入。所以内层循环条件多了一个 `|| pendingMessages.length > 0`。
**叠加 2:外层 followUp 循环**(包在整个内层循环外面)。Agent 自然停了之后,系统可能还想追加任务(比如"顺便跑个测试")。外层循环让这些追加任务在**同一个 Trace 内**继续跑,不需要重新启动一个新的 Loop。
把内核和两层叠加拼起来,才是完整的 `runLoop` 骨架:
```python
# ============================================================
# 【Python 改写】runLoop 的完整骨架(内核 + 两层叠加)
# 原文 TS:
# async function runLoop(currentContext, newMessages, config, signal, emit, streamFn) {
# let pendingMessages = (await config.getSteeringMessages?.()) || [];
# while (true) {
# let hasMoreToolCalls = true;
# let firstTurn = true;
# while (hasMoreToolCalls || pendingMessages.length > 0) {
# if (!firstTurn) emit({ type: "turn_start" });
# firstTurn = false;
# // 步骤 A~F
# }
# const followUpMessages = (await config.getFollowUpMessages?.()) || [];
# if (followUpMessages.length > 0) {
# pendingMessages = followUpMessages;
# continue;
# }
# break;
# }
# }
# ============================================================
async def run_loop(current_context, new_messages, config, signal, emit, stream_fn):
# ① 首次 steering 检查(在进入内层循环之前!)
pending_messages = (await config.get_steering_messages()) if config.get_steering_messages else []
# ========== 叠加2:外层循环(followUp 续命)==========
while True:
has_more_tool_calls = True
first_turn = True # 首轮跳过 turn_start(入口已发)
# ========== 内核 + 叠加1:内层循环 ==========
while has_more_tool_calls or len(pending_messages) > 0:
# ↑ 叠加1:steering 消息也驱动循环
if not first_turn:
await emit({"type": "turn_start"})
first_turn = False
# 步骤 A:注入 pending_messages(steering 消息)← 叠加1
# 步骤 B:调 LLM → stream_assistant_response() ← 内核
# 步骤 C:检查 stop_reason ← 内核
# 步骤 D:执行工具 ← 内核
# 步骤 E:emit turn_end ← 内核
# 步骤 F:prepare_next_turn → should_stop_after_turn ← 叠加(钩子)
# → 再次检查 steering ← 叠加1
...
# ========== 内层循环结束 ==========
# 叠加2:检查 followUp 队列
follow_up_messages = (await config.get_follow_up_messages()) if config.get_follow_up_messages else []
if len(follow_up_messages) > 0:
pending_messages = follow_up_messages
continue # 回到外层循环顶部,内层循环重开
break # 两个队列都空,真正退出
```
现在我们逐步骤展开。每个步骤会标注"内核"还是"叠加",方便你区分。
---
### 4.3 【叠加1 · 步骤A】steering 消息注入
> **什么是 steering?** 这是 coding-agent 的一个交互功能。想象你让 Agent 帮你修一个 bug,Agent 正在读文件、分析代码。这时候你突然想到一个补充:"也检查一下测试文件"——你希望这条指令能**插队**,而不是等 Agent 把当前任务做完再说。
steering 就是这个"插队"机制。用户在 Agent 工作期间输入的新指令,会被放进 steering 队列。每圈内层循环开头,Loop 先检查这个队列,把紧急消息注入到当前对话中:
```python
# ============================================================
# 【Python 改写】steering 消息注入
# 原文 TS:
# if (pendingMessages.length > 0) {
# for (const message of pendingMessages) {
# await emit({ type: "message_start", message });
# await emit({ type: "message_end", message });
# currentContext.messages.push(message);
# newMessages.push(message);
# }
# pendingMessages = [];
# }
# ============================================================
# 概念对照:TS 的 `array.length > 0` → Python 的 `len(list) > 0`;
# TS 的 `for...of` → Python 的 `for...in`;TS 的 `array.push` → Python 的 `list.append`
if len(pending_messages) > 0:
for message in pending_messages:
await emit({"type": "message_start", "message": message})
await emit({"type": "message_end", "message": message})
current_context.messages.append(message)
new_messages.append(message)
pending_messages = [] # 消费完毕,清空
```
这段代码就是把紧急消息逐条注入到上下文和消息收集器中。
pendingMessages 的第一个来源是 `runLoop` 一进来就执行的首次 steering 检查(`agent-loop.ts:167`)。为什么要在进入循环**之前**就检查?因为用户在等待 LLM 首次响应时可能又输入了内容——这时候消息已经从外部排队了,但循环还没开始,如果不提前取出来,这批消息就漏掉了。
---
### 4.4 【内核 · 步骤B】streamAssistantResponse() — 调 LLM
这是整个 Loop 最重的一步——把消息发给模型、拿回流式响应。分为四个阶段。
#### 阶段 A:上下文预处理(可选)
```python
# ============================================================
# 【Python 改写】上下文预处理
# 原文 TS:
# let messages = context.messages;
# if (config.transformContext) {
# messages = await config.transformContext(messages, signal);
# }
# ============================================================
messages = context.messages
if config.transform_context:
messages = await config.transform_context(messages, signal)
```
如果配置了 `transformContext`(如压缩算法),在此预处理消息。不配置就跳过。
#### 阶段 B:AgentMessage → Message 转换(两层消息的边界)
```python
# ============================================================
# 【Python 改写】AgentMessage → Message 转换
# 原文 TS: const llmMessages = await config.convertToLlm(messages);
# ============================================================
llm_messages = await config.convert_to_llm(messages)
```
这一行站在 Agent 内核和 LLM 的**边界**上。要理解它为什么存在,得先知道"两层消息"的设计。
Agent 内部维护对话历史时,需要记录的不只是"用户说了什么、AI 回了什么"——它还需要记录**自己的内部状态**。比如 coding-agent 会记录:上下文被压缩过(`CompactionSummaryMessage`)、Bash 命令的执行详情(`BashExecutionMessage`)、分支切换的记录(`BranchSummaryMessage`)。这些是 Agent 自己用的"内部语言",**LLM 根本不认识这些消息类型**——它只认三种标准消息:`UserMessage`、`AssistantMessage`、`ToolResultMessage`。
`convertToLlm` 就是站在这个边界上的**翻译官**:把 Agent 的内部语言翻译成 LLM 能理解的协议。默认实现就是一个 `.filter()`——只保留三种标准消息:
```python
# ============================================================
# 【Python 改写】default_convert_to_llm
# 原文 TS:
# function defaultConvertToLlm(messages: AgentMessage[]): Message[] {
# return messages.filter(
# (message) => message.role === "user"
# || message.role === "assistant"
# || message.role === "toolResult",
# );
# }
# ============================================================
# 概念对照:TS 的 array.filter(callback) → Python 的 [m for m in messages if pred(m)]
from typing import Callable
def default_convert_to_llm(messages: list[AgentMessage]) -> list[Message]:
"""只保留 LLM 认识的三种标准消息,过滤掉 Agent 内部状态消息。"""
return [
m for m in messages
if m.role in ("user", "assistant", "toolResult")
]
```
数据变换:
```
转换前(AgentMessage[]):
[
{ role: "user", content: "帮我读一下 src/main.ts", ... }, ← 保留
{ role: "assistant", content: [...], ... }, ← 保留
{ role: "compactionSummary", summary: "之前的对话摘要..." }, ← 过滤掉
{ role: "toolResult", content: [...], ... }, ← 保留
]
转换后(Message[]):
[
{ role: "user", content: "帮我读一下 src/main.ts", ... },
{ role: "assistant", content: [...], ... },
{ role: "toolResult", content: [...], ... },
]
```
> 两层消息的完整设计,详见《第6章:消息系统》。
#### 阶段 C:构建 Context 并调用模型
```python
# ============================================================
# 【Python 改写】构建 llm_context 并调用模型
# 原文 TS:
# const llmContext: Context = {
# systemPrompt: context.systemPrompt,
# messages: llmMessages,
# tools: context.tools,
# };
# const streamFunction = streamFn || streamSimple;
# const resolvedApiKey =
# (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined)
# || config.apiKey;
# const response = await streamFunction(config.model, llmContext, {
# ...config, apiKey: resolvedApiKey, signal,
# });
# ============================================================
# 概念对照:TS 的对象字面量 → Python 的 dict 或 dataclass;
# TS 的 `a || b` 短路求值 → Python 的 `a if a else b`;
# TS 的 `...config` 展开 → Python 的 {**config, ...}
llm_context: Context = {
"system_prompt": context.system_prompt,
"messages": llm_messages,
"tools": context.tools,
}
stream_function = stream_fn or stream_simple
resolved_api_key = (
(await config.get_api_key(config.model.provider)) if config.get_api_key else None
) or config.api_key
response = await stream_function(config.model, llm_context, {
**config, "api_key": resolved_api_key, "signal": signal,
})
```
**构建 Context 是这一步的主线。** 注意 `llmContext` 是一个**全新对象**,每圈内层循环都重建一次。它由三部分组成:
- **`systemPrompt`** —— 直接复用 Agent 上下文里的系统提示词,告诉模型"你是谁、该遵守什么规则"
- **`messages`** —— 就是上一步 `convertToLlm` 过滤后的 `llmMessages`,只含 LLM 认识的三种标准消息
- **`tools`** —— 工具列表(带 schema 定义),让模型知道"这次有哪些工具可以调"
注意一个细节:`llmContext.tools = context.tools` 是**引用赋值**——每圈虽然包了个新的 wrapper 对象,但 `tools` 数组本身是同一份引用,内容字节级稳定。`systemPrompt` 同理。只有 `messages` 真的在长(每圈追加新的 ToolResultMessage)。
那为什么还要每圈重建 `llmContext` 这个 wrapper?因为有的 Turn 确实会改这三者里的某一个:`prepareNextTurn` 钩子(§4.7)可能换过模型或改过 systemPrompt,扩展系统(§5)可能动态注册新工具。重建 wrapper 的成本可以忽略(一个 JS 对象),但能保证不会因为共享引用导致难以追踪的状态污染。
**这会不会破坏 prompt cache?** 不会。Anthropic 的 prompt cache 是**内容寻址**的——它看的是发过去的字节,不是请求的 identity。每次发的是新对象还是旧对象无所谓,只要 `system + tools` 的字节不变,cache 就命中。Pi 在 [anthropic-messages.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/anthropic-messages.ts) 里显式在**三个位置**打 `cache_control: { type: "ephemeral" }` 标记:
| 位置 | 源码行 | 作用 |
|------|--------|------|
| System prompt 末尾 | [L922/929/938](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/anthropic-messages.ts#L922) | 系统提示词整体作为可缓存前缀 |
| **最后一个 tool** | [L1208](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/anthropic-messages.ts#L1208) | 整个 tools 列表作为可缓存前缀 |
| **最后一条 user message** | [L1157-1178](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/anthropic-messages.ts#L1157) | **rolling cache**——每 Turn 把 cache 推进到最新消息 |
第三条尤其精妙:cache breakpoint 不是固定在第一条消息上,而是**跟着最新 user message 走**。这样旧前缀继续命中、新追加的内容被写入,整个对话历史都享受 cache 收益。命中链路大致是:
```
Turn 1: 写入 [system + tools] → 写入 [messages §1]
Turn 2: 命中 [system + tools] → 命中 [messages §1] → 写入 [messages §2]
Turn 3: 命中 [system + tools] → 命中 [messages §1+§2] → 写入 [messages §3]
```
还有个容易误解的点:**tools 不是被塞到 messages 末尾**。Anthropic API 协议里 `tools` 是独立的顶层字段(位置在 messages 之前),这个协议设计本身就考虑了 cache——稳定的 tools 在前、变动的 messages 在后,prefix 越长越省。
OpenAI 体系走的是另一条路([openai-completions.ts:554](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/openai-completions.ts#L554)):`prompt_cache_key: sessionId`,OpenAI 后端按 session 自动匹配前缀。DeepSeek、Qwen 等通过 `cacheControlFormat: "anthropic"` 兼容字段,也能复用 Anthropic 风格的 cache_control 标记([L593](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/openai-completions.ts#L593) 的 `applyAnthropicCacheControl`)。
#### 阶段 D:流式处理响应 —— 原地替换的妙用
`streamFunction` 返回的是 `AssistantMessageEventStream`——一个异步迭代器。这步有一个很精巧的设计:
```python
# ============================================================
# 【Python 改写】流式响应处理(原地替换)
# 原文 TS:
# for await (const event of response) {
# switch (event.type) {
# case "start":
# partialMessage = event.partial;
# context.messages.push(partialMessage);
# emit({ type: "message_start", ... });
# break;
# case "text_delta":
# case "toolcall_delta":
# case "thinking_delta":
# partialMessage = event.partial;
# context.messages[last] = partialMessage; // ★ 原地替换
# emit({ type: "message_update", ... });
# break;
# case "done":
# case "error":
# finalMessage = await response.result();
# context.messages[last] = finalMessage;
# emit({ type: "message_end", ... });
# return finalMessage;
# }
# }
# ============================================================
# 概念对照:TS 的 for await...of → Python 的 async for...in;
# TS 的 switch/case → Python 的 if/elif(或 match/case,Python 3.10+);
# TS 的 `array[last] = x` → Python 的 `array[-1] = x`
async for event in response:
if event.type == "start":
# 拿到一个"空壳"消息,直接 append 到 context
partial_message = event.partial
context.messages.append(partial_message)
await emit({"type": "message_start", ...})
elif event.type in ("text_delta", "toolcall_delta", "thinking_delta"):
partial_message = event.partial # 更新后的部分消息
context.messages[-1] = partial_message # ★ 原地替换!
await emit({"type": "message_update", ...}) # UI 收到增量更新
elif event.type in ("done", "error"):
final_message = await response.result()
context.messages[-1] = final_message # ★ 用最终完整消息替换
await emit({"type": "message_end", ...})
return final_message
```
为什么要先 push 空壳再原地替换?注意"原地替换"的意思——不是往 `context.messages` 数组里 push 新条目,而是**用新内容覆盖最后一条**(`context.messages[-1] = partialMessage`)。这样 context 的消息数量不变,但最后一条消息的内容在"长大"。
为了**UI 能实时展示**。如果等全部响应完成才 push 到 context,用户在 LLM 思考的几秒里盯着空白屏幕。通过"先放空壳、逐 token 替换",UI 通过 `message_update` 事件拿到最新部分消息,能做到逐字渲染。
<Diagram file="/assets/260702-ch03-streaming-replace.svg" caption="流式响应原地替换的时间线" id="260702-ch03-streaming-replace" />
**配图说明**:四个时间点的 context.messages[last] 演变——start 时空壳、text_delta 时文字在长、toolcall_delta 时工具调用出现、done 时最终完整消息替换。每一步同步展示 UI 显示状态。
数据在流式响应期间,`context.messages[last]` 的演变:
```
start → { role: "assistant", content: [] } ← 空壳 push
text_delta → { content: [{ type:"text", text:"好的..." }] } ← 文字在长
toolcall → { content: [{ text:"好的..." }, ← 工具调用出现
{ type:"toolCall", name:"read", arguments:{file_path:"src/main.ts"} }] }
done → { content: [...], stopReason:"toolUse", usage:{...} } ← 最终完整消息替换
```
---
### 4.5 【内核 · 步骤C】检查 stopReason
§三详细讲了 `stopReason` 的来源和含义。这里看代码怎么处理它。拿到 `AssistantMessage` 后,立即做一次硬停止判断:
```python
# ============================================================
# 【Python 改写】agent-loop.ts:196-200 硬停止判断
# 原文 TS:
# if (message.stopReason === "error" || message.stopReason === "aborted") {
# await emit({ type: "turn_end", message, toolResults: [] });
# await emit({ type: "agent_end", messages: newMessages });
# return;
# }
# ============================================================
if message.stop_reason in ("error", "aborted"):
await emit({"type": "turn_end", "message": message, "tool_results": []})
await emit({"type": "agent_end", "messages": new_messages})
return # ← 直接退出整个 run_loop,不检查 followUp
```
`error` 和 `aborted` 是"硬停止"——立即发 turn_end + agent_end,直接 return。连工具都不执行,连 followUp 都不检查。这是一种**快速失败**(fail fast)策略:既然模型调用本身就失败了(网络异常或用户中止),继续跑没有任何意义。
而 `stop`、`toolUse`、`length` 这三种,代码继续往下走——进入工具执行逻辑。区别在于:`stop` 和 `length` 时,`toolCalls` 数组为空,所以工具执行步骤什么也不干。
---
### 4.6 【内核 · 步骤D】executeToolCalls() — 执行工具
模型返回的 `AssistantMessage.content` 里,可能有多个 `type === "toolCall"` 的块(模型一口气要求了多个操作)。先过滤出来:
```python
# ============================================================
# 【Python 改写】过滤出工具调用
# 原文 TS: const toolCalls = message.content.filter((c) => c.type === "toolCall");
# ============================================================
tool_calls = [c for c in message.content if c.type == "toolCall"]
```
然后决定这批工具**并行还是串行**执行:
```python
# ============================================================
# 【Python 改写】并行/串行选择
# 原文 TS:
# if (config.toolExecution === "sequential" || hasSequentialToolCall) {
# return executeToolCallsSequential(...);
# }
# return executeToolCallsParallel(...);
# ============================================================
if config.tool_execution == "sequential" or has_sequential_tool_call:
return await execute_tool_calls_sequential(...)
return await execute_tool_calls_parallel(...)
```
**"一票否决"策略**:只要这批工具中有**任何一个**声明了 `executionMode: "sequential"`,整批都串行。为什么这么保守?因为判断"哪些工具会冲突"很难——edit 和 edit 操作不同文件就安全吗?万一它们编辑的文件有依赖关系呢?所以 Pi 选择了"宁可多等,不可出错"。而 edit 工具内部还有第二道防线(`withFileMutationQueue`,对同一文件的编辑串行化),确保即使外层判断为并行,也不会互相覆盖。
两种执行模式的内部结构:
```
串行模式:
ToolCall A: 准备 → 验证 → beforeHook → 执行 → afterHook → emit end
ToolCall B: 准备 → 验证 → beforeHook → 执行 → afterHook → emit end
(一个完全结束,才开始下一个)
并行模式(三阶段设计):
阶段1 - 准备(顺序): A 准备 → B 准备 → C 准备
↑ prepareToolCall 含验证和 beforeHook,必须顺序执行
阶段2 - 执行(并行): A、B、C 同时执行(Promise.all)
↑ 只有 tool.execute 并行,省时间
阶段3 - 事件(有序): end 按完成顺序发;result 按调用顺序发
↑ result 消息保持和 ToolCall 一致的顺序,LLM 收到的上下文才是正确的
```
注意并行模式的精妙之处:**准备阶段始终顺序**(因为验证和权限检查不能并行——万一 B 被拦截了,C 就不应该执行),**只有实际执行并行**。
每个工具的结果被包装成 `ToolResultMessage`,追加到 `context` 和 `newMessages`:
```
工具执行后:
context.messages = [..., user2, assistantMessage, {
role: "toolResult", toolCallId: "toolu_01", toolName: "read",
content: [{ text: "文件内容..." }], isError: false
}]
```
**terminate 机制**:工具可以在返回结果中设置 `terminate: true`,表示"我觉得不该继续了"。但 Loop 不会因为某一个工具喊停就停——它用的是 `every` 而非 `some`:**必须这批工具的全部结果都设置了 terminate 才真正退出**。这是保守策略:只要有一个工具还在正常工作,Loop 就不中断。
> 工具执行的完整五步管道(prepareArguments → Schema 验证 → beforeToolCall → execute → afterToolCall)详见《第5章:工具系统》。
---
### 4.7 【内核+叠加 · 步骤E~F】turn_end + 钩子 + 再次检查 steering
Turn 的核心工作做完了(调模型 + 执行工具),接下来是收尾。收尾分四步,其中前两步是内核,后两步是 coding-agent 叠加的扩展点:
```python
# ============================================================
# 【Python 改写】turn_end + 钩子 + 再次检查 steering
# 原文 TS:
# await emit({ type: "turn_end", message, toolResults });
# const nextTurnSnapshot = await config.prepareNextTurn?.({...});
# if (nextTurnSnapshot) {
# currentContext = nextTurnSnapshot.context ?? currentContext;
# config.model = nextTurnSnapshot.model ?? config.model;
# }
# if (await config.shouldStopAfterTurn?.({...})) {
# await emit({ type: "agent_end", messages: newMessages });
# return;
# }
# pendingMessages = (await config.getSteeringMessages?.()) || [];
# ============================================================
# ① emit turn_end —— 通知外部"这一轮结束了"(内核)
await emit({"type": "turn_end", "message": message, "tool_results": tool_results})
# ② prepare_next_turn —— 给外部一个机会"改装"下一轮(叠加)
# 返回值可包含 context / model / thinkingLevel 三者之一的覆盖
if config.prepare_next_turn:
next_turn_snapshot = await config.prepare_next_turn({...})
if next_turn_snapshot:
current_context = next_turn_snapshot.context or current_context
config.model = next_turn_snapshot.model or config.model
# thinking_level 也在此处覆盖(详见 agent-loop.ts 中 prepareNextTurn 处理逻辑)
# ③ should_stop_after_turn —— 外部判断是否该停了(叠加)
if config.should_stop_after_turn and await config.should_stop_after_turn({...}):
await emit({"type": "agent_end", "messages": new_messages})
return
# ④ 再次检查 steering —— 有没有新的紧急消息?(叠加1)
pending_messages = (await config.get_steering_messages()) if config.get_steering_messages else []
```
**`prepareNextTurn`** —— 这是个容易被忽略但很强大的扩展点。它在每个 turn_end 之后、下一轮开始前被调用,允许外部**动态切换下一轮的配置**。具体例子:
```
场景:按任务复杂度切换模型
Turn 1: 用户问了一个简单问题 → 模型用 Haiku(快、便宜)
turn_end → prepareNextTurn 检查到问题很简单
→ 返回 { model: haiku } → 下一轮继续用 Haiku
场景:中途发现任务变复杂了
Turn 1: 用户让"重构这个模块" → Haiku 开始读文件
turn_end → prepareNextTurn 发现要改的文件很多
→ 返回 { model: opus } → 下一轮自动切到 Opus(强、贵)
```
除了换模型,它还能换 `context`(比如注入新的上下文信息)和 `thinkingLevel`(思考强度)。返回 `undefined` 表示"什么都不换,按原配置继续"。
**`shouldStopAfterTurn`** —— 外部注入的停止判断。coding-agent 层会用它来检查上下文窗口是否快满了(快满了就停下来触发压缩),或者是否达到了最大 Turn 数限制。这是产品层的"安全阀",最简 Loop 不需要它。
**④再次检查 steering** —— 一圈内层循环结束,再看看 steering 队列有没有新积攒的紧急消息。如果有,下一圈继续跑。
---
### 4.8 回到循环顶部
工具执行完且收尾结束,代码回到内层 while 循环的条件判断。§三已经详细讲了 `hasMoreToolCalls` 由 `toolCalls 数组长度 > 0 && !terminate` 驱动——这里只看代码:
```python
# ============================================================
# 【Python 改写】内层循环条件
# 原文 TS: while (hasMoreToolCalls || pendingMessages.length > 0)
# ============================================================
while has_more_tool_calls or len(pending_messages) > 0:
...
```
两个条件任一为 true 就继续。`hasMoreToolCalls` 由模型输出里有没有 toolCall 块(且未全部 terminate)决定(内核),`pendingMessages` 由 steering 队列决定(叠加1)。两个都为 false 时,内层循环退出。
---
### 4.9 【叠加2 · 步骤G】外层循环:followUp 的续命机制
内层循环退出了——没有工具要执行,也没有紧急消息。但 coding-agent 的设计是:此时检查一下 `getFollowUpMessages()`,看看系统有没有追加任务:
```python
# ============================================================
# 【Python 改写】外层 followUp 检查
# 原文 TS:
# const followUpMessages = (await config.getFollowUpMessages?.()) || [];
# if (followUpMessages.length > 0) {
# pendingMessages = followUpMessages;
# continue;
# }
# break;
# ============================================================
follow_up_messages = (await config.get_follow_up_messages()) if config.get_follow_up_messages else []
if len(follow_up_messages) > 0:
pending_messages = follow_up_messages # 塞进 pending,触发新 Turn
continue # 回到外层循环顶部
break # 两个队列都空了,真正退出
```
如果有 followUp 消息,它们被塞进 `pendingMessages`,`continue` 回到外层循环顶部,内层循环检测到 `pendingMessages` 不为空,**在同一个 Trace 内**继续跑。这比重新启动一个新的 `runAgentLoop()` 好在哪?——连续性:同一个 `newMessages` 数组、同一个事件序列,不需要额外合并。
§四开头已经说过:如果你做的是简单 Agent,外层循环是多余的——内层循环退出后直接 `break` + `emit agent_end` 就行了。
---
### 4.10 steering vs followUp:一张表看清两种干预
本章出现了两种"外部消息注入"机制。虽然 §四开头已经分别介绍过,但放在一起对比更能看清它们的差异:
| 维度 | steering(叠加1) | followUp(叠加2) |
|------|----------|----------|
| **检查时机** | runLoop 开始前 + 内层循环**每圈**结尾 | 内层循环**全部结束**后 |
| **语义** | "紧急插队"——在工具执行间隙中插入 | "排队等叫号"——等当前任务全部完成 |
| **典型场景** | 用户在 Agent 工作时输入了新指令 | 系统在 Agent 完成后追加"顺便跑个测试" |
生活类比:steering 是你正在开会,有人敲门递了张纸条——"紧急,先看这个"。followUp 是开完会翻了翻信箱——"不急,但需要处理"。
<Diagram file="/assets/260702-ch03-steering-vs-followup.svg" caption="steering vs followUp 对比" id="260702-ch03-steering-vs-followup" />
**配图说明**:左红右绿对照——steering 在每圈内层循环开头+结尾检查、紧急插队;followUp 在内层循环全部结束后检查、续命重启。底部列出各自时机/来源/影响/典型场景。
---
## 五、总结:Loop 的四条核心设计
回顾从按下回车到 Agent 完成的整段旅程:
### 1. ReAct 循环模式
Loop 的本质是 Reason(模型思考)→ Act(执行工具)→ Observe(观察结果)→ Reason(再次思考)的循环。模型的输出内容决定"该调什么工具"——这是 Agent 区别于 Workflow 的核心。但"什么时候停"不是模型的决策,而是我们人类定义的规则:**模型不再输出工具调用时,就认为本轮结束。**
### 2. stopReason 驱动机制
整个循环由一个字段驱动:`stopReason`。但实际驱动循环的不是 stopReason 本身,而是模型输出里有没有 toolCall 块且未全部 terminate——`"有 toolCall"` = 继续转;没有 toolCall 或全部 terminate = 准备停(或立即停)。**"是否继续"不靠代码的复杂判断,只靠一条简单规则:模型的输出中有没有工具调用。** 这是 Agent 架构的核心设计原则——把决策外包给模型输出模式,代码只做最简单的信号判断。
### 3. 内核 + 叠加的架构思路
Agent Loop 的内核极其简短——十几行代码就能实现一个能用的循环。Pi 的 coding-agent 在内核上叠加了 steering(紧急插队)、followUp(任务追加)、prepareNextTurn(动态切模型)、shouldStopAfterTurn(安全阀)等设计。**内核是所有 Agent 的通用法则,叠加是产品功能的按需选择。** 做自己的 Agent 时,先搭内核,再按场景加叠加。
<Diagram file="/assets/260702-ch03-kernel-onion.svg" caption="Agent Loop 内核与叠加设计" id="260702-ch03-kernel-onion" />
**配图说明**:从里到外的四层洋葱——最内核是最简 Loop(~10 行通用法则);外层依次叠加 steering(紧急插队)、followUp(任务追加)、钩子(切模型/安全阀)。剥掉任何一层,里层仍能跑——这是判断"内核是否被污染"的试金石。
---
## 六、下一站
Loop 跑起来了——我们知道它怎么调用模型、怎么执行工具。但 Loop 调用的"模型"到底是什么?Pi 是怎么用同一套代码调用 OpenAI、Claude、Gemini 等 30+ 家不同供应商的?`streamSimple()` 内部做了什么?
下一章,我们拆开 Pi 的模型调用层:《第4章:模型调用 —— 一行代码驾驭多个模型》。
---
> **本章关键源码索引**(v0.80.2 实际行号):
> - `agent-loop.ts:95-118` — `runAgentLoop()` 入口
> - `agent-loop.ts:155-269` — `runLoop()` 双层循环完整实现
> - `agent-loop.ts:167` — steering 首次检查(进入内层循环之前)
> - `agent-loop.ts:175-179` — turn_start 的首轮跳过机制
> - `agent-loop.ts:196-200` — stopReason 硬停止判断
> - `agent-loop.ts:275-368` — `streamAssistantResponse()` 流式响应
> - `agent-loop.ts:313-357` — 流式处理中的原地替换
> - `agent-loop.ts:373-516` — `executeToolCalls()` 并行/串行调度
> - `agent-loop.ts:218-253` — turn_end + prepareNextTurn + shouldStopAfterTurn
> - `agent-loop.ts:253` — steering 每圈二次检查
> - `agent.ts:118-152` — `PendingMessageQueue` 和 drain 模式
> - `agent.ts:451-474` — `runWithLifecycle()` 生命周期管理