Example

用 SDK 会话把一个智能体嵌进你的进程

sdk.test.ts 观察到的五条进程内规则:先订阅、在流式输出时说明引导还是后续跟进,并让 SessionManager 拥有历史。

一个 SDK 会话把智能体移进你自己的 Node.js 或 Bun 进程:createAgentSession() 返回一个类型化的 AgentSession,而那些你曾经从管道里解析出来的事件,以对象的形式到达,它们保留 JSON 流所剥去的累积式 partial 快照。在你的进程内部,终端过去默默处理的规则变成了你要陈述的东西。这里的一切都是已观察的——sdk.test.ts 驱动一个 provider 被脚本化的真实 AgentSession,在 Pi 1.0.4 上。

运行它

使用 Pi 1.0.4 和示例仓库的测试运行器。规范文件是 examples/ch34-sdk/sdk.test.ts:它通过共享的测试骨架构建一个真实的 AgentSession,用 faux provider 脚本化模型,并对下面五条规则做出断言。没有什么要配置的,因为模型是脚本化的。

这条流的形状是示意性的(不是一个规范文件):在提示之前订阅,因为一次快的完成可能先到:

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

进程内的生命周期

阶段 会发生什么 为什么它要紧
subscribe() 在提示之前挂上 一次快的完成可能先到
prompt() 只在这次运行结束时 resolve,重试包括在内 宿主从不需要挑选一个完成事件
流式输出中的 message_update 携带累积式 partial 快照的类型化对象 JSON 变换所剥去的那个细节
steer() / followUp() 流式输出期间排队输入的唯一合法方式 两者都不带的 prompt() 会被拒绝
dispose() 中止工作、移除监听器、停止交付 省掉它就会泄漏这个智能体

预期结果

sdk.test.ts 的断言 测试观察到什么
类型化的增量到达 增量拼成整个答案,不止一个增量,而 getLastAssistantText() 返回它
流式输出期间的引导或后续跟进 一个光秃秃的 prompt() 被拒绝;steer() 和 followUp() 都返回 "queued",而这次运行干净地结束
SessionManager 是权威的 一个伪造的 agent.state.messages 从未到达 provider;真实的那条更早的问题到达了
内存中的管理器 getSessionFile() 是 undefined——没有文件被写出
dispose() 一个监听器在释放之后什么也收不到

机制与局限

有文档记载:sdk.md(1.0.4)规定了 createAgentSession()、在提示之前订阅、steer() 和 followUp() 的 "queued" / "handled" 返回、SessionManager 作为被持久化或内存中的条目树的拥有者(给 session.agent.state.messages 赋值不会替换那个上下文),以及 dispose() 释放智能体的订阅。已观察:sdk.test.ts 对着一个真实的 AgentSession 对上面全部五行做出断言。本章那个不带参数的 createAgentSession() 是有文档记载、未运行的:它需要一个真实的 provider,而它的默认 SessionManager 会写一个会话文件,除非你传入 SessionManager.inMemory()。

这些增量是脚本化的,所以这展示的是事件的管路,而不是一个真实模型的行为。嵌入 Pi 不是一道安全边界:你进程的扩展、凭据、文件和网络就是智能体的,而重启 Pi 意味着重启你的服务。它也没有展示那处不对称,即 SDK 会话不像 CLI 那样把 codemode、tool_search 或 MCP 作为内置扩展加载。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.