← Pi Agents

你正在为它编程的那个循环

在写扩展之前,先看清它要挂接的那个循环:一条提交的消息如何变成一次模型请求,一次工具调用如何变成一个结果,以及一次运行何时结束。

你打算写一个扩展。在那之前,你需要知道你要扩展的是什么。

这是大多数人会跳过的一步。他们装上 Pi,跑一个任务,得到一个差不多的结果,然后就开始对照着从观察中得来的心智模型写代码。这个模型通常足够接近、能跑,但在少数几个具体的地方是错的——而所有有意思的 bug 都住在这些地方。

所以本章把 Pi 的一轮完整地讲一遍,并把你可以挂接的位置逐一命名。

一轮

Pi 的文档把它称为智能体循环(agent loop)。这里值得精确一点,因为"循环"这个词用得很松,而精确的版本本身就回答了大多数扩展问题。

一条提交的消息会被加入活动分支。Pi 用四样东西构建一次模型请求:系统提示词、活动分支、可用工具,以及模型设置。这个请求通过选定的 provider 发出。

provider 流式返回一条助手响应,其中可以包含文本和工具调用。Pi 记录这条响应,执行每一个工具调用,并记录结果。这就算完成一轮。

然后是一个问题:

工具结果,或者排队的消息,是否需要再一次模型请求?
   |
   +-- 是   ->  开始另一轮
   |
   +-- 否   ->  本次运行结束

这就是整个循环。本书其余的一切,都是关于在这个循环的哪个位置挂接的决策。

四个输入,一次请求

模型请求由四个输入组装而成。这个分解值得记在心里,因为每一个都可以单独寻址,而你将要写的几乎每一个扩展,操作的正好是其中一个。

输入 它是什么 你怎么改它
系统提示词 Pi 的基础指令加上被发现的上下文文件 SYSTEM.md、APPEND_SYSTEM.md、AGENTS.md,或一个事件处理器
活动分支 通往当前条目的那段对话历史 对话本身,或 context / context_with_system
可用工具 模型可以调用什么 pi.registerTool()、pi.setActiveTools()
模型设置 用哪个模型,以及它思考得多用力 /model、思考级别、settings.json

一个往转录记录里插入内容的扩展,动的是第二个输入。一个注册工具的扩展,动的是第三个。从外面看它们感觉不同,从里面看它们的行为毫无相似之处——这是第 18 章的主题。

什么是活动分支

Pi 把会话存储为树。每个条目有一个 ID,并指向它的父条目。从根到当前条目的那条路径就是活动分支,而正是这条路径为下一次请求提供历史。

两个后果立刻可以推出,而且两者以后都会救你一命。

**分支不是会话。**一个会话文件可以包含多个分支。回去编辑就会产生另一个分支。其他分支上的所有东西仍然存在于文件中。当某个东西检查"这段对话"时,它必须决定自己指的是活动分支还是整棵树——这是两个不同的问题,各有不同的正确答案。

**压缩不会删除。**当 Pi 执行压缩时,它会插入一个摘要条目,在后续请求中替换更早的消息。原始条目仍然留在树里。这就是为什么一个被压缩过的会话仍然可以被完整检查,也是为什么一个压缩 bug 通常是关于"你数了哪些条目"的 bug,而不是关于"条目缺失"的 bug。

第 24 章正经讲这棵树,第 23 章讲压缩。现在唯一需要记住的是:历史是一棵树,而下一次请求只读其中一条路径。

一轮不是一次运行

再一个区分,而正是这一个绊住了大多数扩展作者。

一轮(turn)是一次模型请求,加上紧随其后的工具执行。一次运行(run)是整个序列——一轮、工具结果、又一轮、工具结果,直到不再需要更多为止。

错误:"agent_end 触发了,所以运行结束了。"

正确:"agent_end 结束的是一次低层智能体运行。自动重试、溢出恢复、压缩、引导或后续工作仍然可能接在后面。"

两者之间隔着两个边界,而 Pi 的文档以不寻常的谨慎对待它们:

  • agent_before_settle——最后一个可行动的边界。这里的一个处理器可以追加条目,并请求一次继续。
  • agent_settled——终局性的,且仅作通知。它之后什么也不能继续。

两者都重要,而它们在第三部分中最重要,因为自动重试、恢复、压缩和排队的工作都可能在 agent_end 之后继续。第 16 章是完整论述。

排队的消息

有两类消息可以在运行进行中到达,而它们落在不同的位置。

引导(steering)消息在当前助手轮次之后进入。它们不会打断已经在飞行中的工具调用;它们要等那一轮结束后才落位。

后续跟进(follow-up)消息在智能体完成它手头的工作之后进入。那是在智能体不再要求更多轮次之后,而不是在 agent_settled 之后:排队的后续工作会在最终落定边界之前被处理完,这正是 agent_settled 成为真正终点而非暂停的原因。第 25 章讲队列机制,第 16 章讲事件顺序。

而中止会停止当前运行,并把排队的消息还给编辑器,而不是丢弃它们。

这是一个小而后果重大的设计:没有任何机制能在飞行途中打断一轮。如果你需要工作立刻停下,你就中止这次运行,而任何排队的消息都会回到人类手中。第 25 章讲机制;这里要紧的是你知道队列存在、以及它在哪里排空。

上下文从哪来

在请求发出之前,Pi 组装提示词。这部分会让人意外,所以值得直说。

系统提示词由 Pi 的基础指令和被发现的上下文文件构成。请求还携带工具定义与技能描述。

完整的技能指令不包含在内。它们在需要时才加载,即当一个任务匹配某个技能的描述时。正是这一点,让一整个目录的技能在你还没有用过其中任何一个之前,不会消耗你的上下文。

扩展可以添加指令或转换上下文。提示词模板在任何东西变成用户消息之前,先在编辑器里展开。选中的文件、图片、粘贴的文本和 shell 输出,都可以成为消息内容。

所以当模型"知道"某件事时,是因为下面某一样把它放了进去:

base instructions      基础指令
context files          AGENTS.md 等,按目录发现
APPEND_SYSTEM.md       追加的指令
SYSTEM.md              替换基础提示词
skill descriptions     始终存在
skill instructions     匹配到时按需加载
tool definitions       始终存在(针对已激活的工具)
extension additions   你按事件添加的任何内容
editor input           提示词模板、@ 选中的文件、粘贴的内容

这份清单就是上下文。没有别的东西。当你在调试模型为什么知道或不知道某件事时,你要顺着这份清单一路查下去。

这个循环,画出来

    flowchart TD
  IN["INPUT<br/>message added to the active branch"] --> REQ["REQUEST<br/>system prompt, active branch,<br/>tools, model settings"]
  REQ --> PROV["PROVIDER"]
  PROV --> RESP["RESPONSE<br/>text and tool calls"]
  RESP --> EXEC["EXECUTION<br/>run each tool call, record each result"]
  EXEC --> MORE{"more needed?"}
  MORE -->|yes| REQ
  MORE -->|no| DONE["RUN ENDS"]
  

本书中的每一个集成点都是那张图上的一个方框,而每一个都标明了扩展挂接在哪里:

    flowchart TD
  X["EXTENSION"] --> T["registerTool"] --> E["EXECUTION"]
  X --> C["context handler"] --> R["REQUEST"]
  X --> V["pi.on, any event"] --> G["the edges between boxes"]
  X --> P["registerProvider"] --> PR["PROVIDER"]
  

提示词模板改变的是到达 INPUT 的内容。

为什么这一章排第一

一个不知道上下文如何组装的扩展作者,会写出一个与系统对抗的扩展,并且——这才是代价高昂的部分——无法判断 bug 是自己的还是 Pi 的。

从外面看,症状全都一样。模型无视你的指令。你的工具从不出现。你注入的内容在压缩之后消失。你的处理器在错误的时刻触发。在每一种情况下,你需要回答的问题都一样,而它就由上面那张图回答:我挂接到哪个方框上了,那是我本来要的那个方框吗?

这个循环是哪一类东西

在这一切变得可用之前,有一个问题必须先回答,因为它决定你自己的代码被允许住在哪里:智能体是一次模型调用,还是它自己的一层?

Pi 对此毫不含糊,而证据根本不在文档里——它在已发布包的依赖图里。在 1.0.4 版本上:

pi-ai           模型访问:provider SDK、schema、遥测。没有循环,没有
                工具执行,没有会话。
     ↑
pi-agent-core   pi-ai + typebox。循环、消息、状态、工具执行。
     ↑                       ↑
pi-coding-agent  直接组合 pi-agent-core 与 pi-ai,并包含 pi-tui、
                 pi-mcp、pi-codemode 和 chord

pi-tui           终端渲染。对智能体一无所知。

承重的事实是:pi-agent-core 不依赖 pi-tui 的任何东西,而 pi-tui 也不依赖智能体的任何东西。内核可以在没有终端、没有应用、没有特定 provider 的模型的情况下运行。你可以嵌入它;同一个智能体随后可以驱动一个终端、一个 JSON 流、一个 RPC 进程,或者一个你自己写的应用。

这里把"内核"的含义说精确是值得的,因为它不止一个循环。它自己的包描述是"general-purpose agent with transport abstraction, state management, and attachment support",而交付的模块约六十 KB,分布在一个 agent、一个 loop、一个 proxy 和类型表面上。它拥有循环、消息、智能体状态、工具执行和事件流。

所以有用的分解比"模型"和"智能体"有更多级。下面是本书使用的这个栈,并注明依赖方向:

Interface                 驱动与观察:终端、print、JSON、RPC、一个 SDK 宿主
        │ 驱动
Application / host        智能体的用途所在,以及权限所在之处
        │ 使用
Agent application         会话、压缩策略、上下文策略、扩展、MCP、工作流
        │ 使用
Agent core                循环、消息、状态、工具执行、事件流
        │ 使用
Model access              对某一个模型发出一次请求,再流式返回
        │ 使用
Provider                  Anthropic、OpenAI、一个本地服务器

                          ┊  不是一层:效果边界,即决策一旦越过便无法
                          ┊  收回的那个点。它横切整个栈。

把它当作依赖方向来读:每一层使用它下面那一层,而对它上面那一层一无所知。**智能体位于模型之上、赋予它目的的应用之下。**在 Pi 的包里,中间三层有名字:pi-ai 是模型访问,pi-agent-core 是智能体内核,pi-coding-agent 是一个智能体应用。它上面的应用或宿主是你的:那个程序、那个 CI 作业,或 Pi 会话运行其中的那个服务。第 36 章拆解下面几级,第 42 章讲那条虚线。

层 拥有 不拥有
Provider 模型本身、它的 API、它的限制 关于你的智能体的任何东西
模型访问 模型身份、认证、请求与响应的转换、流式传输、能力 智能体策略、工作流、上下文策略
智能体内核 循环、消息、智能体状态、工具声明与执行、事件流 渲染、凭据、机器的文件系统
智能体应用 会话、压缩与上下文策略、扩展、MCP、工作流 循环本身
应用 / 宿主 用途、用户、部署所授予的权限 智能体的内部
界面 驱动与观察智能体 智能体是什么

上面的包图是 documented(有文档记载,即那些清单文件),下面的程序是 observed(已观察),而这是一个正确的分解则是 proposed(本书提出的设计论证)。本节余下部分讲这个分解给你带来什么、不带来什么。

可替换性不是隔离

有两种不同的性质都被叫做"层次分离",而本书需要把它们分开。

可替换性是替换:换掉 provider 而不重写智能体策略,换掉终端而不重写智能体,换掉宿主而不碰 provider 适配器。它是检验你是否理解了一个层的测试。第四部分为界面演示了这一点:第 31 章在交付的二进制文件上通过 print、JSON 和 RPC 驱动同一个智能体,每次都得到相同答案;第 32 至 35 章带同一套机器走过五个界面。当一处改动非改别处不可时,那就是耦合。

隔离性是遏制:一层能否阻止上一层所做决策的后果。一个可替换的层并不因此就是一个隔离的层。同一个智能体在三个界面背后做同一件事,这正是第 31 章的论点,也正是界面不是安放安全属性的地方的原因:它可以被换掉,而智能体能做什么丝毫不变。第 39 章在循环内部测量同一道鸿沟,第 42 章把它变成一条关于权限可以住在哪里的规则。

可替换性在第 31 至 35 章中是 observed(已观察)。隔离性是本书其余部分不断向每一层追问的,而答案几乎总是"不是这一层"。

运行在没有 provider、没有终端情况下的智能体内核

一个只能读的层只是断言。这一个你可以运行。下面的程序只用 pi-agent-core 和 pi-ai:没有 pi 二进制,没有终端,没有凭据。那个"模型"是 pi-ai 为测试随附的 faux provider,它会重放你写的脚本,所以循环是真的,模型不是。

import { Agent, type AgentTool } from "@earendil-works/pi-agent-core";
import {
	Type,
	createModels,
	fauxAssistantMessage,
	fauxProvider,
	fauxText,
	fauxToolCall,
} from "@earendil-works/pi-ai";

// The provider layer: a scripted stand-in for a model.
const faux = fauxProvider();
const models = createModels();
models.setProvider(faux.provider);

// A tool is a name, a schema and an execute(). Nothing here knows about Pi.
const WordCountParams = Type.Object({ text: Type.String() });

const wordCount: AgentTool<typeof WordCountParams> = {
	name: "word_count",
	label: "Word Count",
	description: "Count the words in a string.",
	parameters: WordCountParams,
	async execute(_id, params) {
		const n = params.text.trim().split(/\s+/).filter(Boolean).length;
		return { content: [{ type: "text", text: String(n) }], details: { words: n } };
	},
};

// Turn 1 asks for the tool. Turn 2 answers from its result.
faux.setResponses([
	fauxAssistantMessage([fauxToolCall("word_count", { text: "the quick brown fox" })], { stopReason: "toolUse" }),
	fauxAssistantMessage([fauxText("Four words.")]),
]);

// The agent core: loop, messages, state, tool execution, events.
const agent = new Agent({
	initialState: { systemPrompt: "You count words.", model: faux.getModel(), tools: [wordCount] },
	streamFn: models.streamSimple.bind(models),
});

agent.subscribe((e) => {
	if (e.type === "tool_execution_end") console.log("tool:", e.toolName, JSON.stringify(e.result.details));
	if (e.type === "message_end" && e.message.role === "assistant") console.log("stop:", e.message.stopReason);
});

await agent.prompt("How many words in 'the quick brown fox'?");

在本书旁边的 examples/ 目录里运行它,用 Node.js 22.19 或更高版本,它可以直接执行 TypeScript。本书的运行本书的示例页面有完整的设置——锁定的安装方式、前置条件,以及运行一章和验证全部章节之间的区别。这个程序会打印:

stop: toolUse
tool: word_count {"words":4}
stop: stop

这就是第 1 章的循环,标签都填上了。第一个 stop: toolUse 是请求工具的那个响应;tool_execution_end 是执行方框;第二个响应是"还需要做什么吗?“这个问题在回答不。把 models.streamSimple 换成一个真实 provider 的流函数,文件里其他任何一行都不用改——这就是上面那个可替换性测试在实践中的含义。

要从它带走三件事。provider 只是一个参数,streamFn。工具是一个普通对象,它的 execute() 返回 content 和 details,与第 15 章在扩展里用的形状相同。而 Pi 在其上添加的一切(会话、压缩、信任、终端)都不在场——这就是上表中智能体内核与智能体应用之间的区别。

*Observed,而非 documented:*这个程序是 examples/ch01-agent-core/agent-core.ts,由本书自己的测试套件对着 1.0.4(锁定的版本)的 @earendil-works/pi-agent-core 和 @earendil-works/pi-ai 运行。Agent 类、agent.subscribe()、fauxProvider() 和 streamFn 选项记录在那些包的 README 和声明中。第五部分(第 36 至 41 章)以这个程序为基础继续构建。

表示跨越边界不等于责任跨越边界

最后一个澄清,因为 provider 层看着像那个明显的肇事者,而它并不是。

Pi 的模型抽象必然知道一次工具调用的形状。一个模型协议有工具声明、工具调用增量、工具调用响应和工具结果消息,而任何与模型对话的层都必须能表示这四者。pi-ai 里含有以工具调用命名的类型,就是这个意思,别无其他——它是线上格式,不是策略。

模型访问层绝不能拥有的是那些决策:

到底该存在哪些工具
某个给定的工具是否已获授权
智能体何时应该再进行一轮
适用什么项目策略
一个结果应当如何改变工作流

所以有用的测试不是这一层是否提到那个东西(这没有意义),而是这一层是否决定。一个知道工具调用长什么样的模型访问层没问题。一个知道"这个仓库每次编辑后都必须跑测试"的模型访问层是架构泄漏,而且无论那个类型是否住在名为 pi-ai 的包里,它都是泄漏。

这与本书其余部分用的是同一种纪律,只是低了一级:一个机制表示什么,不是它负责什么。第 11 章把它变成一条放置规则,第 42 章把它变成流程与边界之间的区别。

层边界究竟在哪

智能体内核是一个真实的、可分离的层,而 Pi 的生态系统证明了整类产品——审查工作流、记忆系统、权限决策层、沙箱、协议桥——都可以建在它上面而不碰它。这部分是站得住的。

站不住的是那种整洁的假设:内核只拥有一个循环。它拥有循环、消息、智能体状态、工具执行和事件流。而它周围的若干决策,已经反复被证明根本无法表达为扩展。

三个案例让这个模式变具体,而不是修辞。每一个都是一个需求、一个差一点就行的机制、分叉不得不改动的那个具体位置,以及它对接缝说明了什么。**它们是报告出来的,不是运行出来的。**它们来自一个扩展优先的分叉自己的变更记录,是下面接缝原则的 proposed(本书提出)证据,而三者都没有在本书的测试套件中被复现。第 39 章在智能体内核的钩子上测试这个原则本身,在那里它可以被运行。

**1. 在模型拒绝一个过长上下文时执行压缩。**一个扩展可以观察 session_before_compact,也可以在它之后行动,它还可以自己调用 ctx.compact()。它无法拦截 provider 拒绝过长请求的那个点,所以它无法保证恢复发生在那一轮失败之前。分叉改动了内核里的压缩路径。

**2. 拒绝在一个负担不起的模型上启动会话。**一个从 createAgentSession 抛出的预算检查运行在构造函数里,而那发生在任何扩展钩子被接线之前。那里根本没有拦截点,不是"有一个窄的拦截点”。分叉修改了内核构造函数。

**3. 由部分而非追加来构建系统提示词。**一个 before_agent_start 处理器可以为某一轮追加提示词。它无法替换产出提示词的那个构建器,所以一条必须作用于提示词结构——而不只是其文本——的规则没有接缝。分叉重写了提示词构建。

共同形态值得命名,因为它比那三个例子中的任何一个都有用:

一个扩展点只有在它能在那些决策变得不可逆转之前拦住它们时,对它们才是一个真正的架构接缝。

两点细化让这句话可用。第一,接缝是对一个具名决策而言的接缝。beforeToolCall 是"这个效果可以发生吗"的接缝,而如第 39 章所示,一个对该决策不是接缝的钩子,仍可能是另一个决策(“这次运行继续吗”)的接缝。第二,“不可逆转"是决策的属性,不是钩子的属性:问题始终是这个钩子在它触发时还能改变什么。

第三点细化,是在一次独立评审施压之后补上的:先按声明的协议判断一个接缝,再按语言允许什么来判断它。第 39 章把两者分开,而正是这个区分让这个论证不会在两个方向上都出错。一个没有否决字段的钩子并不因此就无能为力——一个会抛出的 prepareRequest 能阻止请求,一个会改写 args 的 beforeToolCall 能改变工具收到什么。两者都在 1.0.4 上被观察到。两者都没有文档记载,而建立在任其之上的策略,是建立在一个实现细节之上的。所以问题不是"我能做到这件事吗?",而是"我能以这个包所承诺的方式做到这件事吗?",而对一个正在设计扩展的读者来说,诚实的答案是后者。

观察很容易暴露。事后观察是扩展表面提供的大部分东西。仲裁才是会失败的东西。

所以这个论断的可辩护版本,比那个整洁版本更窄,也更有意思:

Pi 有一个可分离的智能体内核。它拥有循环、核心状态和执行抽象,大量产品可以原封不动地建在它上面。但有若干个生命周期决策——何时压缩、是否准入一个会话、基础提示词如何构建——是扩展只能看到太晚而无法影响的,而正是这些决策,生态系统中最大的那些分叉是为了触及它们而写的。

这不是一个缺陷。这是问题的形态。它与第 11 章变成放置规则的是同一个区分,与第 42 章在流程和边界之间划出的线也是同一个:用本书始终使用的词来说,是在一个观察决策的机制和一个拥有它的机制之间。

下一章

现在你能叫出这个循环和它的接缝了,这足够你对着它调试,但还不足以让你看过一次运行。下一章启动这个流程,把一个真实任务跑过它,并标出你在第一个小时里会做出的、且在此书余下部分会反复做出的那些决策。如果你已经在运行 Pi,跳到第 11 章,等有什么行为奇怪时再回到这里。

第 2 章:安装、第一次会话,以及第一个任务。