尧图网站建设 
A2UI 扩展规范深度解析A2A 协议中的流式交互 UI 扩展v0.8【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiA2UIAgent-to-Agent UI是 A2AAgent-to-Agent协议的一个官方扩展它定义了一种让 Agent 向客户端流式发送、交互式用户界面的标准格式。本文以 v0.8 扩展规范为骨架结合仓库中配套的 JSON Schema 与协议文档完整讲解扩展 URI、核心概念、Agent Card 能力声明、扩展激活机制与数据编码方式帮助你快速理解并接入这套Agent 生成 UI的标准化方案。扩展定位A2A 之上的 UI 通道A2UI 扩展Extension解决的核心问题是Agent 与客户端之间除了文本与结构化数据的往返外如何传递可渲染的界面。该扩展在 A2A 协议的消息模型之上定义了一套附加格式使 Agent 能够向客户端发送流式、可交互的用户界面如表单、卡片、地图、仪表盘并接收用户在界面上的操作事件。从仓库结构可以看到A2UI 生态由规格specification/v0_8、JSON Schemaspecification/v0_8/json、协议文档a2ui_protocol.md以及多平台渲染器renderers组成其中扩展规范定义了如何把 A2UI 作为 A2A 扩展协商与激活协议文档则定义了JSONL 流中每条消息长什么样。扩展 URI 与唯一性约束每个 A2A 扩展都由唯一的 URI 标识。A2UI 扩展的 URI 为https://a2ui.org/a2a-extension/a2ui/v0.8规范明确规定这是该扩展唯一被接受的 URI。客户端与服务端在能力协商、扩展激活、消息识别等环节都必须严格使用这一标识不能使用其他别名或自定义变体。URI 中的v0.8段同时承担了版本标识作用当协议演进到新版本时会分配新的扩展 URI。核心概念A2UI 扩展建立在四个核心概念之上它们是理解整套规范的钥匙。Surface可独立控制的 UI 区域Surface是客户端 UI 中一块独立、可控制的区域。规范通过surfaceId将更新指令定向到特定区域例如主内容区、侧边栏、或一个新的聊天气泡。这使得单个 Agent 数据流能够同时独立管理多个 UI 区域——每个 Surface 拥有独立的根组件、组件层级和独立的数据模型避免大量 Surface 共存时出现键冲突。典型的应用场景是在聊天应用中每条 AI 生成的回复渲染到对话历史中的一个独立 Surface同时用一个常驻 Surface 显示侧边栏关联信息。Catalog Definition Document组件无关性的基础A2UI 扩展与具体组件无关component-agnostic。所有 UI 组件如 Text、Row、Button及其样式定义都放在独立的**目录定义文档Catalog Definition Document**中而不写死在协议里。这样客户端与服务端可以通过协商决定使用哪份目录Catalog。目录定义 Schema 的正式结构见 catalog_description_schema.json一个目录文档包含三个必填字段catalogId唯一标识该目录的字符串建议用你拥有的互联网域名作为前缀以避免冲突例如mycompany.com:somecatalogcomponents组件目录每个键是组件名每个值是描述该组件属性的 JSON Schemastyles样式目录每个键是样式名每个值是描述该样式属性的 JSON Schema。三大 JSON SchemaA2UI 扩展由三份核心 JSON Schema 定义Schema作用仓库对应文件Catalog Definition Schema定义组件库与样式的标准格式catalog_description_schema.jsonServer-to-Client Message SchemaAgent 发往客户端的核心线上格式如surfaceUpdate、dataModelUpdateserver_to_client_with_standard_catalog.jsonClient-to-Server Event Schema客户端发往 Agent 的核心线上格式如userActionclient_to_server.jsonClient Capabilities客户端能力声明客户端通过a2uiClientCapabilities对象声明自己的能力该对象被放在每一条从客户端发往服务端的 A2AMessage的metadata字段中用于告知 Agent 服务器客户端支持哪些目录。其正式 Schema 见 a2ui_client_capabilities_schema.jsonsupportedCatalogIds字符串数组必填客户端支持的所有预定义目录的 URI 列表。若支持标准目录必须显式包含其 IDinlineCatalogs对象数组可选完整的目录定义文档数组允许客户端在本地开发等场景中临时提供自定义目录仅当服务端声明acceptsInlineCatalogs: true时才可提供。Agent Card 中的能力声明Agent 在其 AgentCard 的AgentCapabilities.extensions列表中声明 A2UI 能力params对象定义 Agent 具体的 UI 支持情况。规范给出的示例{ uri: https://a2ui.org/a2a-extension/a2ui/v0.8, description: Ability to render A2UI, required: false, params: { supportedCatalogIds: [ https://a2ui.org/specification/v0_8/standard_catalog_definition.json, https://my-company.com/a2ui/v0.8/my_custom_catalog.json ], acceptsInlineCatalogs: true } }参数定义params.supportedCatalogIds可选字符串数组每个字符串是指向组件目录定义 Schema 的 URI表示该 Agent 能够生成这些目录中的组件params.acceptsInlineCatalogs可选布尔值表示 Agent 是否接受客户端a2uiClientCapabilities中的inlineCatalogs数组。省略时默认值为false。需要说明的是Agent Card 中的声明并非严格契约更多是给编排器和客户端用于识别能力匹配的 Agent的信号。在运行时编排 Agent 可能动态委派任务给支持额外目录的子 Agent因此客户端应把广告的supportedCatalogIds视为 Agent 及其子 Agent 真实支持目录的子集。扩展激活机制客户端通过传输层定义的 A2A 扩展激活机制来表达使用 A2UI 扩展的意愿对于JSON-RPC 与 HTTP 传输通过X-A2A-ExtensionsHTTP 头指定对于gRPC 传输通过X-A2A-Extensions元数据metadata值指定。激活该扩展意味着服务端可以发送 A2UI 专属消息如surfaceUpdate客户端也应发送 A2UI 专属事件如userAction。数据编码A2A DataPart 中的 A2UI 消息A2UI 消息编码为 A2A 的DataPart。要标识某个DataPart承载的是 A2UI 数据必须满足以下元数据约定mimeTypeapplication/jsona2uiDataPart的data字段包含 A2UI JSON 消息如surfaceUpdate、userAction。规范给出的示例{ data: { beginRendering: { surfaceId: outlier_stores_map_surface } }, kind: data, metadata: { mimeType: application/jsona2ui } }深入A2UI 消息协议与数据流扩展规范聚焦于协商与激活而消息内容由配套的 a2ui_protocol.md 定义。协议采用JSON LinesJSONL流传输通常承载于 **Server-Sent EventsSSE**之上客户端逐行解析、渐进渲染以获得良好的感知性能。服务端到客户端共四种消息类型Schema 见 server_to_client_with_standard_catalog.json每条消息必须恰好包含其中一种beginRendering通知客户端已具备足够信息可执行首次渲染指定根组件 ID可选携带catalogId目录标识与stylesfont主字体、primaryColor主色主色需符合^#[0-9a-fA-F]{6}$十六进制格式必填root与surfaceIdsurfaceUpdate提供一组组件定义用于向指定 Surface 新增或更新组件必填surfaceId与components至少 1 个组件每个组件必填id与component可选weight——对应 CSSflex-grow仅当组件是 Row/Column 的直接子级时可设置dataModelUpdate向 Surface 的数据模型插入或替换数据必填surfaceId与contents可选path省略或设为/时替换整个数据模型。contents中每条数据必须含key和恰好一个类型化value*属性valueString、valueNumber、valueBoolean、valueMap其中valueMap也是键值对的邻接表deleteSurface从 UI 中显式删除指定 Surface必填surfaceId。客户端到服务端共两种事件Schema 见 client_to_server.json一个包装对象必须恰好包含其中之一userAction上报组件触发的用户操作必填name、surfaceId、sourceComponentId、timestampISO 8601与context组件action.context经数据绑定解析后的键值对象error上报客户端侧错误内容灵活。整体数据流为服务端通过 SSE 推送 JSONL 流 → 客户端缓冲组件与数据 → 收到beginRendering信号后从根组件递归构建组件树并解析数据绑定、经由 WidgetRegistry 实例化原生组件 → 用户交互时客户端构造userAction通过 A2A 消息回传 → 服务端处理后通过原 SSE 流下发新的surfaceUpdate/dataModelUpdate/deleteSurface驱动 UI 更新。标准目录组件速查v0.8 的标准目录标识为https://a2ui.org/specification/v0_8/standard_catalog_definition.json其完整定义见 standard_catalog_definition.json并已内联进 server_to_client_with_standard_catalog.json。从 Schema 可确认 v0.8 标准目录包含 18 种组件组件关键属性Texttext必填literalString或path、usageHinth1–h5/caption/body支持不含 HTML/图片/链接的简单 MarkdownImageurl必填、altText、fitcontain/cover/fill/none/scale-down对应 CSSobject-fit、usageHinticon/avatar/smallFeature/mediumFeature/largeFeature/headerIconname约 60 个枚举值如accountCircle、search、send、warningVideourl必填AudioPlayerurl必填、descriptionRowchildren必填explicitList或template、distribution对应justify-content、alignment对应align-itemsColumn同RowListchildren必填、directionvertical/horizontal、alignmentCardchild必填TabstabItems必填每项含title与childDivideraxishorizontal/verticalModalentryPointChild、contentChild均必填Buttonchild、action均必填action含name与可选的context键值数组、primary布尔强调主操作CheckBoxlabel、value均必填布尔绑定TextFieldlabel必填、text、textFieldTypedate/longText/number/shortText/obscured、validationRegexpDateTimeInputvalue必填ISO 8601、enableDate、enableTimeMultipleChoiceselections、options均必填、maxAllowedSelectionsSlidervalue必填literalNumber或path、label、minValue、maxValue容器组件Row/Column/List的children必须恰好包含explicitList静态子组件 ID 的有序数组或template用于动态列表渲染含必填的dataBinding数据路径与componentId模板组件 ID二者之一。组件、绑定与事件组件对象在线上是通用的component包装对象必须恰好包含一个键键为目录中的组件类型名如Text值是该组件的属性对象。组件树采用邻接表模型——UI 是一份扁平组件列表树结构通过子组件 ID 引用隐式构建客户端在渲染时根据MapString, Component重建树。任何可绑定的属性如Text的text都接受BoundValue对象支持三种用法仅literalString静态值直接显示仅path动态值渲染时从数据模型解析path与literal*同时提供作为数据模型初始化简写——客户端先将字面量写入指定path隐式dataModelUpdate再绑定到该path渲染。协议只支持直接的 1:1 绑定不包含格式化、条件等转换器任何数据变换都应由服务端在发送dataModelUpdate前完成。交互事件方面客户端事件包装对象必须恰好包含userAction或error之一userAction中的context由组件action.context数组逐项解析字面量或数据绑定后构造。仓库中的配套实现与延伸阅读扩展规范与协议文档之外仓库还提供了可直接验证与接入的资源协议规范全文a2ui_protocol.md含完整 JSONL 流示例、目录协商流程、客户端实现组件清单各版本 JSON Schemaspecification/v0_8/jsonserver_to_client.json为抽象线上协议server_to_client_with_standard_catalog.json为已内联标准目录的解析后 Schema版本演进说明docs/evolution_guide.md 与 docs/a2ui_custom_functions.md多平台渲染器实现renderers/web_core、renderers/react、renderers/angular、renderers/lit其中 v0_8 渲染器实现见各仓库对应目录。结语A2UI v0.8 扩展规范以组件无关 目录协商 流式渲染为核心通过唯一的扩展 URI、AgentCard 能力参数、传输层激活头与application/jsona2ui的 DataPart 编码将 A2A 协议扩展为一条完整的Agent 生成 UI通道。理解扩展 URI、supportedCatalogIds/acceptsInlineCatalogs参数、a2uiClientCapabilities元数据以及激活与编码约定是接入或实现 A2UI 客户端/服务端的第一步更进一步的消息级细节可直接查阅本文引用的协议文档与 JSON Schema。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 A2UI 扩展规范深度解析：A2A 协议中的流式交互 UI 扩展（v0.8）
A2UI 扩展规范深度解析A2A 协议中的流式交互 UI 扩展v0.8【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiA2UIAgent-to-Agent UI是 A2AAgent-to-Agent协议的一个官方扩展它定义了一种让 Agent 向客户端流式发送、交互式用户界面的标准格式。本文以 v0.8 扩展规范为骨架结合仓库中配套的 JSON Schema 与协议文档完整讲解扩展 URI、核心概念、Agent Card 能力声明、扩展激活机制与数据编码方式帮助你快速理解并接入这套Agent 生成 UI的标准化方案。扩展定位A2A 之上的 UI 通道A2UI 扩展Extension解决的核心问题是Agent 与客户端之间除了文本与结构化数据的往返外如何传递可渲染的界面。该扩展在 A2A 协议的消息模型之上定义了一套附加格式使 Agent 能够向客户端发送流式、可交互的用户界面如表单、卡片、地图、仪表盘并接收用户在界面上的操作事件。从仓库结构可以看到A2UI 生态由规格specification/v0_8、JSON Schemaspecification/v0_8/json、协议文档a2ui_protocol.md以及多平台渲染器renderers组成其中扩展规范定义了如何把 A2UI 作为 A2A 扩展协商与激活协议文档则定义了JSONL 流中每条消息长什么样。扩展 URI 与唯一性约束每个 A2A 扩展都由唯一的 URI 标识。A2UI 扩展的 URI 为https://a2ui.org/a2a-extension/a2ui/v0.8规范明确规定这是该扩展唯一被接受的 URI。客户端与服务端在能力协商、扩展激活、消息识别等环节都必须严格使用这一标识不能使用其他别名或自定义变体。URI 中的v0.8段同时承担了版本标识作用当协议演进到新版本时会分配新的扩展 URI。核心概念A2UI 扩展建立在四个核心概念之上它们是理解整套规范的钥匙。Surface可独立控制的 UI 区域Surface是客户端 UI 中一块独立、可控制的区域。规范通过surfaceId将更新指令定向到特定区域例如主内容区、侧边栏、或一个新的聊天气泡。这使得单个 Agent 数据流能够同时独立管理多个 UI 区域——每个 Surface 拥有独立的根组件、组件层级和独立的数据模型避免大量 Surface 共存时出现键冲突。典型的应用场景是在聊天应用中每条 AI 生成的回复渲染到对话历史中的一个独立 Surface同时用一个常驻 Surface 显示侧边栏关联信息。Catalog Definition Document组件无关性的基础A2UI 扩展与具体组件无关component-agnostic。所有 UI 组件如 Text、Row、Button及其样式定义都放在独立的**目录定义文档Catalog Definition Document**中而不写死在协议里。这样客户端与服务端可以通过协商决定使用哪份目录Catalog。目录定义 Schema 的正式结构见 catalog_description_schema.json一个目录文档包含三个必填字段catalogId唯一标识该目录的字符串建议用你拥有的互联网域名作为前缀以避免冲突例如mycompany.com:somecatalogcomponents组件目录每个键是组件名每个值是描述该组件属性的 JSON Schemastyles样式目录每个键是样式名每个值是描述该样式属性的 JSON Schema。三大 JSON SchemaA2UI 扩展由三份核心 JSON Schema 定义Schema作用仓库对应文件Catalog Definition Schema定义组件库与样式的标准格式catalog_description_schema.jsonServer-to-Client Message SchemaAgent 发往客户端的核心线上格式如surfaceUpdate、dataModelUpdateserver_to_client_with_standard_catalog.jsonClient-to-Server Event Schema客户端发往 Agent 的核心线上格式如userActionclient_to_server.jsonClient Capabilities客户端能力声明客户端通过a2uiClientCapabilities对象声明自己的能力该对象被放在每一条从客户端发往服务端的 A2AMessage的metadata字段中用于告知 Agent 服务器客户端支持哪些目录。其正式 Schema 见 a2ui_client_capabilities_schema.jsonsupportedCatalogIds字符串数组必填客户端支持的所有预定义目录的 URI 列表。若支持标准目录必须显式包含其 IDinlineCatalogs对象数组可选完整的目录定义文档数组允许客户端在本地开发等场景中临时提供自定义目录仅当服务端声明acceptsInlineCatalogs: true时才可提供。Agent Card 中的能力声明Agent 在其 AgentCard 的AgentCapabilities.extensions列表中声明 A2UI 能力params对象定义 Agent 具体的 UI 支持情况。规范给出的示例{ uri: https://a2ui.org/a2a-extension/a2ui/v0.8, description: Ability to render A2UI, required: false, params: { supportedCatalogIds: [ https://a2ui.org/specification/v0_8/standard_catalog_definition.json, https://my-company.com/a2ui/v0.8/my_custom_catalog.json ], acceptsInlineCatalogs: true } }参数定义params.supportedCatalogIds可选字符串数组每个字符串是指向组件目录定义 Schema 的 URI表示该 Agent 能够生成这些目录中的组件params.acceptsInlineCatalogs可选布尔值表示 Agent 是否接受客户端a2uiClientCapabilities中的inlineCatalogs数组。省略时默认值为false。需要说明的是Agent Card 中的声明并非严格契约更多是给编排器和客户端用于识别能力匹配的 Agent的信号。在运行时编排 Agent 可能动态委派任务给支持额外目录的子 Agent因此客户端应把广告的supportedCatalogIds视为 Agent 及其子 Agent 真实支持目录的子集。扩展激活机制客户端通过传输层定义的 A2A 扩展激活机制来表达使用 A2UI 扩展的意愿对于JSON-RPC 与 HTTP 传输通过X-A2A-ExtensionsHTTP 头指定对于gRPC 传输通过X-A2A-Extensions元数据metadata值指定。激活该扩展意味着服务端可以发送 A2UI 专属消息如surfaceUpdate客户端也应发送 A2UI 专属事件如userAction。数据编码A2A DataPart 中的 A2UI 消息A2UI 消息编码为 A2A 的DataPart。要标识某个DataPart承载的是 A2UI 数据必须满足以下元数据约定mimeTypeapplication/jsona2uiDataPart的data字段包含 A2UI JSON 消息如surfaceUpdate、userAction。规范给出的示例{ data: { beginRendering: { surfaceId: outlier_stores_map_surface } }, kind: data, metadata: { mimeType: application/jsona2ui } }深入A2UI 消息协议与数据流扩展规范聚焦于协商与激活而消息内容由配套的 a2ui_protocol.md 定义。协议采用JSON LinesJSONL流传输通常承载于 **Server-Sent EventsSSE**之上客户端逐行解析、渐进渲染以获得良好的感知性能。服务端到客户端共四种消息类型Schema 见 server_to_client_with_standard_catalog.json每条消息必须恰好包含其中一种beginRendering通知客户端已具备足够信息可执行首次渲染指定根组件 ID可选携带catalogId目录标识与stylesfont主字体、primaryColor主色主色需符合^#[0-9a-fA-F]{6}$十六进制格式必填root与surfaceIdsurfaceUpdate提供一组组件定义用于向指定 Surface 新增或更新组件必填surfaceId与components至少 1 个组件每个组件必填id与component可选weight——对应 CSSflex-grow仅当组件是 Row/Column 的直接子级时可设置dataModelUpdate向 Surface 的数据模型插入或替换数据必填surfaceId与contents可选path省略或设为/时替换整个数据模型。contents中每条数据必须含key和恰好一个类型化value*属性valueString、valueNumber、valueBoolean、valueMap其中valueMap也是键值对的邻接表deleteSurface从 UI 中显式删除指定 Surface必填surfaceId。客户端到服务端共两种事件Schema 见 client_to_server.json一个包装对象必须恰好包含其中之一userAction上报组件触发的用户操作必填name、surfaceId、sourceComponentId、timestampISO 8601与context组件action.context经数据绑定解析后的键值对象error上报客户端侧错误内容灵活。整体数据流为服务端通过 SSE 推送 JSONL 流 → 客户端缓冲组件与数据 → 收到beginRendering信号后从根组件递归构建组件树并解析数据绑定、经由 WidgetRegistry 实例化原生组件 → 用户交互时客户端构造userAction通过 A2A 消息回传 → 服务端处理后通过原 SSE 流下发新的surfaceUpdate/dataModelUpdate/deleteSurface驱动 UI 更新。标准目录组件速查v0.8 的标准目录标识为https://a2ui.org/specification/v0_8/standard_catalog_definition.json其完整定义见 standard_catalog_definition.json并已内联进 server_to_client_with_standard_catalog.json。从 Schema 可确认 v0.8 标准目录包含 18 种组件组件关键属性Texttext必填literalString或path、usageHinth1–h5/caption/body支持不含 HTML/图片/链接的简单 MarkdownImageurl必填、altText、fitcontain/cover/fill/none/scale-down对应 CSSobject-fit、usageHinticon/avatar/smallFeature/mediumFeature/largeFeature/headerIconname约 60 个枚举值如accountCircle、search、send、warningVideourl必填AudioPlayerurl必填、descriptionRowchildren必填explicitList或template、distribution对应justify-content、alignment对应align-itemsColumn同RowListchildren必填、directionvertical/horizontal、alignmentCardchild必填TabstabItems必填每项含title与childDivideraxishorizontal/verticalModalentryPointChild、contentChild均必填Buttonchild、action均必填action含name与可选的context键值数组、primary布尔强调主操作CheckBoxlabel、value均必填布尔绑定TextFieldlabel必填、text、textFieldTypedate/longText/number/shortText/obscured、validationRegexpDateTimeInputvalue必填ISO 8601、enableDate、enableTimeMultipleChoiceselections、options均必填、maxAllowedSelectionsSlidervalue必填literalNumber或path、label、minValue、maxValue容器组件Row/Column/List的children必须恰好包含explicitList静态子组件 ID 的有序数组或template用于动态列表渲染含必填的dataBinding数据路径与componentId模板组件 ID二者之一。组件、绑定与事件组件对象在线上是通用的component包装对象必须恰好包含一个键键为目录中的组件类型名如Text值是该组件的属性对象。组件树采用邻接表模型——UI 是一份扁平组件列表树结构通过子组件 ID 引用隐式构建客户端在渲染时根据MapString, Component重建树。任何可绑定的属性如Text的text都接受BoundValue对象支持三种用法仅literalString静态值直接显示仅path动态值渲染时从数据模型解析path与literal*同时提供作为数据模型初始化简写——客户端先将字面量写入指定path隐式dataModelUpdate再绑定到该path渲染。协议只支持直接的 1:1 绑定不包含格式化、条件等转换器任何数据变换都应由服务端在发送dataModelUpdate前完成。交互事件方面客户端事件包装对象必须恰好包含userAction或error之一userAction中的context由组件action.context数组逐项解析字面量或数据绑定后构造。仓库中的配套实现与延伸阅读扩展规范与协议文档之外仓库还提供了可直接验证与接入的资源协议规范全文a2ui_protocol.md含完整 JSONL 流示例、目录协商流程、客户端实现组件清单各版本 JSON Schemaspecification/v0_8/jsonserver_to_client.json为抽象线上协议server_to_client_with_standard_catalog.json为已内联标准目录的解析后 Schema版本演进说明docs/evolution_guide.md 与 docs/a2ui_custom_functions.md多平台渲染器实现renderers/web_core、renderers/react、renderers/angular、renderers/lit其中 v0_8 渲染器实现见各仓库对应目录。结语A2UI v0.8 扩展规范以组件无关 目录协商 流式渲染为核心通过唯一的扩展 URI、AgentCard 能力参数、传输层激活头与application/jsona2ui的 DataPart 编码将 A2A 协议扩展为一条完整的Agent 生成 UI通道。理解扩展 URI、supportedCatalogIds/acceptsInlineCatalogs参数、a2uiClientCapabilities元数据以及激活与编码约定是接入或实现 A2UI 客户端/服务端的第一步更进一步的消息级细节可直接查阅本文引用的协议文档与 JSON Schema。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考