← Pi Agents

SDK 会话

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

你的集成是用 TypeScript 写的。它解析 JSON、重建增量,什么都不必关联,因为压根没有命令。所有那一切工作之所以存在,只是因为一道你自己选择的进程边界。

@earendil-works/pi-coding-agent 直接嵌入 Pi,而 sdk.md 在头两行就给出了建议:进程内的 TypeScript 集成就用 SDK;要一个与语言无关的、或被隔离的子进程,则改用 CLI 集成。本章讲的是这道边界为你买回什么、又收取什么。

谁拥有什么

createAgentSession() 一上手就接管好几样职责,而知道哪一样是你的,对于释放和对于失败处理都要紧。

对象 你创建它吗 拥有 你必须
SessionManager 可选——默认是 SessionManager.create(cwd) 会话文件,以及活动分支 什么都不用,除非你替换它
SettingsManager 可选——默认读取全局与项目设置 生效的设置 什么都不用,除非你覆盖
ResourceLoader 可选——默认是 DefaultResourceLoader 上下文文件、技能、提示词、主题的发现 什么都不用,除非你想要不同的准入(第 28 章)
AgentSession 通过调用 createAgentSession() 智能体、它的工具、扩展、订阅 对它调 dispose()
里面的那个 Agent 从不直接创建 消息、工具执行、循环 什么都不用;会话拥有它

带一项义务的是倒数第二行。dispose() 释放该会话取得的订阅与资源,而在一个长期运行的服务里省掉它,正是你招来一个泄漏的方式——它看起来什么也不是,直到它真的是。

默认做法有两个后果,两个都值得在依赖它们之前知道。一个默认的 SessionManager 会持久化到磁盘,所以一个 SDK 会话会写一个会话文件,除非你传入一个内存中的——与第 32 章里 --no-session 的同一处不对称。而一个被替换的 SessionManager 要求订阅在之后重新绑定;第 5 章那个分支相对的状态,取决于你把顺序弄对。

整个 API,十二行

最小的会话真的就这么小:

import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();

try {
  await session.prompt("What files are in the current directory?");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

createAgentSession() “使用工作目录、被发现的资源、存储的设置和已配置的凭据。"prompt() 在这次运行结束时 resolve,自动重试包括在内。

拿它和前两章比一比。没有 LF 拆分,没有 jq,没有分帧规则,没有一个要监督的进程。事件仍然存在——session.subscribe() 交付它们——但它们以类型化对象的形式到达。

整章用一行说完:那道进程边界就是你要为之付钱的东西,而它也是 SDK 移除的唯一东西。

对移除这个词要小心,因为第 42 章的论证在这里适用。把 Pi 嵌进你的进程,意味着你进程的扩展、凭据、文件和网络访问全都可以被智能体触及——同一个账户、同一批权限、同一块内存。不见了的是不重启你的服务就重启 Pi 的能力,以及给 Pi 一个不同操作系统身份的能力。那是一个真实的运维收益,而它不是一道安全边界。第 32 章是这笔交易的另一面。

在进程内流式输出

const unsubscribe = session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

try {
  await session.prompt("Explain this repository");
} finally {
  unsubscribe();
}

两个有文档记载的细节。在提示之前订阅——sdk.md 直接这么说了,因为一次快的完成可能先到。还要注意线上那一章的担子在这里少了什么:这里的 event.assistantMessageEvent 是 SDK 类型,它携带 JSON 变换所剥去的累积式 partial 快照。那是 SDK 给回的东西里最具体的一件。

生命周期语义没有变,sdk.md 把它们重复了一遍:message_end 包含权威的已完成消息,agent_end 标记一次低层运行的结束,但"自动恢复或排队的工作仍可能跟随”,而 agent_settled 是当宿主需要知道 Pi 不会自动继续时该用的那一个。

整个生命周期在一次交换里,两个参与者之间没有管道、没有分帧:

    sequenceDiagram
  participant H as 宿主进程
  participant S as AgentSession
  participant L as 智能体循环
  H->>S: subscribe(handler)
  H->>S: prompt("...")
  S->>L: 进入活动分支
  L-->>S: message_update 事件
  S-->>H: 带 partial 的类型化事件
  L-->>S: agent_end
  L-->>S: agent_settled
  S-->>H: prompt() resolve
  H->>S: dispose()
  

那次交换里有两件事是 SDK 自己的收益,而不是协议的。prompt() 只有在 Pi 没有任何自动的事了之后才 resolve,所以宿主从不需要挑选一个完成事件;而 message_update 以一个 SDK 对象到达,它仍然携带 JSON 变换所剥去的累积式 partial 快照。

读与写会话状态

AgentSession 暴露 session.messages、session.model、session.thinkingLevel、session.systemPrompt 和 session.getActiveToolNames()。

有一个属性值得仔细读:session.systemPrompt “是只读的,并返回当前生效的系统提示词,包括那些尚未被发给模型的更改。工具更改在下一次请求之前被声明给模型。“它是那个生效的提示词,而不是你配置的那一个——这使它既是一个控制面,也是一个调试工具。有一个限制,在 1.0.4 上已观察:一个由 before_agent_start 处理器(第 18 章)添加的提示词节,在系统消息中以一个具名块的形式到达 provider,而在这次运行之后在这个访问器里不可见,它仍然显示基础提示词。把它当作 Pi 构建的那个提示词,而当你需要知道什么被发出去时,去检查那个请求。

提示有一个 CLI 隐藏起来的规则

这是进程内与进程外之间最尖锐的行为差别,而它是一个 API 决定,而不是一个协议决定。

在会话已经在流式输出时发送的一条提示,必须指定它应当引导当前这次运行还是跟随它。不带着那个选择调用 prompt() 会被拒绝,而不是去猜。

在终端里,Enter 引导而 Alt+Enter 跟随,所以你从不必选择。在 SDK 里你要选,每一次都选。steer() 和 followUp() 直接暴露那两种行为,而两者都"在输入被排队时(包括在一个扩展转换它之后)返回 "queued",在一个扩展消费它时返回 "handled"。”

那个两值返回是一份有文档记载的契约,讲的是扩展行为渗进你的控制流,而它与 RPC prompt 响应用 data.disposition 做出的区分相同。如果你的处理器返回 "handled",那么没有运行开始,也没有什么可等。

prompt() 还处理扩展命令,并在普通用户消息进入智能体之前展开基于文件的提示词模板——与 rpc-commands.md 为 steer 和 follow_up 记录的同一种展开。

还有两个方法:abort() 停止当前操作并等待空闲,而 waitForIdle() 只等待、不中止。

会话存储也是一道边界

SessionManager “拥有被持久化或内存中的条目树,并追踪它的活动叶子。分支改变那个叶子,而不删除被放弃的分支。”

import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
});

那条导致真实 bug 的规则:"SessionManager 对最终定稿的模型上下文是权威的。要恢复外部历史,请用一个包含那些条目的管理器来构造会话。给 session.agent.state.messages 赋值不会替换被持久化的上下文。”

你可以往那个状态里写,而下一个模型请求什么也不会变。那是 SDK 版的"是分支、而不是文件"那一课,用 API 术语陈述出来。

cwd “选定用于项目资源发现、上下文文件、会话分组和内置工具路径的工作区。当目标与 process.cwd() 不同时显式传入它”——在一个服务器进程里,process.cwd() 是服务器被启动的地方,而那几乎从来不是你的本意所在。

session.dispose() “中止活动的工作、使扩展上下文失效、从智能体断开,并移除事件监听器。"sdk.md 里的每一个示例都把它自己的工作包在 try/finally 里,正是因为这个原因。

替换会话

AgentSessionRuntime 增加了 newSession()、switchSession()、fork() 和 importFromJsonl()。每一个都"替换活动的 AgentSession,并为目标工作目录重建服务。”

那个会咬人的后果是:“在一次 runtime 替换之后,订阅属于旧的 AgentSession,必须被重新绑定。”

在一次切换之后重新绑定,否则你的下一条提示会流进一个挂在被丢弃的会话上的监听器——没有任何错误,因为这个订阅在一个不再有任何东西派发经过的对象上仍然活着。

被注入的边界

没有覆盖时,工厂创建一个 ModelRuntime、一个文件支撑的 SettingsManager、一个持久化的 SessionManager、一个 DefaultResourceLoader,以及配置好的默认工具。每一个都可以被显式提供:

  • modelRuntime、model、thinkingLevel、scopedModels——模型访问与选择。
  • settingsManager——合并后的设置,或一个内存中的配置。
  • sessionManager——持久化或内存中的对话历史。
  • resourceLoader——扩展、技能、提示词模板、主题、上下文文件。
  • tools、noTools、excludeTools、customTools——活动的工具集合。

sdk.md 把线划得很清:“当你想要带着若干选定覆盖的标准发现时,用 DefaultResourceLoader。当宿主完全拥有资源存储与发现时,提供一个自定义的 ResourceLoader。“大多数集成想要前者,而太早地去够后者。

与 CLI 的一处不对称

这是今天绊住正在构建 SDK 宿主的人的那个细节:“CLI 会把 codemode、tool_search 和 MCP 作为内置扩展加载。SDK 会话不会。”

要得到它们,你把 createCodemodeExtension()、createToolSearchExtension() 和 createMcpExtension() 加到 extensionFactories。codemode 和 tool_search 被注册为未激活——通过 defaultTools 配 ["+codemode", "+tool_search"] 来启用它们,同时保留其他默认工具,或者让 MCP 扩展激活它们:codemode 给带 codemode 暴露方式的服务器,tool_search 给带 deferred 暴露方式的服务器。

而 MCP 扩展在 session_start 上连接它的服务器,所以你必须调用 session.bindExtensions()。忘了那一点,MCP 工具就干脆永不到达——静悄悄地,因为没有任何东西失败。

反向的那一点是 1.0.4 新增的。DefaultResourceLoader 接受 disabledBuiltinExtensions,一个不加载的内置扩展列表,“即使设置或 -e 启用了它们”,这样一个宿主可以把 mcp 挡在会话之外,而不必要求用户编辑 settings.json。那是 SDK 版的 --no-mcp,而它的组合方式与那个旗标一样:它禁用内置扩展,而不是禁用替换它的扩展。

运行了什么

examples/ch34-sdk/ 用一个脚本化的模型、对着一个真实的 AgentSession 运行这些论断。流式输出和"引导或跟随"规则完全按描述的方式使用 SDK。那些默认凭据的片段(不带参数的 createAgentSession())被标记为有文档记载、未运行,因为它们需要一个真实的 provider。

  • 在提示之前订阅,会把答案作为几个类型化的 text_delta 事件交付,而 getLastAssistantText() 返回整个答案;
  • 在会话流式输出时发送、又没有给出行为的一条提示,会被拒绝。steer() 和 followUp() 都返回 "queued",而这次运行干净地结束;
  • **SessionManager 是权威的。**该测试用一段伪造的历史覆盖 session.agent.state.messages,再次提示,并检查 provider 收到了什么:伪造的文本从未到达,而真实的那条更早的问题到达了。给那个内存中的转录记录赋值,对下一个请求没有任何改变;
  • 一个内存中的会话管理器不写文件;
  • 在 dispose() 之后,一个监听器什么也收不到。

与前一章的对比

JSON 流给你一切,并为解析它向你收费。SDK 给你同样的事件,但是类型化的,外加累积式快照,外加把模型运行时、设置和会话管理器作为你拥有的对象持有的能力。

它的代价:**语言独立性,以及进程隔离。**扩展那一章里关于"在 Pi 进程内以同样的操作系统权限运行"的每一个论断,在这里都以全力适用——在 SDK 里,它字面上就是你的进程。session.dispose() 不是可选的;一个泄漏的会话就是一个泄漏的智能体,带着活着的事件监听器和 provider 连接。

这条进展线的最后一章朝着另一个方向做这笔交易:保留隔离,跨越边界,驱动一个你启动的进程,而不是一个你在其中的进程。

下一章:RPC——一个活着的 Pi 子进程、双向的 JSONL,以及驱动它的那套命令。