03｜pi-ai 的输入输出：事件流、最终消息与可重放上下文

这篇写什么

聚焦 pi-ai 的统一输入输出协议：为什么要把输出分成“事件流”和“最终消息”，以及为什么“可重放性”是 agent 系统的关键约束。

先说结论

pi-ai 的核心价值是：把多厂商模型调用统一成一套对 agent 友好的输入输出协议。

对 agent 友好意味着它要覆盖：

• 多轮上下文
• 工具调用
• 流式增量输出
• thinking/reasoning
• usage/cost
• 失败与中断
• 跨模型继续对话

统一输入：上层真正需要表达的只有四类

1. 用哪个模型
2. 当前上下文是什么
3. 这轮可以用哪些工具
4. 这轮调用的运行参数是什么

模型输入不是字符串

模型对象应携带能力与调用语义：provider、协议类型、上下文窗口、是否支持 reasoning/多模态、成本与兼容配置等。

上下文输入不是单一 prompt

必须能表达 system 指令、历史消息、tool result 历史、以及多模态内容块。

工具输入必须结构化

工具是一组能力清单（名称/描述/参数 schema），而不是靠纯文本提示“你可以用这些工具”。

运行参数与上下文分层

运行参数影响执行方式（温度、max tokens、abort、transport、metadata…），但不应污染上下文语义。

统一输出：为什么要两层

1) 过程层：事件流

事件流用于表达进行中的状态变化，例如：

• 文本增量
• thinking 增量
• tool call 及参数增量
• 结束或错误

价值：UI 可实时渲染，runtime 可在 tool call 完整时接管执行。

2) 结果层：最终消息

最终消息是“这轮调用的官方结算单”：

• 完整 assistant 内容（可能包含 text/thinking/tool call 等内容块）
• 来源信息（provider/model/协议）
• usage/cost
• stop reason
• error（如有）

价值：便于落库、回放、续接会话、统计分析。

为什么必须强调可重放性

一句话：输出最终要能够回流为下一轮输入。

这看起来简单，但现实里要面对：

• thinking/reasoning 可能无法跨模型无损重放
• tool call 标识或格式在不同 provider 下可能不兼容
• aborted/error 消息是否应进入历史

因此设计要允许：

• 表达 thinking/tool call
• 同时不假设它们一定能跨模型原样重放
• 必要时降级、剔除或转换

stop reason 为什么必须标准化

不同 provider 的结束语义很不统一，但上层真正关心的是：

• 是否自然结束
• 是否需要执行工具
• 是否长度截断
• 是否错误或中断

标准化 stop reason 是 agent runtime 决策（继续/停止、补救、重试）的关键依据。

小结

pi-ai 输入侧统一“模型 + 上下文 + 工具 + 运行参数”，输出侧统一“事件流 + 最终消息”，并把“可重放性”作为设计约束。

这些是它能支撑 agent 系统稳定多轮运行的骨架。