实现篇第3章 把方向盘交给循环——Agent Loop ​

本章导读: 你会写
src/agent.ts的runAgent():它持有消息状态,收集文本和工具调用,执行工具,再把结果塞回下一轮。关键认知:模型只能“提出”工具请求,执行权和停止判定都在循环手里。
模型接通了。小A给它写了个测试:让模型“读一下 config.ts 然后告诉我里面写了什么”。模型返回了一段文字,小A盯着日志看了半天,问老Z:“它……只是说了?没真读?”
“对。模型只能提出工具请求。”老Z说,“src/agent.ts 的 runAgent() 持有消息状态,依次收集文本和 ToolCall,记录 assistant 消息,再执行工具并记录 tool result。这一章,我们把‘下一步’交给循环。”
user → ModelClient.stream → assistant(text/toolCalls)
→ approval → tool lookup → tool result → 下一轮“把这个流程压成一句话:模型说,宿主做。模型说的话是 tool call,宿主做的事是查找工具、问审批、执行、记录结果。两者之间隔着一条明确的边界:模型永远碰不到 toolsByName 这个 Map,宿主也永远不会自己编造一个 tool call。”
小A:“runAgent 到底接收什么、返回什么?我照着画一个。”
老Z把 agent.ts 翻到签名那里:“先看真实签名。输入里混着‘配置’和‘运行时’,输出里只有消息和停止原因。”
// examples/mini-agent/src/agent.ts,节选
export async function runAgent(options: {
client: ModelClient;
system: string;
tools: Tool[];
user: string;
maxTurns: number;
signal?: AbortSignal;
beforeToolCall?: BeforeToolCall;
sessionPath?: string;
contextMaxChars?: number;
}): Promise<RunResult>;
export type RunResult = {
messages: Message[];
stopReason: "complete" | "max_turns" | "aborted";
};“注意几点。client、tools、beforeToolCall 都是注入进来的,循环不负责创建它们,测试替换起来才方便;signal、sessionPath、contextMaxChars 是可选的,你不传,循环照样跑,只是没有取消、没有持久化、没有裁剪。”老Z说,“返回只有两样:messages(这轮之后完整的事实记录)和 stopReason(三种停止原因之一)。没有‘输出文本’这种字段,你要的最终回答,得从 messages 里自己找。这跟 CLI 章‘打印最后一条 assistant content’是配套的设计。”
小A:“为什么不直接返回 finalText?省得调用方去翻 messages。”
“因为循环不知道哪条算‘最终’。”老Z说,“你定义的最终是‘最后一条 assistant content’,但别的调用方可能要‘最后两条’,可能要‘所有 tool result’,可能要‘把 assistant 和 tool 配对’。把 messages 整个交出去,定义权留给调用方,这是库函数不能替应用做决定的又一个例子。如果 runAgent 返回 finalText,它就替所有调用方假设了‘最终答案 = 最后一条 assistant 文本’,这个假设在多轮、多工具场景里随时会破。”
“可是 main 和 runCli 不就都这么取的吗?”小A问,“一个取最后一条,一个全打印。”
“对,可那是入口层做的决定。”老Z说,“main.ts 里写的是 result.messages.filter(m => m.role === "assistant").at(-1)?.content ?? "",它在自己的文件里决定‘我要最后一条’;哪天 main 想要‘最后三条’,改的是 main,不是 agent.ts。runCli 甚至更宽:它把每条非空 assistant 都写给 write。同一个 RunResult,两个入口两种取法,谁都没动循环。”
老Z把输入参数按必填、可选分了张表:
| 参数 | 必填 | 不传的后果 |
|---|---|---|
client / system / tools / user / maxTurns |
是 | 缺任一项循环无法启动 |
signal |
否 | 没有取消能力,aborted 路径永不触发 |
beforeToolCall |
否 | 默认放行所有工具(见 ?? { approved: true }) |
sessionPath |
否 | 不持久化,进程退出即丢 |
contextMaxChars |
否 | 不裁剪,长会话直接喂全长 messages |
“这张表里每一行‘不传的后果’,都是功能降级,不是崩溃。”老Z说,“设计成可选不是偷懒。这些能力彼此正交:可以有取消没持久化,有持久化没取消,有裁剪没审批。循环把正交的能力拆开,调用方按需组合。”
“那 contextMaxChars 存在时,循环做了什么额外的?”小A问,“它不只是把 messages 原样丢给 stream 吗?”
“看 agent.ts 的 stream 调用点:messages: options.contextMaxChars ? trimContext(messages, options.contextMaxChars) : messages。”老Z说,“裁剪发生在发给模型之前、记录之后。内存里的事实记录永远是全量的,只有送进 stream() 的那一刻才被裁剪。也就是说,裁剪对模型可见、对会话不可见:恢复的 session 还是完整历史,只是这一轮的请求省了 token。这两件事不冲突,对象不同。代价是每次请求都要跑一遍 trimContext,而这套产物的吞吐瓶颈同样不在这。contextMaxChars 另一个约束是 maxChars < 1 直接抛错、预算小到装不下最小自洽单元也抛错,剪不动的预算宁可报错,也不悄悄放空。”
“maxTurns 呢?它和 session 里恢复的历史是什么关系?”小A追问。
“maxTurns 只数本轮的循环次数,不数历史里的轮次。”老Z说,“恢复的历史作为 messages 的起点参与上下文,但 for (let turn = 0; turn < options.maxTurns; turn++) 的计数从 0 开始,恢复了多少轮旧对话,不影响本轮还剩几次。历史决定起点,maxTurns 决定本轮上限。main 和 runCli 都传 8,这是入口定的策略,循环里没有写死任何轮数。”
消息先记录,再继续 ​
小A:“消息从哪开始?会话文件要不要一开始就加载?”
“加载要放在取消检查之前。”老Z指给他看 agent.ts 的开头:
const messages: Message[] = options.sessionPath ? await loadSession(options.sessionPath) : [];
if (aborted(options.signal)) {
return { messages, stopReason: "aborted" };
}
const record = async (message: Message) => {
messages.push(message);
if (options.sessionPath) await appendSession(options.sessionPath, message);
};
await record({ role: "user", content: options.user });“加载发生在取消检查之前,因此 pre-abort 可以返回已恢复历史;检查发生在新 user message 的首次 record() 之前,所以不会污染 session 文件。”老Z说,“record 先更新内存再追加磁盘;这意味着 append 失败时内存和文件可能短暂不一致,当前实现让异常上抛,不提供补偿或重试。”
小A:“正常 session 的往返测过吗?”
“正常 session round-trip 已由直接调用 runAgent({ sessionPath }) 的回归测试覆盖;main.ts 与 runCli() 当前都没有装配 sessionPath。”
“为什么入口不装配?”小A问,“持久化不是现成的吗?”
“是现成的,但装不装配由入口说了算。”老Z说,“main 面向一次性脚本,跑完打印、进程退出,会话文件对它没意义;runCli 面向交互,理想情况下应该接上持久化,但当前没接就是没接,不能假装有。测试里反复出现 sessionPath,恰恰证明循环这条链路是通的、可测的;入口不接,只是范围问题。等到哪个入口真的需要‘中断后恢复’,装配处加一行 sessionPath 就行,实现篇第12章清单里‘main/runCli 尚未装配 sessionPath’那条,说的就是这个。”
“那 loadSession 恢复的历史,会被 trimContext 裁掉吗?”小A又问。
“会,而且是故意的。”老Z说,“恢复的历史和本轮消息一起进 messages,请求前统一过 trimContext,预算优先,历史再久也按预算办。持久化管磁盘,保证历史不丢;裁剪管窗口,保证模型不撑,两边由同一条 messages 数组衔接。”
一轮如何收集事件 ​
小A凑过来:“事件具体怎么收?”
let text = "";
const calls: ToolCall[] = [];
for await (const event of options.client.stream(request)) {
if (event.type === "text") text += event.text;
if (event.type === "tool_call") calls.push(event.call);
}
if (text === "" && calls.length === 0) throw new Error("model completed without text or tool calls");“字符串在本轮局部累积,工具请求保留 id 与输入,流结束了才提交 assistant message。”老Z说,“空响应检查在 commit 前,session 不会得到一条看似正常的空 assistant。”
“流式过程中 stream() 抛错了呢?”小A问,“还没 commit 的 text 和 calls 去哪了?”
“被丢弃。”老Z说,“agent.ts 的 try/catch 包住整个 for-await,catch 里先查 signal 是否已取消:取消了就走 aborted 返回,没取消就直接 throw error,把原始异常抛给调用方。局部变量 text 和 calls 这一刻随作用域一起消失,不落盘,也不返回。它们是这一轮的临时结果,不是会话事实,事实要 commit 之后才算数。取消时丢掉半截流,凭的也是同一条规矩:未提交即不存在。”
小A:“done 事件呢?ModelEvent 里有 done,这段循环好像没处理它?”
“没处理,done 对 loop 是个无操作。”老Z说,“for await 遍历的是 AsyncIterable<ModelEvent>,done 只是流里一个普通元素,loop 看到它既不累加也不抛错,真正表示‘流结束了’的是 for-await 自然走完。done 对 loop 透明,对 toModelEvents 才有意义:它保证协议映射完成、前面没有半截 block。这个事件是给 Provider 映射层收尾用的,循环只关心自己收集到了什么,各看各的。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。