A2UI 协议 v0.9.1 演进指南MIME 类型标准化与 Surface ID 唯一性约束放宽【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本指南系统讲解 A2UIAgent to UI协议从 v0.9 到 v0.9.1 的全部变更内容涵盖 MIME 类型标准化、surfaceId唯一性约束的放宽以及面向实现者的无缝迁移步骤。读者读完将掌握 v0.9.1 相对 v0.9 的差异本质、如何在代码中正确处理新旧 MIME 类型以及如何在多 Agent / 多 Surface 场景下正确管理 Surface 生命周期。A2UI v0.9.1 是 v0.9 规范的一次小版本细化minor refinement它不引入新的消息类型不改动组件模型与数据绑定语义而是聚焦于两处关键修正——统一消息载荷的 MIME 类型标识以及放宽surfaceId的全生命周期唯一性要求。这两项变更共同指向一个目标让协议在多 Agent 协作、多 Surface 并存的真实生产环境中更易落地。注本文基于仓库中的 v0.9.1 演进指南 展开从 v0.8 到 v0.9 的更大规模演进Structured Output First 到 Prompt First 的哲学转变可参阅 v0.9 演进指南。一、v0.9.1 核心变更一览根据 evolution_guide.md 的 Executive Summaryv0.9.1 的全部变更可归纳为两点变更项变更前v0.9 草稿变更后v0.9.1MIME 类型标准化遗留的application/jsona2ui统一为application/a2uijsonSurface ID 唯一性约束surfaceId必须在 renderer 生命周期内全局唯一仅在当前活跃的 surfaces 之间唯一对已存在 surface 重复发送createSurface而不先deleteSurface仍属错误其余协议语义、消息结构与 v0.9 保持一致。下文分别深入解析这两处变更及其底层证据。二、变更一A2UI 载荷 MIME 类型标准化2.1 变更内容在 v0.9 扩展规范的多轮草稿迭代中A2UI 消息载荷的 MIME 类型曾被写成application/jsona2ui。v0.9.1 将所有规范文档与扩展元数据示例统一为标准写法application/a2uijson这一写法的意义在于MIME 类型结构上应为type/subtypejson表示该类型以 JSON 为底层序列化格式即 JSON 后缀语法而application/a2ui才是类型主体。旧写法application/jsona2ui把a2ui当作json的后缀语义上是JSON 的一种变体并不符合媒体类型命名惯例。2.2 仓库中的实现证据Python Agent SDK 中对两类 MIME 类型的处理直接印证了这一变更在 agent_sdks/python/a2ui_agent/src/a2ui/a2a/parts.py 中定义了两个常量MIME_TYPE_KEY mimeType A2UI_MIME_TYPE application/a2uijson DEPRECATED_A2UI_MIME_TYPE application/jsona2ui而create_a2ui_part()在构造 A2ADataPart时会根据协议版本选择 MIME 类型mime_type A2UI_MIME_TYPE if version is None or version in (0.8, 0.9, v0.8, v0.9): mime_type DEPRECATED_A2UI_MIME_TYPE也就是说v0.9.1以及后续 v1.0的新载荷一律使用application/a2uijson旧的application/jsona2ui被标记为DEPRECATED已弃用仅用于兼容 v0.9 及更早版本。与此同时is_a2ui_part()在识别 A2UI 消息时同时接受两个值见 parts.py保证解析端不会因对方仍发送旧 MIME 类型而漏判——这是标准化但不破坏兼容的实现范本。v0.9.1 扩展规范文档同样全面采用新写法例如在 a2ui_extension_specification.md 中客户端通过message.metadata[a2uiClientCapabilities]协商 A2UI 支持Agent 返回DataPart.data.metadata[mimeType] application/a2uijson时客户端即可确认该载荷包含 A2UI 消息。Agent 侧指引 agent_development.md 亦明确要求将校验通过的载荷包装为带正确 MIME 类型application/a2uijson的 A2ADataPart并流式输出。2.3 演进脉络v1.0 的进一步确认从后续版本的演进文档可以看出这条标准化路线的延续。在 v1.0 演进指南 中v1.0 进一步将官方 MIME 类型固定为application/a2uijson以符合 IANA 媒体类型指南并给出迁移动作将传输层中 A2UI 载荷的 MIME 类型从application/jsona2ui改为application/a2uijson。这印证了 v0.9.1 的标准化决策是后续版本的一贯基线。三、变更二Surface ID 唯一性约束放宽3.1 变更内容在a2ui_protocol.md中surfaceId的定义与约束被更新为删除了surfaceId必须在 renderer 的整个生命周期内全局唯一的硬性限制保留并明确了活跃态约束对已存在的surfaceId发送createSurface而不先发送deleteSurface仍然属于协议错误。换句话说唯一性约束的作用范围从过去到现在所有曾出现过的 surface收缩为当前同时活跃active的 surfaces。一个已经删除的 surface 的 ID 可以被安全地复用。3.2 为什么放宽多 Agent 协作的现实需要在 v0.9 的Prompt First架构下一个 orchestrator编排者或会话内可能先后创建、销毁多个 UI surface尤其是多 Agent 会话多个子 Agent 先后接管界面各自创建 surface用完后删除若 ID 终身唯一客户端必须为每次会话生成单调递增的全局 ID既浪费 token又容易在长会话中撞上ID 用尽的尴尬Surface 复用模式同一类型界面如用户资料卡可能被反复打开与关闭允许复用 ID 更符合真实的交互循环。放宽为活跃唯一后实现者只需保证同一时刻不存在两个同 ID 的 surface这与创建前先检查 / 删除后再创建的直觉一致也让 agent 可以自由采用诸如user_profile_card这类语义化、可复用的命名。3.3 Schema 与协议文档中的对应证据消息 Schema 的CreateSurfaceMessage定义直接写入了这条语义见 server_to_client.jsoncreateSurface: { type: object, description: Signals the client to create a new surface and begin rendering it. It is an error to send createSurface for a surfaceId that already exists without first deleting it. ... }同时在 a2ui_protocol.md 的createSurface小节中对surfaceId的说明为surface 创建后其surfaceId与catalogId即固定若要重新配置必须先删除再重建重复对已存在的surfaceId发送createSurface属于错误。这两处表述与演进指南完全一致可作为实现与测试的判定依据。3.4 配合使用的 Surface 生命周期语义放宽唯一性约束后正确管理 Surface 生命周期变得更为关键。完整语义如下摘自 a2ui_protocol.md 的协议数据流createSurface初始化 surface在此之后才能向其发送updateComponents/updateDataModelupdateComponents为 surface 添加或更新组件组件以扁平列表 ID 邻接表组织必须存在一个id为root的组件作为树根updateDataModel随时填充或替换 surface 的数据模型path省略或为/时替换整个数据模型deleteSurface显式移除 surface 及其全部组件与数据。在多 Agent 场景中若某个 surface 已由其他 Agent 创建当前 Agent 可在知道其 ID 的情况下跳过createSurface直接发送更新消息——这与活跃唯一约束共同构成了更宽松、更实用的协作模型。四、迁移指南v0.9 到 v0.9.1 无缝升级4.1 向后兼容性保证v0.9.1与 v0.9 的载荷完全兼容这是本次迁移最重要的前提。Schema 中的version字段显式接受两个取值见 server_to_client.jsonversion: { enum: [v0.9, v0.9.1] }同样的双版本枚举也出现在 client_to_server.json 与 client_data_model.json 中。因此发送方继续输出version: v0.9的旧载荷v0.9.1 客户端可以正常解析客户端与服务器可以各自独立升级无需停机同步切换。4.2 实现者行动清单升级到 v0.9.1 的实际改动非常小核心只有一项将任何硬编码的 MIME 类型引用从application/jsona2ui更新为application/a2uijson。建议同时做三件事全仓搜索替换检索代码、配置、测试夹具与文档中的application/jsona2ui替换为新写法如前文 parts.py 所示SDK 已经以常量形式集中管理保留旧值兼容读取在解析端同时接受新旧两种 MIME 类型避免升级过程中与旧 peer 通信失败可参考is_a2ui_part()同时匹配两个常量的做法协商新版本标识若走 A2A 传输将扩展 URI 更新为https://a2ui.org/a2a-extension/a2ui/v0.9.1详见 a2ui_extension_specification.md该 URI 显式编码协议版本客户端请求该 URI 即表明支持 v0.9.1 schema 格式HTTP 传输下通过X-A2A-Extensions请求头携带gRPC 传输下通过sendMessageParams.metadata[X-A2A-Extensions]携带。4.3 版本字段的兼容陷阱需要提醒的是尽管version枚举同时接受v0.9与v0.9.1但消息内的 MIME 类型与version字段是两个独立维度。以 parts.py 的实现为例SDK 会依据传入的version决定使用新/旧 MIME 类型v0.9或更早走弃用类型v0.9.1及之后走标准类型。实现者在自定义封装时应确保新版本载荷配新 MIME 类型这一对应关系避免出现version: v0.9.1却携带旧 MIME 类型的混合状态。五、v0.9.1 协议能力速览迁移后的可用范围完成迁移后你获得的完整协议能力与 v0.9 相同核心结构如下均位于 specification/v0_9_1 目录消息信封server_to_client.json 定义四种服务端消息createSurface/updateComponents/updateDataModel/deleteSurface通过顶层oneOf严格分派并使用catalog.json#/$defs/anyComponent占位引用实现目录可替换可映射到基础目录或自有目录公共类型common_types.json 定义DynamicString等数据绑定原语、ChildList子节点模板与ComponentId引用类型基础目录catalogs/basic/catalog.json 统一定义 UI 组件Text、Button、Row、Column、List、TextField、ChoicePicker等 18 个与客户端函数required、regex、email、formatString、formatNumber、formatCurrency、formatDate、and/or/not等 14 个以及主题 schemaprimaryColor、iconUrl、agentDisplayName双向消息与能力协商client_to_server.json、client_capabilities.json、server_capabilities.json、client_data_model.json 覆盖action、error、能力公告与sendDataModel数据回传。完整的消息结构、组件模型、数据绑定绝对/相对 JSON Pointer 路径、双向绑定、formatString插值语法、以及Prompt-Generate-Validate三循环与标准VALIDATION_FAILED错误格式均可在 a2ui_protocol.md 中查阅各组件与函数的渲染实现指引见 basic_catalog_implementation_guide.md。六、结语v0.9.1 是一次小而关键的协议修订MIME 类型标准化消除了规范文档间的自相矛盾为 SDK 与传输层实现提供了唯一权威的标识符Surface ID 约束放宽则把唯一性从终身降为活跃期使多 Agent 协作下的 Surface 生命周期管理更加务实。由于版本字段天然兼容v0.9与v0.9.1任何客户端或服务器都可以在不改动消息结构、不停机的前提下完成升级——实现者真正需要做的只是把硬编码的application/jsona2ui替换为application/a2uijson。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考