单独运行的智能体内核
pi-agent-core 的 Agent 类是去掉了编码智能体的 Pi 循环:本章带着一个工具、以智能体的形式运行这个论断核查任务,并精确展示宿主本来在提供什么。
第 36 章那个论断核查器有一个极限。把证据递给它,它就回答。给的证据太少,它会说 insufficient 然后停下,因为一次单独的调用不能去查找更多。
查找更多就是一个循环:模型要某样东西,你运行它,你把结果交回去,然后模型再次决定。你已经从外面见过那个循环三十六章了。本章从里面运行它,大约四十行,用的正是编码智能体所构建于其上的那个类。
不是编码智能体
先说一个命名上的要点,因为它能帮你避免一次走错路。pi-agent-core 就是 Pi。它是 pi-coding-agent 所构建的包,而第 1 章的那个循环就是它的代码。本章省掉的是 pi-coding-agent:会话、信任门、扩展、终端。所以这一部分的标题是"在编码智能体之下",而不是"没有 Pi"。
它已发布的依赖是 @earendil-works/pi-ai 和 typebox,没有别的。列表里没有终端库、没有文件系统层,也没有 provider SDK。这就是第 1 章那个层次论断所依据的有文档记载的事实,也是下面的程序为什么能跑在一个普通 Node.js 进程里的原因。
flowchart TD
subgraph CORE["pi-agent-core — 1.0.4 上零个界面导入"]
L["那个循环<br/>轮次、钩子、事件、队列"]
end
subgraph AI["pi-ai"]
M["一次请求<br/>认证、载荷、停止原因"]
end
APP["你的代码<br/>工具、提示词、状态"] --> L
L -->|"streamFn:一个函数,不是一个导入"| AI
L -.->|"没有终端、没有文件、没有 provider SDK"| N["上面的一切都是你的"]
那条虚线就是本章的全部。内核里没有任何东西触及终端、文件系统或 provider;智能体应用所是的一切——会话、上下文文件、技能、信任、界面——都是你在这条线之上写的代码。
一个 Agent 由什么构成
上面那个依赖论断是可以核实的,而知道怎么核实它是值得的。在 pi-agent-core 1.0.4 上,该包 dist/ 里出现的每一个模块说明符,都是 @earendil-works/pi-ai、typebox,或该包内部的一条相对路径之一。两个声明的运行时依赖,以及零个界面导入。传递依赖图也闭合了这一点:pi-ai 依赖 provider SDK、遥测和 schema 库,而不依赖任何 UI 或 TUI 包。
那是一个锁定发布版上可计数的性质,这就是为什么本章在陈述它时带着版本号——这个数字稳定,只是因为那个锁定稳定。第 1 章把它的分层论证建立在这上面,而附录 A 记录了那次测量。
Agent 构造函数接受两样要紧的东西。一个模型,以及一个流函数:
new Agent({
initialState: { systemPrompt, model, tools },
streamFn: models.streamSimple.bind(models),
});
streamFn 是内核触及模型的方式。它是一个从模型和一段转录记录到一个事件流的函数,而 Models.streamSimple 正是那个形状。这就是层与层之间的接缝:智能体内核不导入 provider,它被交给你一个函数。换掉那个函数,你就换掉了 provider,而它上面的任何东西都不用碰。Pi 交付了一个这样的替换品:streamProxy 把调用经由一个服务器转发,用于一个不能持有 provider 密钥的应用。AgentOptions 也有一个 transport 字段,它被转发给那个流函数,还有一个 getApiKey 钩子,它在请求时提供一个凭据。setDefaultStreamFn() 为那些想一次性装好一个流函数的宿主而存在,这样构造智能体的代码就不需要传它。
一个 AgentTool 是一个 pi-ai Tool 加上若干新增。你总要写的两个是用于显示的 label,以及一个做事的 execute()。该声明还有四个可选字段:prepareArguments、executionMode、outputSchema 和 replay。声明那一半正是第 36 章交给模型的东西。执行那一半是第 36 章故意省掉的东西:
execute: (toolCallId, params, signal?, onUpdate?) => Promise<AgentToolResult>
等 execute() 运行时,params 已经依据 schema 验证过了。要让 TypeScript 知道 params 的形状,就用它的 schema 给这个工具定型:AgentTool<typeof LookupParams>,其中 LookupParams 是那个 TypeBox 对象。不给类型参数,参数就是 unknown,而一个 execute(_id, params: { query: string }) 编译不过。那是通过编译本书自己的示例发现的,而它们被编译正是为了这个原因。
你返回 content,模型读它;以及 details,你的代码留着它。如果这个工具做不了它的活,它就抛出,而内核把那变成一个带 isError: true 的工具结果。该声明提供了第二条通道:一个结果可以自己带 isError: true,“以便报告一次失败而不抛出”,而模型把它看作一个错误结果。不算失败的,是一个在 content 里描述失败却自称成功的结果,那样模型就得读散文才能发现什么也没发生。这与第 6 章给 bash 的规则、第 17 章给扩展工具的规则是同一条。编码智能体没有发明它。它从这里继承它。
两个可选字段各值得一句话。outputSchema 配上 AgentToolResult.structuredContent 是一个给程序化调用者用的、已声明的机器可读结果,它不被发给模型:与第 38 章那个类型化出口是同一个想法,只是低了一级。replay("never" 或 "safe")是工具对自己如何恢复一个结果未知的效果所做的声明。它是工具为自己选的一个值,第 39 章和第 42 章会回到它。
那个研究智能体
下面是这个论断核查任务,加上一个查找东西的办法:
import { Agent, type AgentTool } from "@earendil-works/pi-agent-core";
import { Type, type Model, type Models } from "@earendil-works/pi-ai";
export interface Corpus {
[id: string]: string;
}
// A tool is data plus one function. This one is read-only and pure, so it is
// safe to run in parallel with itself.
const LookupParams = Type.Object({ query: Type.String() });
export function lookupEvidence(corpus: Corpus): AgentTool<typeof LookupParams> {
return {
name: "lookup_evidence",
label: "Look up evidence",
description: "Return the corpus entries whose text contains the query. Use short keywords.",
parameters: LookupParams,
async execute(_id, params) {
const q = params.query.toLowerCase();
const hits = Object.entries(corpus).filter(([, text]) => text.toLowerCase().includes(q));
const text = hits.length ? hits.map(([id, t]) => `[${id}] ${t}`).join("\n") : "no matches";
return { content: [{ type: "text", text }], details: { query: params.query, hits: hits.map(([id]) => id) } };
},
};
}
// The agent core takes exactly two things from the outside: a model and a
// stream function. The prompt, the tools and the transcript are ours.
export function makeResearchAgent(models: Models, model: Model<any>, corpus: Corpus): Agent {
return new Agent({
initialState: {
systemPrompt: "Research the claim using lookup_evidence. Answer in one sentence.",
model,
tools: [lookupEvidence(corpus)],
},
streamFn: models.streamSimple.bind(models),
});
}
其中有三点是值得注意的选择。
lookupEvidence() 是只读且纯粹的。它读一个你传进去的语料库,并返回文本。因为它对世界没有效果,智能体身上没有任何东西需要守护它,而这个工具可以安全地与它自己并行运行,这是内核对一条助手消息中那些工具调用的默认行为。一个工具可以用 executionMode: "sequential" 覆盖这一点,而一批里有一个顺序工具就会让整批变成顺序的。第 39 章会回到这一点为什么重要,那是在一个工具确实有效果之后。
一次未命中把 "no matches" 作为普通内容返回。一个什么都没找到的搜索是一个答案,不是一次失败,而模型应该被允许对它做推理。第二个测试钉住了这一点。
系统提示词是一句话。内核拥有提示词、工具和转录记录,而 initialState 就是全部配置。没有 AGENTS.md 要发现,也没有 APPEND_SYSTEM.md 要合并。那些是编码智能体的特性,第 18 章和第 28 章是它们住的地方。
运行这个循环
const agent = makeResearchAgent(models, model, corpus);
const seen: string[] = [];
agent.subscribe((e) => {
seen.push(e.type);
});
await agent.prompt("Did the release ship?");
在 faux provider 被脚本化为先请求 lookup_evidence 然后回答的情况下,测试断言了所发生之事的形状:
const roles = agent.state.messages.map((m) => m.role).filter((r) => r !== "system");
assert.deepEqual(roles, ["user", "assistant", "toolResult", "assistant"]);
assert.equal(faux.state.callCount, 2); // one request per turn
那段四消息转录记录就是第 1 章的那个循环,你和它之间什么都没有。助手要了一个工具,工具结果作为它自己的消息进入转录记录,然后模型被再次询问。两次请求,因为有两轮。
agent.state.messages 就是转录记录,而在裸内核里它归你读也归你赋值——它上面没有会话层来反对。
在 pi-coding-agent 内部,不要给它赋值。SessionManager 拥有权威副本(第 34 章),而一次对内核转录记录的赋值会编译、会运行,却不会改变会话发送的东西。那是已观察、而非本书提出:第 34 章的测试套件运行了它,用一条伪造的用户消息覆写 agent.state.messages,再次发提示词,并断言那段伪造文本从未到达 provider,而真实历史到达了。所以同一行在一层里是权威的,在另一层里是惰性的,而你在哪一层决定了赋值是否有意义。
断言里把领头那条系统消息过滤掉,是因为内核把提示词和工具声明记录为转录记录开头的一条系统消息。第 26 章描述了磁盘上同样的结构;这就是它被创建的地方。
这些事件你已经认识,只少两个
agent.subscribe() 交付你在第 33 章遇到过的那个生命周期:agent_start、turn_start、message_start、message_update、message_end、tool_execution_start、tool_execution_update、tool_execution_end、turn_end、agent_end。在内核里,监听器按注册顺序被等待,而 await agent.prompt() 只有在 agent_end 的监听器都落定之后才落定。
有两个名字缺失,而这个缺失是有信息量的。**agent_before_settle 和 agent_settled 根本不在 pi-agent-core 的类型里。**它们属于编码智能体,因为它们描述的是编码智能体在内核运行结束之后自己的额外工作:自动重试、溢出恢复、压缩、排队的消息。当第 1 章和第 16 章说 agent_end 结束的是一次低层运行而不是整个工作时,“低层"指的是这个:内核的运行。内核没有要等待的恢复,所以对内核来说 agent_end 真的就是终点。无论谁包裹它,都要添加其余部分,并添加那个宣告其余部分已结束的事件。
引导和后续跟进在内核里,带着第 25 章描述过的语义:agent.steer() 在当前助手轮次之后交付,agent.followUp() 只在智能体否则要停下时交付,两者都有 "all" 和 "one-at-a-time" 模式。第 25 章的终端按键就是这两个方法的一个界面。
宿主本来在为你做什么
自己跑一次这个循环,编码智能体提供的那份清单就变具体了。下面没有任何一样存在于这个程序里。
| 能力 | 它住在哪里 | 在本章中 |
|---|---|---|
| 循环、消息、工具执行、事件 | pi-agent-core |
在场 |
| 选择模型并触及它 | pi-ai + 你的 streamFn |
由你提供 |
一个会话文件、一棵树、/tree 与 /fork |
pi-coding-agent |
缺席:转录记录是内存里的一个数组 |
| 压缩 | pi-coding-agent |
缺席:transformContext 是你写自己的地方 |
| 自动重试与溢出恢复 | pi-coding-agent |
缺席 |
| 上下文文件、技能、提示词模板 | pi-coding-agent |
缺席 |
内置的 read、bash、edit、write |
pi-coding-agent |
缺席:唯一的工具是你写的那个 |
项目信任、tool_call 扩展 |
pi-coding-agent |
缺席:第 39 章给出内核自己的钩子 |
| 一个终端、JSON 或 RPC 界面 | pi-coding-agent |
缺席:subscribe() 就是界面 |
把最后一列当作重点来读。凡是缺席的东西,现在都由你来决定,这是一种代价;也是某种无法干扰你的东西,而这是你离开一个插件繁重的宿主时想要的东西。一个不存在的 bash 工具不可能被一个出错的模型调用。第 42 章的第一级"不要授予该能力"在这里是默认的——而第 42 章把它编号为第 2 级,不是第 1 级。第 1 级是指令;第 2 级是该能力干脆不存在。
用 Agent 还是 agentLoop
pi-agent-core 也把这个循环作为一个函数导出,agentLoop(),它返回一个事件流。除非你有理由不这样,否则请用 Agent 类。README 把为什么说得很具体:原始循环的流是观察性的,并且"不会在你的异步事件处理落定之前,就让后续的生产者阶段继续”。Agent 类让 message_end 处理成为工具预检之前的一道屏障,所以一个 beforeToolCall 钩子看到的状态已经包含那条索要该工具的助手消息。一个针对原始循环写的守卫,会和它自己的记账发生竞态。
你能断言什么、不能断言什么
有文档记载:Agent 构造函数选项、streamFn、作为 Tool 扩展的 AgentTool、事件名、监听器被等待的行为、抛出即失败、并行工具执行为默认、引导与后续跟进,以及依赖列表(pi-agent-core README 与声明,1.0.4)。
已观察:examples/ch37-agent-core/ 中转录记录的形状和请求次数,在脚本化响应下,在 1.0.4 上。agent_settled 不在内核的类型里,这是对声明的一次阅读,而不是一次运行时观察。
本书提出:“宿主本来在为你做什么"那张表是本书的总结,从两个包的文档汇集而来。它不是 Pi 发布的表。
下一章
这个智能体能工作,而它会做模型要求它做的任何事,以模型回答的任何形状。它的答案是散文。第 36 章花了整章从一次调用里逼出一个类型化结果,而一个循环让那变得更难,因为现在由模型决定它什么时候做完。
第 38 章弥合那道差距:一个智能体,它唯一的完成方式就是交回一个匹配某个 schema 的值。