Pi 不只是终端 CLI：4 种把它嵌入应用的方式

📝

Pi 编程 Agent 不只是终端 CLI，提供四层接入路径：SDK（createAgentSession 进程内嵌入）、RPC（跨语言 JSONL 协议）、JSON 模式（一次性事件流）、pi-orchestrator（多实例编排）。从进程内到跨进程到多 Agent 编排，一层比一层向外。

原文来自微信公众号 @tokenbloom（Pi 系列第 12 篇）

Pi 不只是终端 CLI，四条接入路径：

一、SDK：编程式嵌入（同进程）

SDK 在主包里，不用单独装。核心是 createAgentSession()：

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

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

await session.prompt("What files are in the current directory?");

就三步：建会话 → 订阅流式输出 → 发 prompt。AgentSession 的方法与终端操作一一对应：prompt、steer、followUp、setModel、compact、abort、navigateTree。

可定制：模型、工具、自定义工具（customTools）、扩展、技能、prompt 模板、system prompt。会话可 in-memory 或落盘。

二、RPC：跨进程 JSON 协议

如果你用 Python、Go，或要进程隔离，就用 RPC 模式：

1	pi --mode rpc --no-session

协议是 JSONL——每行一个 JSON，LF 换行。你往 stdin 写命令，Pi 往 stdout 吐响应和事件。

命令：prompt、steer、follow_up、abort、new_session、set_model、compact、bash、switch_session、fork 等。

响应：{"type": "response", "command": "prompt", "success": true}

事件（流式推）：agent_start、message_update（流式 token）、tool_execution_*、turn_end、compaction_*——与 SDK 的 subscribe 事件一一对应。

⚠️ JSONL 只认 \n 做分隔符，Node 的 readline 不行（会把 U+2028/U+2029 也当换行）。客户端要自己按 \n 切。

SDK 还是 RPC？

场景	用哪个
同进程、要类型安全、想直接拿 agent 状态	SDK
跨语言（Python/Go…）、要进程隔离、做语言无关客户端	RPC

三、JSON 模式：单次输出事件流

1	pi --mode json "你的 prompt"

跑一次，把所有事件以 JSON 行输出到 stdout，跑完退出。适合接进流水线，一次性拿结果。

四、pi-orchestrator：多实例编排（实验性）

核心是 supervisor（监督者）：spawn 多个 Pi 实例（每个是跑在 RPC 模式的子进程），管它们的生命周期。

const instance = await supervisor.spawnInstance({...});
const instances = supervisor.listInstances();
const response = await supervisor.handleRpc(instanceId, command);
const handle = supervisor.openRpcStream(instanceId, ...);

支持 recoverAfterRestart（崩了能恢复）、shutdown（优雅关停），以及与 Radius 服务的集成。这是 Pi 从「单 agent」往「多 agent 编排」走的一步，目前还是实验性的。

小结

从「进程内调用」→「跨进程接入」→「多 agent 编排」，一层比一层向外——这就是 Pi 作为「可嵌入内核」在接入方式上的体现。