a13nDocs

Stream Protocol

将 Harness 公开观测转换为结构化 AG-UI 事件，供终端、浏览器和传输层使用。

Stream Protocol（a13n-stream-protocol）将 Harness 输出转成 AG-UI 事件，再合并为终端或浏览器中的展示条目。保存检查点后，可以恢复尚未完成的展示。

从这里开始

任务指南
无需凭据，运行完整转换示例快速入门
映射文本、推理、工具、自定义事件和终结结果事件与处理器
消费端重启后重建投影重放与恢复
查找公开导出、分片限制和载荷格式API 与载荷参考
从保存状态继续 agent 执行Harness 状态与恢复

一个 observer 对应一次执行

HarnessAguiObserver 绑定单次执行。HarnessAguiStreamObserver 则绑定根流，独立跟踪其中的内联子执行，并用 subagentRunId 标识其输出归属。Host 管理的异步子执行仍使用独立 observer。

observe() 返回当前条目的事件。默认还保留供 snapshot() 使用的事件日志。Host 自行存储增量事件或使用 DisplayFold 时，设置 retain_events=False。fold 保留累积展示内容和解析续接状态，而不是每个 token 事件。重放与恢复介绍检查点恢复、observer 续接和源重放。

安装

Terminal
uv add a13n-stream-protocol

发布版 Stream Protocol 固定依赖匹配的 Harness 版本。源码快速入门使用仓库锁文件，与跟随 main 的本文档保持一致。

职责归属

职责负责方
Harness 执行、源生命周期、结果和 HarnessStateHarness
Harness 到 AG-UI 转换及进程内重建Stream Protocol
通过重放稳定的处理器表达可见性策略Host 处理器
源历史保留、游标、缺口检测和切换到实时流Host
持久 AG-UI ID、持久化、重放和扇出Host
SSE、WebSocket、Redis 或进程内交付Host 传输层
展示条目和解析续接状态Stream Protocol
检查点存储、分页、确认和后续事件选择Host
视觉呈现渲染器

升级到 AG-UI 1.0

请同步升级 Host 与渲染器。Python 使用 ag-ui-protocol>=1,<2；浏览器消费上游 @ag-ui/core 类型与 schema，不替换原有传输客户端。标准 wire 字段使用 camelCase，不提供 0.x 解码器或别名层。

  • 逻辑执行在准备成功后、公开输出前只发送一次 RUN_STARTED。
  • 取消和暂停使用带 cancelled 或 interrupt outcome 的 RUN_FINISHED，只有失败使用 RUN_ERROR。延后调用保留原生 ID，Host 回答验证策略不变。
  • 输入使用 CUSTOM value.event.role 和 value.event.message_id，元数据仍在顶层。
  • 工具结果可以包含有序的上游内容 part；隐藏的补充媒体不会公开。二进制数据和不安全 URL 转为省略载荷的描述，绝不包含内联字节；provider 文件句柄保持为 FileSource 引用，不提供可下载 URL。
  • 内联子执行的展示键按 subagentRunId 隔离，子回答不成为根回答。旧记录中缺失的子执行展示不能从模型历史重建。

协议升级不删除 Harness 续接状态或用量账本。

下一步

参考主题

主题指南
观测 Harness 执行观测 Harness 执行
读取累积快照读取累积快照
应用 Host 处理器应用 Host 处理器
从源历史恢复从源历史恢复
observer 恢复与 agent 恢复的区别observer 恢复与 agent 恢复的区别
错误与原子性错误与原子性

本页目录

从这里开始一个 observer 对应一次执行安装职责归属升级到 AG-UI 1.0下一步参考主题