源码篇第4章 双层循环——pi-agent-core ​

本章导读: 源码路线第 ③ 站(核心层)。从
pi-ai切到pi-agent-core包,读agent.ts和agent-loop.ts。这一站要看的是循环的真面目:模型输出和工具结果怎么一推一拉,把状态一轮轮往前送,以及那个容易被误读的“内外两层循环”到底是怎么回事。
小A读完流适配层,信心满满地跟老Z说:“我懂了。模型流进来,循环就在那儿转:外层管模型轮次,内层管并行跑工具,对吧?”
老Z没直接回答:“你这句话里有几个‘想当然’?”
小A愣住了。
“流适配层只会产出事件;把事件变成上下文中的 assistant message、把 tool call 变成 tool result、再决定是否继续请求的,是 pi-agent-core 的 loop。”老Z说,“你猜的‘外层管模型轮次、内层并行跑工具’就是这一站要拆的误读。答案是否定的,必须按状态变量和分支看。”
本章依据上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32)、@earendil-works/pi-agent-core 1.0.0。覆盖 runAgentLoop、runLoop、streamAssistantResponse、executeToolCalls 和 runToolCall;不讨论会话落盘、压缩或 Skills,这些在 v1.0.0 已不属于本包。
在 Agent.continue() 的分支里还要补上一种情况:assistant 结尾且 steering/follow-up 队列皆空时抛错。这一支说明“没有下一步输入”不是静默结束,而是调用方需要处理的错误。
Agent 是带队列的宿主包装,不是循环本身 ​
小A还不死心:“那 Agent 类总该就是循环了吧?”
“不是。”老Z说,“packages/agent/src/agent.ts 的 Agent 持有 transcript state、listener 集、steering queue、follow-up queue 和当前 AbortController。它的 prompt() 最终调用 runAgentLoop;continue() 在最后消息不是 assistant 时调用 runAgentLoopContinue。最后消息是 assistant 时,它先取一条 steering,没有再取 follow-up,用取到的消息开一段新 run;两个队列都空才抛错。”
// packages/agent/src/agent.ts,Agent 的队列接口(v1.0.0,节选)
/** Queue a message to be injected after the current assistant turn finishes. */
steer(message: AgentMessage): void {
this.steeringQueue.enqueue(message);
}
/** Queue a message to run only after the agent would otherwise stop. */
followUp(message: AgentMessage): void {
this.followUpQueue.enqueue(message);
}“注意这两个队列的时机不同,不能因为都叫‘用户消息’而合并。”老Z说,“PendingMessageQueue.drain() 还受 QueueMode 控制:all 取全部,否则取一条;默认是 one-at-a-time。drain() 先用 peek() 选出要取的消息再移出,所以宿主也可以用 peekQueuedMessages() 预览下一轮会注入什么,而不消费队列。调用 prompt() 时若已有 active run,源码直接抛错并提示使用 steer() 或 followUp(),避免两个 loop 并发改同一 state。”
| API/状态 | 已确认的作用 | 不能从中推出 |
|---|---|---|
prompt |
新增用户消息并启动一段 run | 可以并行开始多个 run |
continue |
从 user/tool result 结尾继续;assistant 结尾时只消费已排队的 steering/follow-up | assistant 结尾也可无条件继续 |
steer |
当前 assistant turn 后、下次请求前注入 | 立刻打断正在到来的 token |
followUp |
Agent 否则会停止时再注入 | 每一轮都会插入 |
abort |
abort 当前 controller | 已经执行的外部副作用自动撤销 |
subscribe |
顺序 await listener,传入 signal | listener 是持久化机制 |
“subscribe 的注释还说明 agent_end 是事件上的末尾,但 Agent 要等该事件的所有 listener settle 后才真正 idle。这个等待关系是观察一致性的一部分;并不等同 session 已经写盘。v1.0.0 的 pi-agent-core 根本不管写盘,那是宿主的职责,例如 coding-agent 的 AgentSession。”
还有一处变化要先记住:v1.0.0 的 AgentContext 只剩 messages 和 tools 两个字段,没有 systemPrompt。system prompt 和模型可见的工具声明都放进 transcript 里的 role: "system" 消息。Agent 构造时用 pi-ai 的 createInitialSystemMessage 把初始 systemPrompt 和 tools 变成首条 system message;state.systemPrompt 只是从 transcript 回放出来的 getter。
runAgentLoop 先建立本次增量 ​
小A想直接看循环:“循环函数进来第一件事干嘛?”
“先建立本次增量。”老Z打开 agent-loop.ts:
低层 runAgentLoop 接收 prompts、已有 context、config、event sink、signal、stream function。它先用 declareToolChanges 处理 prompts,再用结果建立本次 newMessages,用历史 messages 加这批消息构造 currentContext,发出 agent_start、首个 turn_start 和每条消息的 start/end 事件,然后进入 runLoop。
// packages/agent/src/agent-loop.ts,runAgentLoop(v1.0.0,节选)
const initialMessages = declareToolChanges(context, prompts);
const newMessages: AgentMessage[] = [...initialMessages];
const currentContext: AgentContext = {
...context,
messages: [...context.messages, ...initialMessages],
};
await emit({ type: "agent_start" });
await emit({ type: "turn_start" });
for (const message of initialMessages) {
await emit({ type: "message_start", message });
await emit({ type: "message_end", message });
}
await runLoop(currentContext, newMessages, config, signal, emit, streamFn ?? getDefaultStreamFn());“这里有两个列表,别混。”老Z强调,“currentContext.messages 是下一次模型调用可见的完整工作上下文,newMessages 是本次 run 新增加、最后随 agent_end 返回的增量。混淆二者会错误解释为什么 prompts 既被 emit 又会进入模型上下文。”
小A指着第一行:“declareToolChanges 是干嘛的?”
“它比较两份工具清单。”老Z说,“context.tools 是运行时能执行的工具;transcript 里 system message 回放出来的是模型以为自己能调用的工具。两者不一致时,它在待注入消息前插一条 system message,用 toolsAdded/toolsRemoved 声明差异;待注入消息里已有 system message 时,就改写那一条的工具字段。这样回放 transcript 得到的工具集总等于 context.tools。代价是工具变化会作为消息留在历史里,而不是悄悄改一个字段。”
“runAgentLoopContinue 的边界也明确:空 context 会 throw;最后一条是 assistant 也直接 throw。排空队列的逻辑在上一节的 Agent.continue() 里,不在低层函数里。这样不会把 assistant 回答直接接到下一次 provider 请求;真正的 convertToLlm 只在每个 turn 调用时才能验证 provider 接受的消息形式。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。