第 5 课：流式事件与可观测性

结论

Pi 的事件流是 agent runtime 的黑盒观测接口。它告诉宿主：模型正在生成什么、工具何时开始和结束、turn 何时闭合、整个 agent 何时完成。

入口问题

如何证明 agent 真的执行过某个动作，而不是只在最终回答里声称自己做过？

心智模型

• message 事件记录模型输出的增量和结束。
• tool 事件记录工具开始、更新、结束和错误。
• turn 事件记录一轮模型与工具闭环。
• agent 事件记录整次任务的生命周期。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

function trace(event: AgentEvent) {
  const row = {
    time: Date.now(),
    type: event.type,
    turn: currentTurnId(),
    summary: summarize(event),
  };

  traceWriter.append(row);
}

• trace 不应该保存一大坨终端文本，而应该保存结构化事件。
• summary 可以避免默认记录完整敏感内容，同时保留排障所需信息。
• 后续评测、回放和可靠性分析都依赖这种事件级证据。

课堂练习

为一次 agent 运行设计最小 trace 字段：时间、事件类型、turn、工具名、退出状态、摘要。

掌握标准

• 能区分 message、tool、turn、agent 四类事件。
• 能说明 trace 和普通日志的差异。
• 能设计不会默认泄露敏感内容的事件摘要。

课后习题

1. 实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
2. 思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？