手册/第 04 章
04
一次提问:13 条消息走完一个 turn
架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 下面这张图从用户敲下回车开始,到文本渲染上屏为止。
阅读顺序:自上而下三条时间线——① 用户输入到模型请求,② 工具调用与结果回填, ③ 再次请求到渲染上屏。虚线段表示落盘,斜跨的粗箭头是一次模型调用。 这张图画布较窄(952px),1× 下最小字号约 6px、2× 即可到 12px,通常不必开到 3×。
三个关键时刻
Ⅰ模型调用是唯一的出口
整个仓库里,模型请求只经过
streamFn(model, context) 这一个函数。
换 provider、换模型、走代理、加 trace,都只需要在这一层做。Ⅱ工具执行是唯一的信任边界
prepare → validate → beforeToolCall → execute → afterToolCall。
参数校验、权限策略、审计、扩展挂钩,全都在这一条链上。Ⅲ落盘发生在渲染之前
assistant 消息先追加进 JSONL,再交给 UI。
所以进程被 kill 也不会丢掉已完成的 turn——这正是可恢复性的前提。
为什么模型被调用两次?
因为工具结果也是「消息」。第一次 streamFn 返回的是「我要调用 bash」;
工具跑完后,结果作为一条 toolResult 追加进活动分支,
然后必须带着新历史再请求一次模型,它才知道命令输出了什么。
这个「再请求」就是 turn 的循环条件:只要还有工具调用,就再起一个 turn;否则 run 结束。
"The loop just loops until the agent says it's done."
这个循环就一直循环,直到 agent 说它做完了。
— 2025-11-30 博客 · 没有 max steps 这个旋钮
docs/how-pi-works.md · Agent loop agent-loop.ts:842 · tool.execute stream-fn.ts:15