协议语义在每种传输上都相同。 传输是绑定(binding):它定义运行输入如何投递、事件如何成帧与编码、流如何终止或失败。它不定义事件含义——事件模式与处理模型在每个绑定上都相同。
绑定契约
绑定 MUST 提供:
- 有序、完整地投递一次运行的事件,按生产者发射顺序。协议的顺序就是到达顺序;可能重排或丢弃事件的传输,若没有恢复两者的层,就无法承载 AG-UI。
- 投递开启交换的
RunAgentInput,先于任何事件。继续携带更多运行的流——重放线程——不为它们投递更多输入:这些运行是生产者在重述历史,每个RUN_STARTEDMAY 携带自己的input回显。 - 消费者能与截断区分的终止信号:在终止事件之后干净结束的流是已关闭运行;没有终止事件就断开的连接是截断运行。
- 被拒绝输入的错误路径——结构无效的
RunAgentInput在RUN_STARTED之前被拒绝,位于流之外。
认证与授权是绑定与应用的属性,不是协议的:AG-UI 不定义凭据,绑定携带其通道使用的任何机制(HTTP 认证、环境进程身份,或什么都没有)。
标准绑定
- HTTP + Server-Sent Events:运行输入是一个 HTTP POST;事件作为携带 JSON 的 SSE 帧流回。
- HTTP + Protobuf:同样的 POST,协商为长度前缀 protobuf 帧的二进制响应。
两个绑定共享请求部分;仅在响应编码上不同,由内容协商选择。使用 HTTP 的实现 MUST 支持 SSE 绑定;protobuf 绑定是 OPTIONAL。
截断
流在没有终止事件的情况下结束,消费者就有一个截断运行:生产者可能仍在继续,但此消费者永远看不到其余部分。截断运行没有 outcome。消费者 MUST NOT 为它合成 RUN_FINISHED,也 MUST NOT 报告它成功;运行在中断前投递的一切仍然有效。除此之外如何呈现截断——让运行保持未决,或抛出合成的失败——是消费者的事;重新运行是一次带新 runId 的新运行。
自定义传输
实现 MAY 通过其他通道承载 AG-UI——WebSocket、消息总线、进程内管道。自定义传输 MUST 保留事件模型、事件模式与处理规则,并 MUST 满足上述绑定契约。它 SHOULD 记录其成帧、输入投递,以及终止与错误信号,以助互操作。
携带 JSON 的自定义传输 SHOULD 完全按 SSE 绑定的方式成帧——每帧一个事件对象——而不是发明新信封:SSE 绑定的成帧就是协议的 JSON 成帧,只有其 HTTP 机制是 HTTP 特有的。