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 何时改变。

逐步推进一次文本响应这里演示事件顺序,省略 partial、contentIndex 等完整 payload 字段;最终结果是 AssistantMessage,面板只显示其中的文本。
生产者 push尚未 push
for await 消费者等待事件…
result()Promise pending

尚未开始;最终消息等待终止事件。

查看完整步骤
  1. start:开始响应,result() 仍在等待。
  2. text_start:创建空文本块。
  3. text_delta:追加「Pi 」。
  4. text_delta:追加「ready」,文本成为「Pi ready」。
  5. text_end:文本块结束,result() 仍在等待。
  6. 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。

检索练习

  1. 哪个对象决定请求应交给哪个 provider/API?

模型体 / 消息体 / 上下文 / 工具体

查看解析

答案:模型体。Model 同时携带 provider、api、model id 和能力限制,用于选择路由。

  1. pi-ai.Tool自身包含哪类内容?

执行器 / 参数表 / 结果值 / 事件流

查看解析

答案:参数表。pi-ai.Tool 是给模型看的调用声明,execute 属于 pi-agent-core.AgentTool。

  1. AssistantMessageEventStream的核心设计是什么?

双出口 / 只数组 / 只回调 / 全同步

查看解析

答案:双出口。同一个 stream 同时支持增量 async iteration 和最终 result Promise。

离开页面前的 90 秒

不看上文,用自己的话回答:

  1. Context为什么是“请求快照”,而不是 Agent 状态?
  2. Tool为什么故意没有execute()?
  3. result()在什么事件被推入流时解析?成功与失败分别是什么事件?

上一课 · 核心契约速查 · Agent 事件顺序 · 课程地图

这一页,先记到这里。