第 5 章:AgentLoop——一轮 turn 怎样反复采样
前几章分别讲了事件、provider 和工具。这一章把它们放在同一个控制循环里。
读完以后,你应该能从 src/runtime/agent_loop.rs 解释:用户输入怎样变成第一次模型请求,工具结果怎样进入下一次请求,一轮 turn 在什么情况下完成或失败。
先找真正的入口
当前 AgentLoop 的主要入口分布在两个文件:
- src/runtime/agent_loop_setup.rs:构造新 loop、从日志恢复 loop;
- src/runtime/agent_loop.rs:append、开始 turn、继续 turn、取消和限制。
先看方法之间的关系:
run_turn(input)
└─ run_turn_with_cancel(input, token)
└─ run_turn_with_reason(...)
├─ begin_turn(...)
└─ continue_turn(...)
└─ continue_turn_with_reason(...)
begin_turn 负责把用户输入和 turn.started 变成事实。continue_turn_with_reason 才是反复请求 provider、处理工具调用和判断终态的循环。
主循环的每一轮
把实际代码压缩成伪代码:
while turn 还没有终态:
检查 cancel、step、turn time、tool time
从 SessionState 构造 ContextSnapshot
转成 ModelRequest
调 provider,得到 ModelCompletion
如果 continuation 改变:
append provider.continuation.updated
如果响应是 Text:
append model.response.recorded
append turn.completed
返回最终文本
如果响应是 ToolCall 或 ToolCalls:
检查是否为空、是否重复、是否超过 batch 上限
append model.response.recorded
对每个 call:
append tool.requested
通过 policy
Allow → append tool.started → 执行 → append tool.completed/failed
Ask → append tool.approval.requested,暂停
Deny → append tool.policy_denied,结束或继续
回到下一轮采样
这段循环没有直接修改 history。所有改变都经过 append,再由 reducer 更新 state。
ModelResponse 为什么也会记录工具调用
一个模型响应可以是文本,也可以是工具调用。当前实现把工具调用转换成一个可观察的 model.response.recorded,内容类似:
tool call: read
tool calls: read, bash
它不是工具结果,也不替代 tool.requested。它表示“模型这次说了什么”;tool.requested 表示“runtime 接受了哪个调用并开始处理状态机”。
工具调用执行后,ToolCompleted 才会把 ToolResult 加入 history,供下一次 ModelRequest 使用。
ContextSnapshot 是模型看到的窗口
打开 src/runtime/context.rs。ContextSnapshot 是拥有所有权的、不可变的模型输入:
SessionState
├─ history
├─ provider_continuation
└─ tools
│
▼
ContextSnapshot
├─ 有限 history
├─ 有限的每项文本
├─ tools
└─ continuation
│
▼
ModelRequest
它有两个重要限制:
- 单条 history item 默认最多 16 KiB;
- provider 看到的 history 总量默认最多 512 KiB。
截断只发生在 ContextSnapshot,不会删除 durable history。日志保留完整事实,模型请求只携带当前预算允许的部分。
如果有 provider continuation,history_start 会根据 history_cursor 选择需要发送的历史窗口。续传 provider 和完整回放 provider 都通过同一个 ModelRequest 接口工作。
append 是主循环的安全边界
AgentLoop::append 的顺序必须牢记:
1. expected_seq = state.last_seq + 1
2. 确认 store 没被其他进程追加
3. 检查事件序列化后的大小
4. 在 next_state 副本上调用 reduce
5. store.append(event)
6. 检查 store 返回 seq
7. 提交 self.state = next_state
如果先修改 self.state,再写日志,进程在中间崩溃,内存曾经看到过一个事实,日志却没有它。恢复时就会出现两个世界。
如果 provider 响应产生空工具批次、重复 call_id、超过 max_batch_tool_calls 或超过 step 上限,runtime 会先记录 turn.failed,再返回错误。错误路径也必须是事件路径。
取消、超时和审批
取消和超时有不同的事件:
用户取消
└─ turn.cancel_requested
└─ turn.cancelled
时间预算耗尽
└─ turn.timed_out
工具的取消还要等 executor 收尾。审批则是另一种暂停:
tool.requested
→ tool.approval.requested
→ turn 保持 active
→ 用户批准
→ tool.approval.responded
→ tool.started
→ 工具完成
→ 回到采样
审批不是 provider 错误。它是一个已经持久化的控制状态,所以 UI 或协议客户端重启后仍然可以看到“正在等待审批”。
建议的阅读实验
运行:
cargo test --test integration_agent_loop
cargo test agent_loop_passes_system_instructions_through_snapshot
cargo test --test agent_loop_limits
在 integration_agent_loop.rs 中找一个脚本为 ToolCall、Text 的测试,画出两次 ModelRequest:
request 1: user history + tool specs
request 2: user history + tool result + tool specs
再找一个 max_steps 或空批测试,看它在事件日志里记录哪个终态。
思考题
- 为什么工具结果必须进入下一次 ModelRequest,而不能只存在 ToolCompleted 事件里?
- ContextSnapshot 截断 history 后,为什么 durable log 仍然要保留完整文本?
- 如果模型一次返回 100 个工具调用,最早应该在哪一层限制?
- append 的副本 reduce 能防止哪些问题,不能防止哪些外部副作用?
- 为什么 turn.cancel_requested 和 turn.cancelled 要分成两个事实?
- 审批暂停时,Session actor 为什么可以处理新输入;工具执行期间又为什么会延迟处理?
下一章:进程、取消和原子编辑。