附录 C —— 把 Agent 装进你的服务
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,
分支就三行:
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):
/** * 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:
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() 零参数,只打两个字段):
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 层。
三、十行嵌入
最短能跑的形状:
// 本页示例,实跑于 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 用是最常见的笔误:
const off = session.subscribe(...); // 对const s2 = session.subscribe(...); // s2 是函数,不是 sessionprompt() 的 Promise 覆盖整轮,不只是首 token。 模型调工具、
工具跑完、再调模型,这一整套都在同一个 Promise 里。
实测同一段代码(只把 handle 换成打类型名):
model : doubaofallback : (none)unsubscribe: functionprompt ms : 7849messages : 5dispose ok : 11126 ms total11.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):
第 1 轮后 messages = 3第 2 轮后 messages = 5最后一条 role = assistant | stop = stop文本 = "42" ← 它记得上一轮3 是 system + user + assistant;第二轮又加 2 条。每轮只增两条,
但每次请求发的是全量。
用量在 message.usage。实测第二轮那条:
{"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 不只属于用户
一轮真实对话的骨架(实测,字段是原样打印):
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:
| { 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. 一轮到底发多少事件
实测一次带两次工具调用的对话(每轮都不一样,以下是那一次的计数):
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=166 个事件里 37 个是增量。转发时用白名单,别原样丢给浏览器:
entry_appended、queue_update、compaction_* 前端根本不显示,
传过去只是浪费带宽和前端的事件处理分支。
六、四十行服务
用 node:http,不引 Express。理由不是「轻量」,是仓库的依赖里没有它
(packages/coding-agent/package.json 的 dependencies 里没有 express),
示例引一个装不上的包,等于跑不起来。
// 实跑于 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。
请求一次
curl -sN -X POST http://127.0.0.1:3123/chat \ -H "Content-Type: application/json" \ -d '{"message":"list files with ls"}'真实输出(截前四帧和末尾):
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 跑同一套读法):
状态: 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):
if (this.isStreaming) { if (!options?.streamingBehavior) { throw new Error( "Agent is already processing. Specify " + "streamingBehavior ('steer' or 'followUp') " + "to queue the message.", ); }实测:第一个 prompt 还没结束时调第二次,立刻抛错,不排队。
错误原文:
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 改成:
const ok = res.write(frame);if (!ok) slowClients++;slowClients 涨起来就是有客户端在拖。真拖了只有两条路:断开它,
或者在监听器里先攒批、再异步写。
坑 4:一个畸形请求能打挂整个进程
这个是实测撞出来的。第一版服务直接 JSON.parse(body),我把 curl -d
的引号弄丢了,服务端收到 {message:hi}:
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.0async 的请求处理函数里抛错,就是一个未处理的 rejection,进程直接退出,
后面所有请求都连不上。加了 try/catch 之后实测:
{"error":"bad json"} <- HTTP 400服务继续活着。写服务的第一天就该加这七行。
八、改一处试试
把 busy 那道闸门拆掉,看并发会怎么坏。(实跑于 node v24.12.0)
- 改哪里 删掉 §六 里
if (busy) { … }那五行(:344-348),保留busy = true和finally里的busy = false;再在门口加一行日志, 把进门那一刻的busy打出来:
console.log(`#${id} 进门时 busy=${busy}`);busy = true;- 预期 A 先发、700 ms 后发 B、再 300 ms 后发 C,实测:
[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 的错误帧长这样:
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。
- 连带 真正的坏消息在门口日志:
#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只在请求真正结束时清零。
本章小结
- 四种跑法(交互 / print / RPC / SDK)下面都是同一个 session。
- 没 key 也能走一半:读代码 + 假
streamFn。 - 一个 session 同时只跑一轮,第二个请求立刻抛。
- SSE 的 200 不代表成功:错误也走帧。
- 畸形 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 只在请求真正结束时清零。
常见误区
- 你会以为 200 就是成功;实际是 错误也走 200 + error 帧;证据 §八。
- 你会以为
busy只是个优化标志;实际是 没有它就是两条回答串在一起; 证据 §七 坑 2、§八 的门口日志。 - 你会以为 一个进程能直接服务多用户;实际是 要每人一个 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 |
— |