AG-UI Profile

目标

AG-UI 是 AaaS v1 的一等前端协议档案，负责把 canonical run 命令、事件流、状态恢复和人机协作语义暴露给 UI。

AG-UI 不拥有独立的消息真源。它是 canonical Run、Thread、InteractionRequest、Artifact 与事件流在前端侧的协议视图。

档案声明

• AG-UI 能力由 AgentRevision.protocolProfiles.agui 声明
• 实际 endpoint、transport 和 security 由 ProtocolBinding(protocol=agui) 声明
• transports 用于声明 SSE、WebSocket、HTTP Binary 等 transport
• capabilities 用于声明 transport、tool、state、reasoning、multi-agent、multimodal、human-in-the-loop、structuredOutput 能力
• protocolVersion 表示 AG-UI 版本，不等于 AaaS /v1

核心映射

AG-UI 概念	AaaS canonical model
agent session / conversation	Run + Thread
event stream	SequencedOutputEnvelope
message history restore	消息投影 + event replay
state snapshot / delta	读面投影与事件流增量
parent run lineage	RunLink
tool call / tool result	标准 tool call / result 事件、childRunId 与 Artifact
human-in-the-loop / approval	InteractionRequest

映射原则

• 创建会话或继续会话都映射到 run 命令
• 输出流映射到统一 SequencedOutputEnvelope
• UI 状态恢复 MUST 基于消息、interaction、artifact 和事件 replay 重建
• human-in-the-loop、approval、intervention、feedback 语义 MUST 映射到 InteractionRequest
• transport 可协商 SSE、NDJSON、WebSocket 或其他已声明接口

状态恢复与谱系

• AG-UI 客户端 MUST 可以通过 cursor 从上次消费位置恢复
• 服务端 MUST 允许通过读面和事件流重建当前 UI 所需历史
• 多 Agent 委派、handoff 或子任务 SHOULD 通过 RunLink 暴露谱系，而不是隐藏在 UI 私有消息里
• 如 profile 声明 state.snapshots 或 state.deltas，其内容 MUST 可与 canonical 读模型对齐

中断与交互

• AaaS v1 不把 AG-UI 的 draft interrupt 线协议直接采纳为 canonical 模型
• 稳定的中断语义使用 CancelRunCommand
• 稳定的继续输入、审批、确认和反馈语义使用 ContinueRunCommand 与 InteractionRequest
• 如实现需要支持 AG-UI draft interrupt shape，MUST 通过 extensions 声明，并映射回 canonical 命令

规范要求

• AG-UI 响应流 MUST 带稳定 cursor
• 断线重连 MUST 允许从上次 cursor 恢复
• AG-UI capability discovery MUST 与 revision profile 和 binding 一致
• AG-UI transport 暴露的 UI 专用元数据 MAY 放入 envelope metadata，但不得修改事件核心语义