A2UI 与 A2A 协议扩展规范 v1.0在 Agent 间传输流式交互 UI 的完整实现指南【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本指南面向所有需要实现 A2UI A2A 扩展的开发者系统讲解如何在 A2AAgent-to-Agent协议之上叠加 A2UI v1.0让 Agent 能向渲染器Renderer发送流式的、可交互的用户界面并接收来自渲染器的用户动作事件。读完本文你将掌握扩展 URI 的约定、AgentCard 能力声明、HTTP/gRPC 两种传输下的扩展激活方式、双向元数据协商以及 A2UI 消息的DataPart数据编码与逐条处理规则并能在 Python Agent SDK 的源码与规范 JSON Schema 中找到每一步的落点与验证依据。A2UI A2A 扩展是什么A2UIAgent-to-Agent UI是 A2A 协议的一个官方扩展它定义了一种数据格式让 Agent 能够把流式的、可交互的用户界面直接发送给渲染器显示。与传统的一次性渲染整页 UI 不同A2UI 允许 Agent 通过消息流例如createSurface、updateComponents、action渐进式地构建和更新界面同时把用户的交互动作实时回传给 Agent。该扩展的激活是可选的渲染器与 Agent 可以通过 A2A 消息中的message.metadata[a2uiRendererCapabilities]自行协商 A2UI 支持能力——这条元数据由渲染器附加在每条发往 Agent 的 A2A 消息上包含其支持的协议版本与目录Catalog。规范同时鼓励 Agent 在其 AgentCard 中主动宣告 A2UI 能力因为渲染器可能依赖该宣告来决定是否发送a2uiRendererCapabilities但这一宣告并非强制要求。该扩展规范对应 A2UI v1.0草案阶段曾称 v0.10基础协议部分请参阅 v1.0 Protocol Specification。扩展 URI版本协商的规范锚点本扩展的规范 URI 为https://a2ui.org/a2a-extension/a2ui/v1.0该 URI 是渲染器与 Agent 之间传达协议版本的方式版本号v1.0被显式编码在 URI 中。渲染器请求这个特定 URI即表示它支持 v1.0 的 schema 格式。在 Python SDK 的 extension.py 中可以看到该约定的实现A2UI_EXTENSION_BASE_URI https://a2ui.org/a2a-extension/a2uiget_a2ui_extension_uri(version)将其与/v{version}拼接生成完整 URIget_a2ui_extension_uri_version()则反向从 URI 中剥离出版本字符串。由于版本被编码在 URI 里SDK 可以通过 版本协商逻辑_select_newest_a2ui_extension基于packaging.version对匹配到的扩展 URI 取版本号最大者在渲染器请求与 Agent 宣告的扩展之间自动选择最新可用版本从而支持多版本共存的平滑演进。在 AgentCard 中声明 A2UI 能力Agent 被鼓励在 AgentCard 的AgentCapabilities.extensions列表中宣告其 A2UI 能力。该宣告是可选的作用是通知渲染器是否应向该 Agent 发送message.metadata[a2uiRendererCapabilities]。params对象定义了 Agent 具体的 UI 支持范围其结构直接对应 Agent Capabilities Schema。规范的 AgentCard 示例{ name: Dashboard Agent, description: Agent capable of generating dynamic UI dashboards., capabilities: { extensions: [ { uri: https://a2ui.org/a2a-extension/a2ui/v1.0, description: Ability to render A2UI v1.0, required: false, params: { supportedCatalogIds: [ https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json, https://my-company.com/a2ui/v1.0/my_custom_catalog.json ], acceptsInlineCatalogs: true } } ] } }params对象对应agent_capabilities.jsonschema 中的v1.0对象包含两个可选字段参数类型说明默认值supportedCatalogIdsstring[]每个字符串是一个标识 Agent 能够为其生成内容的 Catalog Definition Schema 的 ID。注意它不一定是一个可解析的 URI只是目录标识符无可选acceptsInlineCatalogsboolean表示 Agent 是否接受渲染器a2uiRendererCapabilities中的inlineCatalogs数组false省略即默认从 schema 可见v1.0是required字段且整个对象结构中多个目录可以在同一个 surface 中混合使用。在 extension.py 中get_a2ui_agent_extension()帮助函数会按此结构构造AgentExtension仅当accepts_inline_catalogs为真时才写入该字段保持省略即默认false的语义仅当提供了supported_catalog_ids时才写入目录列表保证声明的精简与规范一致。A2A 扩展激活激活 A2UI 扩展是可选的渲染器与 Agent 的协商通道是渲染器在message.metadata[a2uiRendererCapabilities]中携带能力对象Agent 据此确定受支持的 A2UI 协议版本与目录Agent 在返回的 A2ADataPart.data.metadata[mimeType] application/a2uijson中表明载荷包含 A2UI 消息渲染器据此识别。不强制显式激活但渲染器仍可使用传输层定义的 A2A 扩展激活机制来显式激活该扩展。注意不要使用accepted_output_modes: [a2ui]来触发 A2UI那并非 A2UI 标准。HTTP/JSON-RPC 传输在 JSON-RPC/HTTP 传输下通过X-A2A-ExtensionsHTTP 头携带扩展 URI 激活扩展POST /v1/messages HTTP/1.1 Host: agent.example.com X-A2A-Extensions: https://a2ui.org/a2a-extension/a2ui/v1.0 Content-Type: application/json { message: { parts: [ { text: Hello, show me the dashboard } ] } }Agent 端解析该扩展 URI 的完整流程见 extension.pytry_activate_a2ui_extension()先从RequestContext.requested_extensions与message.extensions两个来源收集以A2UI_EXTENSION_BASE_URI开头的请求扩展再与 AgentCard 中宣告的扩展求交集最后通过_select_newest_a2ui_extension()选出最新版本调用context.add_activated_extension(selected_uri)完成激活并返回版本字符串任一环节不匹配则返回None未激活。gRPC 传输在 gRPC 传输下渲染器将扩展 URI 放入 A2AsendMessageParams.metadata[X-A2A-Extensions]{ metadata: { X-A2A-Extensions: https://a2ui.org/a2a-extension/a2ui/v1.0 }, message: { parts: [ { text: Hello, show me the dashboard } ] } }Renderer 到 Agent 的元数据渲染器通过 A2A 消息附加a2uiRendererCapabilities和a2uiRendererDataModel两条元数据向 Agent 传达其状态与支持的目录。a2uiRendererCapabilities渲染器在sendMessageRequest.message[a2uiRendererCapabilities]中携带 Renderer Capabilities Schema用于宣告自身支持的目录。此外渲染器在运行时通过读取活动目录定义中的配置来确定某个函数的执行边界例如rendererOnly状态——该函数只能在渲染器本地执行还是需要回传 Agent。{ message: { parts: [ { text: Show me the dashboard. } ], metadata: { a2uiRendererCapabilities: { v1.0: { supportedCatalogIds: [ https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json, https://my-company.com/a2ui/v1.0/my_custom_catalog.json ] } } } } }对照 renderer_capabilities.json 可知v1.0.supportedCatalogIds是必填字段每个字符串标识渲染器支持的组件/函数目录多个目录可在同一 surface 中混用v1.0.inlineCatalogs是可选字段为内联目录定义数组可同时包含组件与函数且仅当 Agent 宣告acceptsInlineCatalogs: true时才应提供。a2uiRendererDataModel当某个 surface 启用了 Data Model Sync 时渲染器会在每一条消息上附加sendMessageRequest.message[a2uiRendererDataModel]其结构遵循 Renderer Data Model Schema。该数据模型为 Agent 提供最新的 UI 状态用于双向数据同步。更详细的机制见 Actions Guide。{ message: { parts: [ { text: Submit the form. } ], metadata: { a2uiRendererDataModel: { version: v1.0, surfaces: { main_surface_id: { user_id: 12345, email: userexample.com } } } } } }从 renderer_data_model.json 的 schema 定义看version被约束为常量v1.0surfaces是一个 surfaceId 到其当前数据模型的映射值为任意标准 JSON 对象二者皆为必填且additionalProperties被禁止结构非常严格。数据编码DataPart与application/a2uijsonAgent 与渲染器将 A2UI 消息编码为 A2A 的DataPart。标识一个DataPart包含 A2UI 数据的关键元数据是DataPart.data.metadata[mimeType] application/a2uijsonDataPart的data字段是一个A2UI JSON 消息数组如createSurface、updateComponents、action必须是数组形式不能是单个对象。处理规则data中的消息列表不是事务单元。接收方渲染器与 Agent必须按顺序逐条处理该列表中的消息若列表中某条消息校验或应用失败如 schema 违规、无效引用接收方应该针对该条消息记录/上报错误并必须继续处理列表中剩余的其余消息原子性仅保证到单条消息级别为了更好的用户体验渲染器不应在列表内所有消息处理完成前重绘 UI以避免中间状态闪烁。Agent 到渲染器的消息当 Agent 向渲染器或作为渲染器角色的其他 Agent发送消息时data载荷必须通过 Agent-to-Renderer Message List Schema 校验——该列表 schema 的每一项都引用 Agent-to-Renderer 消息 schema。{ data: [ { version: v1.0, createSurface: { surfaceId: example_surface, catalogId: https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json } }, { version: v1.0, updateComponents: { surfaceId: example_surface, components: [ { id: root, component: Text, text: Hello! } ] } } ], kind: data, metadata: { mimeType: application/a2uijson } }从 agent_to_renderer.json 的oneOf定义看Agent 到渲染器的消息共有6 种类型消息类型核心字段语义要点createSurfacesurfaceId必填、catalogId、sendDataModel、components、dataModel、metadata创建并开始渲染新 surface隐式实例化规范Surface容器组件child: rootsurfaceId 在渲染器生命周期内必须全局唯一创建已有 ID 是错误默认sendDataModel为false设为true时渲染器将在后续每条 A2A 消息元数据中回传该 surface 的完整数据模型updateComponentssurfaceId、components均必填用新组件集更新已有 surface可多次发送组件列表中必须有一个id为root的组件作为组件树根发送前必须已createSurfaceupdateDataModelsurfaceId、value均必填、path可选更新已有 surface 的数据模型path形如/user/name省略或为/表示整个数据模型将value显式设为null表示删除该路径的键/值deleteSurfacesurfaceId必填删除指定 surface发送前必须已createSurfacecallRendererFunctionfunctionCallId、callFunction均必填且callFunction内catalogId必填请渲染器在本地代表 Agent 执行函数渲染器必须将functionCallId原样复制进响应agentFunctionResponseagentFunctionResponse必填向渲染器返回FunctionResponseRenderer 到 Agent 的事件渲染器或转发事件的 Agent向 Agent 发送消息时同样使用application/a2uijsonMIME 类型的DataPart但data载荷必须通过 Renderer-to-Agent Message List Schema 校验其每一项引用 Renderer-to-Agent 消息 schema。{ data: [ { version: v1.0, action: { name: submit_form, surfaceId: contact_form_1, sourceComponentId: submit_button, timestamp: 2026-01-15T12:00:00Z, context: { email: userexample.com } } } ], kind: data, metadata: { mimeType: application/a2uijson } }renderer_to_agent.json 定义渲染器到 Agent 的消息共有4 种类型version均必填且恒为v1.0每条消息恰好两个属性消息类型核心字段语义要点actionname、surfaceId、sourceComponentId、timestampISO 8601、context均必填userMessage、metadata可选上报组件触发的用户动作name取自组件action.event.namecontext为解析所有数据绑定后的键值对timestamp为事件发生时刻callAgentFunctionsurfaceId、functionCallId、callFunction均必填请求 Agent远程代表渲染器执行函数Agent 必须将functionCallId原样复制进响应rendererFunctionResponserendererFunctionResponse必填渲染器返回函数执行结果error视类型而定上报渲染器侧错误。Validation Failed 类错误code限定为VALIDATION_FAILED、UNALLOWED_PARENT、UNALLOWED_CHILD之一并要求pathJSON Pointer如/components/0/text、message、surfaceIdGeneric 类错误code不得为上述三个值且surfaceId与functionCallId二选一必填相关规范资源基础协议A2UI Protocol v1.0扩展规范原始源文件specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md能力与数据模型 Schemaagent_capabilities.json、renderer_capabilities.json、renderer_data_model.json消息列表 Schemaagent_to_renderer_list.json、renderer_to_agent_list.json及各自的单条消息 Schema agent_to_renderer.json、renderer_to_agent.json基础目录定义basic 目录v1.0SDK 实现参考extension.py扩展 URI 与激活协商、parts.pyDataPart 编码、sdks_spec.md概念延伸Actions Guide、Data Binding 概念【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考