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,以及驱动它的那套命令。