Pi Agents cover
Programmer.ie 图书 In development

Pi Agents

一本关于为智能体行为找到正确层次的实践之书,以 Pi 为工具去看清并亲手构建每一层:从一次直接的模型调用,穿过智能体内核与编码智能体宿主,直到界面与权限边界——始终从能够解决问题的最弱机制做起。

浏览示例 →

大多数人写智能体的方式就是写提示词。这种方式一直有效,直到某个时刻它不再有效:提示词越来越长,指令之间开始互相矛盾,同一个任务周二还好好的,周四却失败了,而没人说得出原因。

Pi 采取了另一种立场。智能体不是一场恰好正在进行的对话,它是一个程序,并且有一组有文档记载的挂接点。有用于持久化指令的机制。有用于复用提示词的机制。有用于打包指令与文件的机制。有运行在智能体自身进程内的可执行工具与事件处理器机制。后者一个比一个强大,也一个比一个代价更高——无论是在审查面上、在信任上,还是在一次失误可能造成的破坏上。

这本书讲的就是在这架梯子上做出正确选择,然后在你选定的那一级上好好构建。

能够解决这个问题的、最弱的 Pi 机制是什么?

在它之下还贯穿着第二个问题,六个部分会不断回到它——不是哪个机制,而是哪个层次。第 11 章把两条规则放在一起讲,因为它们本是同一门学科的两个粒度:

使用能够满足需求的最弱机制——并把它放进真正拥有该需求的最窄层次中。

第 1 章和第 11 章把这一点落实在 Pi 真实的包依赖图上,并且明确指出了它在哪里不成立:智能体循环是一个可以单独嵌入的层次,但压缩(compaction)、会话准入(session admission)与基础提示词组装没有公开的接缝,而生态系统中最大的那些分叉正是由此而来。

本书构建什么

六个部分、四十二章、两个附录,以及这个准备页。第一部分刻意缓慢:它解释 Pi 实际做了什么,因为一个不知道上下文是如何组装的扩展作者,会写出一个与系统对抗的扩展,并且无法判断 bug 是自己的还是 Pi 的。第二部分按力量递增的顺序介绍各个构件。第三部分处理对话超出窗口之后你需要引导它、检查它或恢复它时发生的事。第四部分用五种方式驱动同一个智能体,而不改变它本身。第五部分下潜到编码智能体之下,直接在模型层与智能体内核之上构建。第六部分追问这一切究竟被允许做什么。

按依赖方向排列的各层:

application / host        智能体的用途所在;权限所在之处
agent application         会话、压缩策略、扩展、工作流      (pi-coding-agent)
agent core                循环、消息、状态、工具执行、事件  (pi-agent-core)
model / provider access   对某一个模型发出一次请求          (pi-ai)
provider                  Anthropic、OpenAI、一个本地服务器

智能体位于模型层之上、赋予它目的的应用之下。本书的主张是:关于智能体的大多数错误,都是关于哪个层次拥有某项决策的错误;而 Pi 之所以有用,是因为它让你能分别看见并构建每一层。

第一部分:智能体循环(第 1 至 10 章)。 *Pi 是什么,以及你在针对什么编程。*每个扩展都会挂接到的那 个循环,安装与第一个任务,模型与思考级别(thinking level),作为预算而非容器的上下文窗口,会话存放在哪里,内置工具,配置从哪里来以及按什么顺序生效,项目 .pi 目录以及摆在前面的信任决策,Pi 实际调用的那个 shell,以及如何写出一个智能体能完成的任务。

第二部分:四个构件(第 11 至 22 章)。 *你如何改变 Pi。*第 11 章是决策章,它之后的一切都假定你已经做出了这个决策。然后是提示词模板及其参数替换;技能(skill)及其基于描述的路由(routing);携带脚本、参考资料与资源的技能;你的第一个扩展;生命周期与事件契约;深入讲解工具,包括暴露方式与嵌套调用;改变模型所知的内容;状态放在哪里,以及为什么四种存储选择不可互换;斜杠命令与终端 UI;MCP;以及把成果作为包发布。

第三部分:长会话与控制(第 23 至 30 章)。 *对话变大时会发生什么。*压缩,以及摘要保留与不保留什么;在一棵树而非一条列表上分支与分叉;对进行中的工作进行引导、排队与中止;整个系统所构建于其上的消息类型;磁盘上的会话文件格式;上下文准入,即由谁决定哪些指令能到达模型;失败、重试与恢复;以及按层次调试。

第四部分:Pi 作为程序(第 31 至 35 章)。 *当界面不是智能体时。*为什么终端只是某一个智能体的某一个驱动;通过 print 与 JSON 模式进行无头操作;JSONL 事件流,以及如何从中重建状态;在进程内创建会话的 TypeScript SDK;以及通过 RPC 驱动一个运行中的 Pi。

第五部分:在编码智能体之下构建(第 36 至 41 章)。 *使用构建 Pi 所用的那些层。*每一层一步一章,配一个贯穿始终的示例、一个断言检查器,以及真正能跑的代码:一次返回类型化值的模型调用;单独运行的智能体内核;作为类型化函数的随机一步;内核上的各种钩子,以及每一个还能改变哪些决策;在不把一切都变成智能体的前提下组合操作;以及测试包含模型的软件。

第六部分:权限(第 42 章)。 *这一切可以做什么。*一章收尾,把信任、许可、工具注解与隔离收拢成对某个问题的回答——这个问题读者从第 1 章起就该一直在问:究竟是什么让一个智能体值得被构建?

**附录。**A:参考资料与延伸阅读。B:详细讲解终端界面,面向正在构建终端组件的读者。

这本书真正要做的决策

Pi 的快速上手告诉你从能满足你需求的最弱机制开始,然后给出这架梯子:

AGENTS.md        一个目录的持久化指令
prompt template  从 / 菜单中复用一条提示词
skill            面向特定任务的指令加上支撑文件
extension        可执行的工具、命令或事件处理器
terminal UI      终端里的一个自定义组件
custom provider  一个不受支持的模型服务
package          一次性安装或分发多个资源

第 11 章把它变成一套流程,本书其余部分都假定你是刻意爬上来的。原因不是优雅。提示词模板是一个文件,审阅者可以在 diff 里读完它。扩展则是在智能体进程内运行的 TypeScript,拥有启动它的那个用户的操作系统权限,能够检查提示词、工具调用、文件、凭据与会话历史。两者都正当。但它们不是同一种承诺,而这种差别在要紧之前是看不见的。

本书做的是哪一类论断

三类,行文中始终分开。

Documented(有文档记载)指 Pi 的文档或其导出的类型声明所陈述的内容。本书对这类内容直接断言,并指出对应的文档主题。Observed(已观察)指被运行并记录下来的行为,并注明了版本。Proposed(本书提出)指属于本书而不属于 Pi 的模式——一种组织扩展的合理方式、一种技能目录的形态——并且始终明确标示。

第五部分以及第 1、28、31 章中的代码,都不是凭记忆粘贴的。它存放在 examples/ 目录中,锁定在本书所声明的 Pi 版本上,并且有一个脚本检查你读到的内容就是被运行过的内容。运行本书的示例 提供了仓库、锁定的修订号,以及验证命令——并且明确指出:一套全绿的测试是关于模型周围代码的证据,从来不是关于模型的证据。

这种区分就是本书的方法。大多数关于智能体的文章出错,不是因为技术错了,而是因为一个碰巧有效的模式被写成了仿佛是框架保证的那样。当本书推荐某个 Pi 并不要求的东西时,它会说出来。

本书面向谁

你已经会用这个智能体,并希望它可靠地做好一件特定的事。你对 TypeScript 的熟悉程度足以读懂一条事件声明。你更愿意理解机制而不是照抄片段,并且想知道你构建的东西中哪些部分依赖于有文档记载的契约、哪些是你自己的判断。

不需要预先具备 Pi 经验。第一部分与第三部分不读 TypeScript 也能看懂。第二部分假定你能读懂一个异步工厂函数和一个 schema 对象。

找到你的问题

多数读者带着症状而不是计划而来。这张表从症状出发。第 42 章的收尾表格是基础——它把一个需求映射到一个机制——但你不应该非得读到全书末尾,才能找到哪一章负责你的问题。

你看到的现象 章节 该看什么
我的技能从来没有加载过 13 描述就是路由文本,缺少描述意味着技能根本不会加载——而且是静默的
我的技能加载了但什么也没做 14 打包的文件是磁盘上的文件。只有当模型用自己的工具读它时,它才进入上下文
打包的脚本在错误的目录下运行 14 向环境询问目标仓库,而不是去数父目录的层数
模型无视我告诉它的话 18 指令不是权限。先检查那一节、那个技能或那个上下文文件到底有没有被准入
我的命令在 RPC 中卡住 35 有东西在等一个响应。disposition 会说明一次运行是否真的开始了
我的命令在 --print 下什么也不做 32 没有可以用来询问的 UI,而且 print 是通过退出码而不是流来报告失败
会话里有一条模型看不见的消息 27,然后是 30 已存储、已投影与已发送是三件不同的事。get_messages 是第二件,不是第三件
上下文窗口溢出了 29 在责怪模型之前,先检查 stopReason 和溢出恢复事件
有东西运行了,而我说不出是哪一层做的 30 把你怀疑的下面那一层换掉。症状还在吗?
模型调用了一个我没有启用的工具 17 注册不是激活。getAllTools() 不是 getActiveTools()
我的扩展的处理器从未触发 16 注册顺序,以及哪些事件只是通知、哪些会做转换
我想先停下来的效果还是发生了 39 beforeToolCall 是唯一一个声明了拒绝能力的钩子。效果发生之后就无法挽回了
这个需求该用哪个机制? 11,然后是 42 最弱的机制;拥有它的最窄层次
智能体能够碰到它不该碰的东西 42 四级台阶,从指令到宿主遏制。可用性不等于同意
我想从模型那里拿回一个类型化的值 36 一次请求,一个 schema,不需要循环
一次模型调用无法产出值 38 这一步必须以 submit 结束。边界与失败种类是本书提出的模式
我的测试套件全绿,智能体却仍然失败 41 脚本化的 provider 证明的是你的代码,从来不是模型。第三级是另一回事
我想运行本书展示的代码 运行本书的示例 锁定的安装方式、前置条件,以及一次全绿运行能证明什么

怎么读它

如果你来这儿是为了构建一样东西,先读第 11 章,让它把你送往你需要的章节。如果你想构建完全不依赖编码智能体的智能体行为,读第 1 章,然后直奔第五部分。如果你在写扩展,按顺序读第一部分——正是这一部分能避免你的 bug 变得含义不明。如果你要把 Pi 嵌入到一条流水线中,去看第四部分,但要略读第三部分,因为会话格式正是你凌晨两点要调试的东西。

目录

章节

01

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

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

02

安装、首次会话与第一个任务

把 Pi 跑起来,并交给它一件真正的事:安装、工作文件夹、身份验证、第一个任务,以及当结果不是你想要的样子时该怎么办。

03

模型与思考级别

智能体跑在哪个模型上、它思考得多用力、凭据如何解析,以及为什么一个模型选择可以解释一个你归因于自己代码的行为。

04

上下文窗口是一个预算

Pi 每一轮发给模型什么、触发压缩(compaction)的算术,以及如何针对你的模型调整 reserveTokens 与 keepRecentTokens。

05

会话,以及它们住在哪里

会话文件是以 id 与 parentId 为键的只追加 JSONL 树;这里讲怎么读一个、怎么恢复它、怎么分叉它,以及怎么控制它存在哪里。

06

内置工具

八个内置的 Pi 工具、defaultTools 实际选的是什么、工具结果如何到达转录记录,以及何时加上 codemode。

07

设置,以及配置来自哪里

Pi 会合并智能体目录与项目 .pi 两个设置文件:标量值被覆盖,资源列表取并集,而环境变量和命令行标志是按设置逐项记录的,并不是两个更高的层。

08

项目 .pi 目录与信任

哪些项目资源 Pi 只在授予信任之后才加载,以及哪些上下文文件无论信任决策如何都会加载。

09

Shell、进程与环境变量

Pi 每条 shell 命令都会用一个全新的非交互式 shell 来运行,所以别名和 shell rc 文件都不在场,除非你配置 shellPath 和 shellCommandPrefix。

10

写出一个 Pi 能完成的任务

Pi 不会在工具调用之前提问,所以任务的陈述必须自带范围、验收检查,以及文件;下面给出一种行得通的形状。

11

改变 Pi 的四种方式

一套用于在上下文文件、提示词模板、技能与扩展之间做出选择的决策流程,配有四个推演案例,以及一个贯穿本部分余下各章的一贯示例。

12

提示词模板

提示词模板把 Markdown 文件变成带 shell 风格参数替换的斜杠命令;这里是 frontmatter、替换表,以及模板从哪里加载。

13

技能

Pi 按名称和描述通告每一个技能,并按需加载它的完整指令;这里讲的是如何写出让路由(routing)生效的描述。

14

运行本书的示例

拿到本书所运行的代码,安装锁定的 Pi 发布版,验证章节与代码一致,并弄清由此得到的证据能证明什么、又不能证明什么。

14

携带文件的技能

`SKILL.md` 可以用相对路径引用脚本、参考资料和资源;这里是目录布局、路径约定,以及如何把整个目录作为包分发。

15

你的第一个扩展

扩展(extension)是一个默认导出接收 ExtensionAPI 的 TypeScript 模块;这里给出能工作的最小工具、它如何被加载,以及工厂函数的生命周期规则。

16

事件与扩展生命周期

Pi 按注册顺序把具名事件分派给处理器;这里讲一次运行的生命周期、每个事件可以返回什么,以及一个建立在 tool_call 上的强制推送守卫。

17

深入讲解工具

一个工具声明一个名字、一段描述、一个 schema 和一个 execute();本章讲暴露方式、注解、结构化输出、terminate 和嵌套调用。

18

改变 Pi 所知的内容

有四个界面改变模型的输入——SYSTEM.md、APPEND_SYSTEM.md、before_agent_start 的各个节,以及 context 事件——它们各有不同的生命周期与代价。

19

扩展状态与持久化

一个扩展把状态放在哪里,才能让它在重载、恢复和分叉之后活下来,以及为什么答案几乎总是一条会话条目,而不是一个模块变量。

20

斜杠命令与自定义 UI

一个扩展如何添加一条 / 命令并渲染自己的屏幕,以及那些决定这块屏幕究竟是否存在的模式规则。

21

MCP 服务器

通过 stdio 和 HTTP 连接 Model Context Protocol 服务器,控制它们的工具如何到达模型,以及一个许可扩展能从它们那里了解到什么、了解不到什么。

22

包:交付一个智能体

一个 Pi 包如何把一个扩展连同它的技能、提示词和主题作为一个可安装单元携带,以及哪些依赖绝不应该被打包。

23

压缩

Pi 如何判断上下文窗口什么时候满了、它用什么替换成摘要、什么会原封不动地保留下来,以及一个扩展可以在哪里接管摘要的生成。

24

分支与分叉

三种回到过去的方式——/tree、/fork 和 /clone——以及当一次错误的转向该留在会话里还是变成独立的工作时,该如何选择。

25

引导、排队与改变方向

当你在 Pi 工作时键入消息会发生什么——引导消息在当前轮次之后进入,后续跟进消息等待一次运行结束,而 Escape 会把队列还给你。

26

消息类型

AgentMessage 覆盖的八种角色、它们共用的内容块,以及哪些字段才是权威的——包括那个会绊倒每个人的时间戳类型。

27

会话文件格式

一行一个 JSON 对象、一棵条目树,以及那次三遍遍历——它把一个被存储的会话变成一次模型请求恰好包含的那些消息。

28

上下文准入是应用策略

一个文件存在、被发现、被准入和到达模型是四个不同的事实;本章把它们分开,展示哪些是 Pi 的规则、哪些属于应用,并实际运行那些发现规则。

29

失败、重试与恢复

对一次失败请求的三种不同回应——重试它、修复上下文后重试一次、或者停下来——以及把它们区分开来的那些设置与事件。

30

按层调试

智能体里的一次失败是某一层里的一次失败,而要找出是哪一层,最快的办法是替换它下面那一层,看症状是否存留;本章把每一层与它的症状和它的仪器配对。

31

界面不是智能体

终端、print 模式、JSON 流、RPC 和 SDK 是驱动同一个智能体的五种方式;换界面后仍存留的东西,是智能体自成一层的证据,而存留不了的东西,是给扩展的设计规则。

32

无头 Pi

在没有人附着的情况下运行 Pi——print 与 JSON 模式、模式如何被选定、没有终端时什么还能活下来,以及每种模式的代价与给予。

33

JSON 事件流

Pi 的 JSONL 事件的线上参考——严格的 LF 分帧、事件词汇表,以及把增量变回权威消息的那条重建规则。

34

SDK 会话

把 Pi 嵌进一个 Node.js 或 Bun 进程——createAgentSession、被注入的边界、会话替换,以及让一个进程内智能体守规矩的那些规则。

35

RPC

通过 JSONL 驱动一个运行中的 Pi 子进程——四种记录族、按 ID 相互关联的命令、一个扩展 UI 子协议,以及关闭约定。

36

没有编码智能体的模型访问

一个应用从模型那里需要的大多数东西是一次调用,而不是一个智能体:本章直接使用 pi-ai,从一次模型调用拿到一个类型化的结果,没有循环、没有会话、没有终端。

37

单独运行的智能体内核

pi-agent-core 的 Agent 类是去掉了编码智能体的 Pi 循环:本章带着一个工具、以智能体的形式运行这个论断核查任务,并精确展示宿主本来在提供什么。

38

随机一步是一个类型化函数

智能体循环自己决定它何时结束;类型化步骤把那个决定拿走,办法是让唯一的出口成为一次必须匹配 schema 的调用,然后再把各步骤当作普通函数串起来。

39

接缝、钩子与不可逆转的决定

智能体内核上的每一个钩子都能看见某些东西;只有一些能改变它,更少的能拒绝它。本章按每个钩子在触发时还能决定什么来映射它们,是测量得出的,而不是假设的。

40

组合智能体操作

一条流水线不是一队智能体:本章把一个函数、一次模型调用、一次检查和一个智能体组合成一条论断检查流水线,并且只在便宜的部分无法决定时才花掉那个昂贵的部分。

41

测试随机软件

单元测试、结构化测试和评估,回答关于包含模型的代码的三个不同问题;本章针对那个论断检查器把三者都构建出来,并展示为什么平均成功率掩盖了要紧的那个数字。

42

权限、隔离,以及什么让一个智能体值得被构建

收尾的论证:能力不是权限;一道边界必须及时行动,并且位于它所约束之物的触及范围之外;由被检查方选定的值不能充当检查的闸门;以及每个需求属于从指令到宿主遏制这四级台阶中的哪一级。

A

附录 A — 参考资料与延伸阅读

本书背后的来源:Pi 自己的文档、已发表的关于智能体循环、界面、上下文与安全的研究、演示了特定设计的生态项目,以及把这些追问推进得更远的伴生书。

B

附录 B — 终端界面详解

面向终端 UI 作为一个分层系统的参考资料:上报协议、pi-tui 组件模型、键位绑定、主题,以及逐终端的修复。从主线中移出,因为它描述的是界面,而不是智能体。