Pi Agent 源码级教程
APX

附录 C —— 把 Agent 装进你的服务

3,428 字 · 含 220 行代码 · 约 19 分钟

Part A–D 讲的是「里面怎么转」。这一页讲另一件事:怎么把它装进一个 能对外服务的进程,让浏览器、Java、Python 都能用。

只走一条路:进程内 SDK 加一个 HTTP 接口,响应是 SSE 流。 不走的路也说清楚——RPC 为什么这次没用、多用户会话隔离为什么本书不写。

这一页的代码全部实跑过,跑不了的会写「未实跑」并说明原因。 实测环境:node v24.12.0、Pi 1.4.0、Windows 24H2。


一、四种跑法,先选一种

Pi 有四种被驱动的方式。翻 main.ts:112-123 的 resolveAppMode, 分支就三行:

ts
function resolveAppMode(parsed: Args, stdinIsTTY: boolean,	stdoutIsTTY: boolean): AppMode {	if (parsed.mode === "rpc") {		return "rpc";	}	if (parsed.mode === "json") {		return "json";	}	if (parsed.print || !stdinIsTTY || !stdoutIsTTY) {		return "print";	}	return "interactive";}

stdout 被重定向就自动降级成 print——所以管道里跑 pi "问题" 不会 卡在 TUI 里等输入。四种跑法对照:

跑法 怎么起 谁能用 事件粒度
交互 TUI pi 人 渲染层内部消费
打印 pi -p "…" / --mode json 任何语言起子进程 只有最终结果
RPC pi --mode rpc 任何能读写 JSON 的语言 全部事件
进程内 SDK createAgentSession() 只有 Node 全部事件

RPC 的定位写在文件头(rpc-mode.ts:1-11):

ts
/** * RPC mode: Headless operation with JSON stdin/stdout protocol. * * Used for embedding the agent in other applications. * Receives commands as JSON on stdin, outputs events and * responses as JSON on stdout. * ...

它的取舍很清楚:多一个进程,换崩溃隔离。进程挂了不影响宿主, 代价是所有事件要序列化一遍过管道——AgentSessionEvent 里带 Message, 有图片时一条事件能到几百 KB。

SDK 没有进程边界,事件是内存里的对象,直接读字段。代价是 Agent 崩了 就是你的进程崩了(第七节坑 4 会演示一次)。

本书选 SDK,因为下面要讲的 subscribe 只在同进程里有意义。

这一节和 M07 的「扩展层 vs 订阅层」是同一件事的两面:pi.on 是 扩展里注册的钩子(extensions/types.ts 一族),session.subscribe 是宿主进程的监听器。服务端用后者。

五个入口什么时候选哪个(-p 的退出码、JSON 的 stopReason、RPC 的 disposition、SDK 怎么换边界),在 F09;这一页只走 SDK + HTTP 这一条。


二、前置条件:先有凭据

createAgentSession() 允许零参数调用,但不允许零配置跑起来。 两道闸门:

第一道,找模型。 sdk.ts:236-251 调 findInitialModel,依次看 settings 里的默认值、各 provider 的默认模型。都找不到时把原因写进 modelFallbackMessage(sdk.ts:247 的 formatNoModelsAvailableMessage)。

第二道,发消息前验 auth。 agent-session.ts:2174-2191:

ts
if (!this.model) {	throw new Error(formatNoModelSelectedMessage());}const hasConfiguredAuth =	this._modelRuntime.hasConfiguredAuth(this.model.provider) ||	(await this._modelRuntime.checkAuth(this.model.provider))		!== undefined;

凭据默认从 ~/.pi/agent/auth.json 读(sdk.ts:196-198 用 agentDir 拼出来)。 这和 M01 §8.2 那条快速路用的是同一份。

本机实测(createAgentSession() 零参数,只打两个字段):

text
model      : doubaoprovider   : (本机 provider 配置)fallback   : (none)

fallback 是 (none),说明第一道闸门过了。

未实跑:把 auth.json 挪走会怎样。按 :2174-2191 读, model 会是 undefined,prompt() 抛 No model selected; 若模型在但 key 没了,抛 No API key found for provider …(:2190)。

所以这一页的所有示例,先决条件分两档——走哪一档取决于你手上有没有 key:

档 前提 能验证什么 验证不了什么
有 key(默认路线) 已跑通 M01 §8.2,~/.pi/agent/auth.json 在 全链:模型调用、SSE 转发、工具运行 —
没 key(降级档) 只需 node;把 streamFn 换成固定假回复 HTTP 层:路由、SSE 帧格式、断开、错误事件 模型真实输出与 token 数

降级档的写法抄 M03 §十二:给 createAgentSession() 传一个自己写的 streamFn,它 yield 几个固定事件(message_start / 若干 text_delta / message_end)就返回。判据从"模型回了什么"变成 "浏览器收到了几帧、顺序对不对"——这一页要验的正是后者。 没 key 时别停在第三步:第三到六步只依赖 HTTP 层。


三、十行嵌入

最短能跑的形状:

ts
// 本页示例,实跑于 v1.4.0import { createAgentSession, SessionManager } from	"@earendil-works/pi-coding-agent";const { session } = await createAgentSession({	sessionManager: SessionManager.inMemory(),});const off = session.subscribe((e) => handle(e));await session.prompt("用 ls 看当前目录");off();session.dispose();

五个 API,各自的位置和返回值:

调用 位置 返回
createAgentSession(opts) sdk.ts:191 { session, extensionsResult, modelFallbackMessage? }
SessionManager.inMemory() session-manager.ts:1814 不落盘的会话存储
session.subscribe(fn) agent-session.ts:1404 注销函数,不是 session
session.prompt(text) agent-session.ts:2113 Promise,整轮结束才 resolve
session.dispose() agent-session.ts:1428 void

三个容易踩的点:

inMemory() 不是「什么都不做」。 不传时走 SessionManager.create (sdk.ts:201),消息会以 JSONL 落到 ~/.pi/agent/sessions/ 下。 服务端每个请求建一个 session 又不清理,几天就是几万个文件。 inMemory() 的 cwd 默认是 process.cwd()(session-manager.ts:1814)。

subscribe 返回的是函数。 拿它当 session 用是最常见的笔误:

ts
const off = session.subscribe(...);   // 对const s2 = session.subscribe(...);    // s2 是函数,不是 session

prompt() 的 Promise 覆盖整轮,不只是首 token。 模型调工具、 工具跑完、再调模型,这一整套都在同一个 Promise 里。

实测同一段代码(只把 handle 换成打类型名):

text
model      : doubaofallback   : (none)unsubscribe: functionprompt ms  : 7849messages   : 5dispose ok : 11126 ms total

11.1 秒里 7.8 秒在 prompt,剩下 3.3 秒在建会话—— DefaultResourceLoader 要扫项目目录、读 settings、加载扩展 (sdk.ts:203-207)。这就是「一个进程建一次 session,而不是一个请求 建一次」的量化理由。

dispose() 之后这个 session 就废了:扩展 ctx 被标成 stale、监听器数组 清空(agent-session.ts:1439-1443)。要新会话,重新 createAgentSession。


四、第二轮:会话怎么续

同一个 session 连着 prompt 两次,就是多轮对话。不用你拼历史——历史在 session 里。实测(同一 session,两次 prompt):

text
第 1 轮后 messages = 3第 2 轮后 messages = 5最后一条 role = assistant | stop = stop文本 = "42"            ← 它记得上一轮

3 是 system + user + assistant;第二轮又加 2 条。每轮只增两条, 但每次请求发的是全量。

用量在 message.usage。实测第二轮那条:

text
{"input":8569,"output":2,"cacheRead":0,"cacheWrite":0, "reasoning":0,"totalTokens":8571, "cost":{"input":0,"output":0,"total":0,         "totalFromProvider":false}}

输入 8,569 个 token,输出 2 个。system prompt 就有 8.5k——回复 「42」这两个字的成本,绝大部分花在重复发送同一份提示词上。M08 讲的那条 目录链之所以值得读,理由就在这个数字里。

cost 全是 0 是因为本机 provider 没配价格表(注意 totalFromProvider 是 false),不是免费。服务端要计费就从 usage 取,别自己数字符。

session.state 还能读到的(agent-session.ts:1461 的 get state, 类型在 packages/agent/src/types.ts:382):messages、model、 thinkingLevel、isStreaming。前端要显示「正在回答」的转圈, 就读 state.isStreaming,不用自己维护标志。

会话越滚越长怎么办,是 M09 的事(两道闸门、两种摘要);这一页不展开。


五、subscribe 能拿到什么

这一节是整页的骨架。表里的「实测键」是把 Object.keys(e) 打出来的结果, 不是从类型定义抄的。

事件 实测键 什么时候发
message_start type,message 一条消息进入 transcript
message_end type,message 同一条消息结束
message_update type,message,assistantMessageEvent 流式增量
tool_execution_start type,toolCallId,toolName,args 工具开始
tool_execution_update — 工具流式输出
tool_execution_end type,toolCallId,toolName,result,isError,durationMs 工具结束
agent_end type,messages,willRetry 一轮循环结束
agent_settled type,aborted 彻底结束

完整事件类型在 agent-session.ts:209-250,是 AgentEvent 的扩展: agent_end 被换掉(多了 willRetry),另加了 agent_settled、 queue_update、compaction_* 等(:211-250)。

四个要点,每个都有实测痕迹。

1. message_start 不只属于用户

一轮真实对话的骨架(实测,字段是原样打印):

text
message_end     role=system stop=-message_end     role=user stop=-message_end     role=assistant stop=toolUsetool_start      keys=type,toolCallId,toolName,args                toolName=bash args={"command":"ls -la"}tool_end        keys=type,toolCallId,toolName,result,                     isError,durationMs                toolName=bash isError=false                result.content[0]={"type":"text","text":"total 371…"}message_end     role=toolResult stop=-message_end     role=assistant stop=stopagent_end       willRetry=false messages=5agent_settled   aborted=false

第一条是 system。如果你按「一条 message 一个气泡」渲染,页面上 第一个气泡会是系统提示词。handler 里要按 role 过滤。

stopReason 只有 assistant 有值:toolUse 表示这条要调工具, stop 表示说完了。用它切分「第几段回答」比数字段靠谱。

2. tool_execution_end 带 durationMs

M05 讲工具时还没有这个字段的用处,服务端就有用了——显示「耗时 1.2s」 不用自己掐表。载荷在 agent-loop.ts:931 附近,start 在 :495、 :553、:608 三处(普通调用、并发调用、另一条分支各一个发射点)。

result 的形状就是工具返回的 AgentToolResult,文字在 result.content[0].text。

3. 增量藏在 assistantMessageEvent 里

message_update 的事件体是 packages/agent/src/types.ts:538:

ts
| { type: "message_update"; message: AgentMessage;    assistantMessageEvent: AssistantMessageEvent }

外层的 type 恒为 message_update,真正区分内容的是 e.assistantMessageEvent.type:"text_delta" 或 "thinking_delta", 文本在 .delta。

实测另一次:text_delta 出现 146 次,thinking_delta 0 次 (那一轮模型没开 thinking)。把 delta 按到达顺序拼接, 就是完整的回答。

4. 一轮到底发多少事件

实测一次带两次工具调用的对话(每轮都不一样,以下是那一次的计数):

text
total=66agent_start=1          turn_start=3message_start=7        message_end=7message_update=37      tool_execution_start=2tool_execution_end=2   tool_execution_update=2turn_end=3             agent_end=1        agent_settled=1

66 个事件里 37 个是增量。转发时用白名单,别原样丢给浏览器: entry_appended、queue_update、compaction_* 前端根本不显示, 传过去只是浪费带宽和前端的事件处理分支。


六、四十行服务

用 node:http,不引 Express。理由不是「轻量」,是仓库的依赖里没有它 (packages/coding-agent/package.json 的 dependencies 里没有 express), 示例引一个装不上的包,等于跑不起来。

ts
// 实跑于 v1.4.0,node v24.12.0import { createServer } from "node:http";import { createAgentSession, SessionManager } from	"@earendil-works/pi-coding-agent";const { session } = await createAgentSession({	sessionManager: SessionManager.inMemory(),});let busy = false;const server = createServer(async (req, res) => {	if (req.method !== "POST" || req.url !== "/chat") {		res.writeHead(404).end();		return;	}	if (busy) {		res.writeHead(429, { "content-type": "application/json" })			.end('{"error":"busy"}');		return;	}	busy = true;	let body = "";	for await (const chunk of req) body += chunk;	let message: string;	try {		message = JSON.parse(body || "{}").message ?? "";	} catch {		res.writeHead(400, { "content-type": "application/json" })			.end('{"error":"bad json"}');		busy = false;		return;	}	res.writeHead(200, {		"Content-Type": "text/event-stream",		"Cache-Control": "no-cache",		Connection: "keep-alive",	});	const send = (type: string, data: unknown) =>		res.write(`event: ${type}\ndata: ${JSON.stringify(data)}\n\n`);	let settled = false;	const off = session.subscribe((e: any) => {		if (e.type === "message_update") {			const a = e.assistantMessageEvent;			if (a.type === "text_delta") {				send("text", { delta: a.delta });			} else if (a.type === "thinking_delta") {				send("thinking", { delta: a.delta });			}			return;		}		if (e.type === "tool_execution_start") {			send("tool_start", {				id: e.toolCallId,				name: e.toolName,				args: e.args,			});		} else if (e.type === "tool_execution_end") {			send("tool_end", {				id: e.toolCallId,				name: e.toolName,				isError: e.isError,			});		}	});	res.on("close", () => {		off();		if (!settled) void session.abort();	});	try {		await session.prompt(message);		settled = true;		send("done", {});	} catch (err) {		settled = true;		send("error", { message: (err as Error).message });	} finally {		off();		res.end();		busy = false;	}});server.listen(3123);

四处值得指出来:

res.on("close") 不是 req.on("close")。 要监听的是响应连接。 req 的 close 在请求体读完时就会触发,那时 Agent 才刚开始跑。

settled 防的是正常结束后的补偿 abort。 没有它,done 发完、 res.end() 之后 close 事件仍会到,session.abort() 会把一个已经 结束的跑动再中止一次。

off() 调了两遍是安全的。 subscribe 返回的注销函数用 indexOf + splice(agent-session.ts:1408-1413),找不到就什么也不做。

abort() 会让 prompt() 抛错。 agent-session.ts:2519 的 abort() 最终调到 agent.abort()(:2527),正在跑的 prompt 以异常 收场。所以 catch 里必须发 error——否则前端连接还在,却永远等不到 done。

请求一次

bash
curl -sN -X POST http://127.0.0.1:3123/chat \  -H "Content-Type: application/json" \  -d '{"message":"list files with ls"}'

真实输出(截前四帧和末尾):

text
event: tool_startdata: {"id":"call_wq32dwjhjasv78zqfi66y65r","name":"bash","args":{"command":"ls -1"}}event: tool_enddata: {"id":"call_wq32dwjhjasv78zqfi66y65r","name":"bash","isError":false}event: textdata: {"delta":"AG"}event: textdata: {"delta":"ENTS"}…event: donedata: {}

-N 关掉 curl 自己的缓冲,否则你会等到全部结束才一次性看到。 上面 data 我只是为排版折了行,实际是一行。

前端那一侧

fetch + getReader(),按 \n\n 切帧。实测(node 24 跑同一套读法):

text
状态: 200 text/event-stream帧数: 4首帧: 2639ms text | 末帧: 2819ms done拼接文本: 你好。text_delta 段数: 3

一句话「你好。」被切成 3 段,首帧在 2.6 秒到达。这就是 SSE 的全部意义: 用户在 2.6 秒看到第一个词,而不是在 2.8 秒看到一整句。

接口文档

给同事的那一版,不含 Pi 的任何概念:

type data 客户端做什么
text {"delta":"…"} 追加到气泡
thinking {"delta":"…"} 追加到折叠区
tool_start {"id","name","args"} 显示「执行中」卡片
tool_end {"id","name","isError"} 更新卡片
done {} 恢复输入框
error {"message":"…"} 显示错误

中断没有单独的接口:直接断开请求。服务端 res.on("close") 会 abort。

实测:客户端 2 秒超时断开(curl 退出码 28),6 秒后再发一个请求, 仍然 HTTP 200 加 event: done——会话没坏,busy 也释放了。


七、上线前的四个坑

坑 1:凭据和 cwd

auth.json 在 ~/.pi/agent/。别写进代码,别打进镜像。

另一件常被忽略的是 cwd。createAgentSession 的 cwd 默认 process.cwd()(sdk.ts:192),它决定两件事:DefaultResourceLoader 去哪找 AGENTS.md、.pi/ 这类项目级配置(:204),以及工具能碰哪些 文件——bash 的默认工作目录就是它。

服务进程在 / 或在部署目录启动,模型的一次 ls 就落在了构建产物里。 生产环境的做法是显式传 cwd,指向一个受限的沙箱目录。

坑 2:并发

一个 session 同时只能跑一轮。第二个人进来时,prompt() 立刻抛 (agent-session.ts:2158-2163):

ts
if (this.isStreaming) {	if (!options?.streamingBehavior) {		throw new Error(			"Agent is already processing. Specify " +			"streamingBehavior ('steer' or 'followUp') " +			"to queue the message.",		);	}

实测:第一个 prompt 还没结束时调第二次,立刻抛错,不排队。 错误原文:

text
Agent is already processing. Specify streamingBehavior('steer' or 'followUp') to queue the message.

所以 busy 标志不是可选的。服务端的 busy 实测:并发两个请求, 第二个拿到 {"error":"busy"} <- HTTP 429。

要支持多用户,得「每人一个 session」:SessionManager 换成按用户 落地的实例(session-manager.ts:1765 的 create),每人调一次 createAgentSession。本书不展开——那涉及会话隔离和按用户路由。 每个 session 都有一份资源加载开销(第三节实测 3.3 秒),真实项目还要配会话池。

坑 3:背压

res.write() 返回 false 表示缓冲区满了。SSE 一段几十字节,正常网络 下不会满;但客户端「连着不读」(手机切后台)时,缓冲区会一直涨。

麻烦在于你没有机会 await drain:subscribe 的监听器是同步调用的 (agent-session.ts:1055-1059,_emit 里一个 for 循环,不 await), 事件一到,你就得在里面把字节塞进 socket。

未压测。检测办法是把 send 改成:

ts
const ok = res.write(frame);if (!ok) slowClients++;

slowClients 涨起来就是有客户端在拖。真拖了只有两条路:断开它, 或者在监听器里先攒批、再异步写。

坑 4:一个畸形请求能打挂整个进程

这个是实测撞出来的。第一版服务直接 JSON.parse(body),我把 curl -d 的引号弄丢了,服务端收到 {message:hi}:

text
SyntaxError: Expected property name or '}' in JSON at position 1    at JSON.parse (<anonymous>)    at Server.<anonymous> (…/tmp-t22-server.ts:22:23)Node.js v24.12.0

async 的请求处理函数里抛错,就是一个未处理的 rejection,进程直接退出, 后面所有请求都连不上。加了 try/catch 之后实测:

text
{"error":"bad json"} <- HTTP 400

服务继续活着。写服务的第一天就该加这七行。


八、改一处试试

把 busy 那道闸门拆掉,看并发会怎么坏。(实跑于 node v24.12.0)

  • 改哪里 删掉 §六 里 if (busy) { … } 那五行(:344-348),保留 busy = true 和 finally 里的 busy = false;再在门口加一行日志, 把进门那一刻的 busy 打出来:
ts
console.log(`#${id} 进门时 busy=${busy}`);busy = true;
  • 预期 A 先发、700 ms 后发 B、再 300 ms 后发 C,实测:
text
[B] status=200 frames=2 首帧=error 末帧=done    ← B 半秒内结束[C] status=200 frames=2 首帧=error 末帧=done    ← C 也被放行[A] status=200 frames=96 首帧=text 末帧=done    ← A 正常跑完

B 的错误帧长这样:

text
event: errordata: {"message":"Agent is already processing. …"}

省略号处是它的完整文案(agent-session.ts:2160-2162):「Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.」——特意抄全,因为你会在日志里反复看到它。

注意前面的 status=200:SSE 的响应头在 prompt() 之前就发出去了, 所以客户端看到的不是 429,而是一个「开了流却只有错误」的 200。

  • 连带 真正的坏消息在门口日志:
text
#1 进门时 busy=false#2 进门时 busy=true     ← 原版在这里 429#2 收尾,busy -> false#3 进门时 busy=false    ← A 还在跑,闸门已经开了

B 走完 catch 就执行 finally 里的 busy = false,而 A 还在跑。第三个 请求因此看到 busy === false 被放行。状态机坏了,不是进程崩溃: 生产上表现为「偶发两条回答串在一起」,日志里什么都看不到。裸布尔的 问题不是没锁,而是别人的收尾替你把锁开了——要挡并发用计数器, 或以 prompt() 抛错为准(见第七节坑 2)。

  • 回滚 把五行判断加回去。busy 只在请求真正结束时清零。

本章小结

  1. 四种跑法(交互 / print / RPC / SDK)下面都是同一个 session。
  2. 没 key 也能走一半:读代码 + 假 streamFn。
  3. 一个 session 同时只跑一轮,第二个请求立刻抛。
  4. SSE 的 200 不代表成功:错误也走帧。
  5. 畸形 JSON 不兜会打挂整个进程。

概念回顾

术语 一句话 在哪
四种跑法 交互 / print / RPC / SDK,共用一套机制 §一
降级档 没 key 时用假 streamFn 走完链路 §二
busy 一个 session 同时只能跑一轮 §六、§七 坑 2
背压 res.write 返回 false 时没人 await §七 坑 3
200 错误帧 响应头先发,错误只能进流 §八

练习

练习 1(读):§八 里 B 走完 catch 就把 busy 清零,而 A 还在跑。 为什么第三个请求会被放行?→ 回 §八 的门口日志三行。

练习 2(改):照 §八 删掉 if (busy) 那五行闸门。 预期:B、C 都拿到 200 但首帧是 error;连带 A 还在跑时闸门已开。 回滚:把五行判断加回去,busy 只在请求真正结束时清零。

常见误区

  1. 你会以为 200 就是成功;实际是 错误也走 200 + error 帧;证据 §八。
  2. 你会以为 busy 只是个优化标志;实际是 没有它就是两条回答串在一起; 证据 §七 坑 2、§八 的门口日志。
  3. 你会以为 一个进程能直接服务多用户;实际是 要每人一个 session; 证据 §七 坑 2。

九、这一页没讲的

  • 入口选型:为什么这里选 SDK 而不是 RPC、-p 和 JSON 各适合什么场景, F09 给了五个入口的六维对照表,包括「SDK 不带内置扩展」这个坑。
  • 多用户会话隔离:每人一个 SessionManager 加一个 session,见坑 2。
  • 鉴权与限流:服务层的事,和 Pi 无关。
  • 优雅退出:dispose() 要挂在 SIGTERM 上,否则正在跑的 prompt 会被硬切。
  • WebSocket:Agent 对话是「用户偶尔发、Agent 持续推」,SSE 够用。 要双向高频(多人协作画板那种)才需要 WebSocket。

源码索引

符号 位置 行数
四种跑法的分支 packages/coding-agent/src/main.ts 1,011
RPC 模式自述 packages/coding-agent/src/modes/rpc/rpc-mode.ts —
createAgentSession packages/coding-agent/src/core/sdk.ts 482
SessionManager.inMemory packages/coding-agent/src/core/session-manager.ts —
AgentSessionEvent 全表 packages/coding-agent/src/core/agent-session.ts 4,480
subscribe / dispose / prompt 同上 —
_emit 同步分发 同上 —
AgentEvent 与 message_update packages/agent/src/types.ts —
工具事件发射点 packages/agent/src/agent-loop.ts —