pi-ai 的五个核心契约
连接 Model、Message、Tool、Context 与事件流,理解增量事件和最终消息。
本章目录CONTENTS ↓
本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。
本章目标:给你一个streamSimple(model, context)调用,你能指出输入的每个角色,并能预测事件流与最终结果。
为什么先学pi-ai?
Agent loop 不应该知道 Anthropic、OpenAI 或 Google 的原始 JSON。它只认识一套公共语言:
streamSimple(model, context, options) │ │ │ └─ 本次请求看到的消息与工具 └───────── provider、API、能力与限制
返回 AssistantMessageEventStream因此,mini_pi 可以首版只接一个 provider,但必须让上层看到相同的公共类型和事件协议。类型定义的第一手来源是pi-ai/src/types.ts。
五个角色
Model
说明调用哪个 provider/API/model,以及输入能力、上下文窗口和输出上限。
Message
SystemMessage | UserMessage | AssistantMessage | ToolResultMessage,用role判别。
Tool
模型可见的能力声明:名称、描述、参数 schema。这里没有execute()。
Context
一次请求的systemPrompt + messages + tools,不是整个 Agent runtime。
EventStream
一边让 UI/Agent 消费增量事件,一边通过result()交付最终消息。
用 StreamFunction 连接请求与响应
StreamFunction 接收模型、归一化请求上下文与选项,返回事件流。当前版本的上下文类型是 TranscriptContext。
Tool 声明 ≠ Tool 实现 pi-ai.Tool只负责“告诉模型怎么调用”。pi-agent-core.AgentTool扩展它,才加入label、execute()和执行策略。
公开入口接受 Context,其中 systemPrompt 和 tools 是简写。normalizeContext() 把它们折叠到开头的 system message 中,再生成 provider 接收的 TranscriptContext。因此,公开请求输入和 provider 的实际输入应分别理解,不能把两者当作同一个类型。
Event stream 不是数组
数组要求所有值先到齐;event stream 允许生产者一边push,消费者一边for await。Pi 的 stream 还有第二个出口:result()返回最终AssistantMessage。
EventStream<T, R>的泛型恰好描述双出口 T是每次迭代得到的事件类型,R是result()的最终类型。因此AssistantMessageEventStream实质上是EventStream<AssistantMessageEvent, AssistantMessage>。
const stream = models.streamSimple(model, context);
for await (const event of stream) { render(event); // 增量出口}
const message = await stream.result(); // 最终出口理解排队与消费时,可以先看三个结构:暂存未消费事件的queue、等待新事件的waiting、标记终止的done。直接阅读event-stream.ts,比先学 RxJS 更贴近我们的复刻目标。
亲手推进一次流
每点一次“下一事件”,生产者 push 一个事件。观察消费者序列、partial text 和最终 Promise 何时改变。
尚未开始;最终消息等待终止事件。
查看完整步骤
- start:开始响应,result() 仍在等待。
- text_start:创建空文本块。
- text_delta:追加「Pi 」。
- text_delta:追加「ready」,文本成为「Pi ready」。
- text_end:文本块结束,result() 仍在等待。
- done:推入最终消息,result() 解析,迭代在交付 done 后结束。
终止事件同时做两件事。 done 或 error 会作为最后一个事件被迭代,也会在被 push 时让 result() 得到最终消息,无需等待消费者读到该事件。流内的错误仍解析为 AssistantMessage。请求开始前,直接调用底层 streamSimple() 的认证错误可能同步抛出;Models.streamSimple() 则把认证工作包装在延迟流中。
从官方 faux provider 看真实用法
import { createModels } from "@earendil-works/pi-ai/models";import { fauxProvider, fauxAssistantMessage } from "@earendil-works/pi-ai/providers/faux";
const faux = fauxProvider();const models = createModels();models.setProvider(faux.provider);
faux.setResponses([fauxAssistantMessage("pong")]);
const stream = models.streamSimple(faux.getModel(), { messages: [{ role: "user", content: "ping", timestamp: Date.now() }],});
for await (const event of stream) console.log(event.type);console.log((await stream.result()).stopReason);预测输出骨架:start → text_start → text_delta* → text_end → done,最终stopReason是stop。faux 的价值不是“假装聪明”,而是把 provider 的非确定性替换成脚本化响应,供 Agent 和协议测试稳定复现。
推荐主读:providers/faux.ts中的streamWithDeltas()。只读该函数,不需要读完整 provider registry。
检索练习
- 哪个对象决定请求应交给哪个 provider/API?
模型体 / 消息体 / 上下文 / 工具体
查看解析
答案:模型体。Model 同时携带 provider、api、model id 和能力限制,用于选择路由。
pi-ai.Tool自身包含哪类内容?
执行器 / 参数表 / 结果值 / 事件流
查看解析
答案:参数表。pi-ai.Tool 是给模型看的调用声明,execute 属于 pi-agent-core.AgentTool。
AssistantMessageEventStream的核心设计是什么?
双出口 / 只数组 / 只回调 / 全同步
查看解析
答案:双出口。同一个 stream 同时支持增量 async iteration 和最终 result Promise。
离开页面前的 90 秒
不看上文,用自己的话回答:
Context为什么是“请求快照”,而不是 Agent 状态?Tool为什么故意没有execute()?result()在什么事件被推入流时解析?成功与失败分别是什么事件?
上一课 · 核心契约速查 · Agent 事件顺序 · 课程地图
这一页,先记到这里。