Nacos A2A Agent 绑定与兼容规范CANONICAL / LEGACY / AUTO 三模式下的 AgentCard 迁移与 RAD 适配实战【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos本文以 A2A Agent Binding 与兼容规范 为主体系统讲解 Nacos 如何把 A2AAgent2Agent协议绑定为标准的 Agent 资源AgentCallInterface并通过nacos.ai.a2a.compatibility.mode开关为历史 AgentCard API 提供兼容 facade。读完本文你将掌握 A2A 在 Nacos 中的标准身份模型、三种兼容模式CANONICAL/LEGACY/AUTO的生效逻辑、旧 AgentCard 定义与 Runtime Endpoint 写入在CANONICAL分支下的适配原理以及旧查询投影与兼容窗口的边界——可直接用于规划从历史 A2A 接口向标准 Agent/RAD 体系迁移。1. 规范定位A2A 是标准 Agent 资源的一种协议 Binding在 Nacos 的 AI 资源体系中A2A不是顶层 AI 资源类型而是标准 Agent 资源的一种协议 Binding。标准资源模型由 Agent 管理规范 定义远程发现则遵循 RAD 协议规范。因此A2A 的标准身份是一条从 namespace 到 protocol 的完整链路namespaceId - agent - agentName - version - protocola2a而历史版本使用的namespaceId - a2a - agentName身份仅用于兼容所有旧请求都会被适配到typeagent一旦启用标准写路径就不允许再创建新的a2a元数据或版本存储。规范本身的状态是实验性目标兼容契约生效条件为配置项nacos.ai.a2a.compatibility.mode默认CANONICAL。从源码结构看这一契约由ai模块下的 service/a2a 包完整实现包括模式枚举、模式解析器、兼容路由服务以及 CANONICAL / LEGACY 两套操作实现。2. 兼容模式开关CANONICAL / LEGACY / AUTO 的生效与边界2.1 三种模式的定义旧 A2A 接口通过nacos.ai.a2a.compatibility.mode选择一套完整的定义实现模式兼容实现CANONICAL标准 Agent metadata、Version 存储与 RAD Runtime Endpoint。当前版本不支持该功能的滚动升级因此默认使用此模式。LEGACY历史 AgentCard Config group 与按精确 Version 划分的 Naming Endpoint。旧实现保持不变。AUTO从LEGACY启动全部已知集群成员都上报 3.3.0 或更高版本后仅单向切换一次到CANONICAL。成员版本缺失或非法时继续使用旧分支。模式 token大小写不敏感。一次请求必须完整路由到同一分支不存在按操作混用、回退、双读或双写。AUTO只预留保守的未来切流入口不构成滚动升级保证单向切换也不会迁移历史 Config 数据。在独立迁移契约落地之前选择LEGACY或后续从LEGACY切到CANONICAL的可见性后果由运维方承担。规范第 27 节对路由到CANONICAL的请求生效路由到LEGACY的请求完整保留历史 Config 定义和按 Version 划分的 Naming Endpoint 行为。AUTO切换后使用与CANONICAL相同的完整分支。2.2 源码级实现证据模式定义在 A2aCompatibilityMode.java就是一个含CANONICAL、LEGACY、AUTO三个枚举常量的 Java enum。真正承载生效条件逻辑的是 A2aCompatibilityModeResolver.java配置项常量MODE_PROPERTY nacos.ai.a2a.compatibility.mode第 44 行默认值取CANONICAL.name()与规范一致MIN_CANONICAL_VERSION 3.3.0第 46 行对应AUTO模式中全部成员上报 3.3.0 或更高版本的判定基线parse()对配置值做trim().toUpperCase(Locale.ROOT)归一化印证了模式 token 大小写不敏感resolve()在AUTO模式下用AtomicBoolean autoCanonical记录单向、仅一次的切换supportsCanonical(allMembers())要求每个集群成员都上报 String 类型的 VERSION 且VersionUtils.compareVersion(version, 3.3.0) 0任一成员版本缺失或非法IllegalArgumentException都返回 false继续停留在LEGACY分支。请求级路由由 A2aCompatibilityOperationService.java 完成current()根据modeResolver.resolve()的结果把 register / release / update / delete / get / list 等全部历史 A2A 定义操作整体委托给A2aServerOperationServiceCANONICAL或LegacyA2aOperationServiceLEGACY从代码层面杜绝了按操作混用与双读双写。2.3 配置方式该配置项通过 Nacos 服务端标准配置渠道注入例如在 distribution/conf/application.properties 中加入nacos.ai.a2a.compatibility.modeCANONICAL取值可为CANONICAL、LEGACY或AUTO大小写不敏感。未配置时默认CANONICAL。3. A2A CallInterfacedescriptor 与字段映射A2A Binding 在标准 Agent 模型里体现为一个AgentCallInterface字段映射关系如下Agent 字段A2A 映射protocol标准 tokena2a。protocolVersion用于快速过滤的规范化 A2A 协议版本。descriptorMediaTypeAgentCard JSON 媒体类型。nativeDescriptor完整规范化 AgentCard不丢失已支持的上游字段。declaredEndpoints从 root URL 和 supported/additional interfaces 派生。endpointSourceOrder从兼容 registration type 派生。关键约束包括当前 descriptor 基线支持A2A 1.0 字段和现有0.x 兼容字段Adapter 规范化时不得用拼装出的通用 Agent 对象替换保存的 native descriptorcommon latest 精确 Version 中的 A2A CallInterface 只有通过该版本基线的完整 AgentCard 校验时才声明 ARD 表示为application/a2a-agent-cardjsonArtifact 直接返回保存的 native descriptor不得把多协议 Nacos Agent 外层对象伪装成 AgentCard旧 online Version 支持 A2A 只影响 RAD 的protocolsAnya2a如果 common latest 不含合法 AgentCard则不产生当前 A2A ARD 表示registrationTypeURL映射为[DECLARED,RUNTIME]registrationTypeSERVICE映射为[RUNTIME,DECLARED]。Registration type 是旧投影字段不参与 Agent 身份也不进入新 API。4. 旧定义写入release / Admin update 的固定规则旧 AgentCard release 和 Admin update 使用与标准 Agent API相同的 AgentName 与 Version 校验。写入成功时创建或复用 Agent 元数据行保存一个 A2A CallInterface并将目标 Version直接置为 online不引入独立的旧 draft Pipeline。固定规则务必逐条对照落地首个 online Version 总是成为latest新增后续 Version 时setAsLatesttrue移动latestfalse保留当前有效指针标准 Agent publish 或 online 操作总是移动latest删除或下线当前 latest 时选择剩余 online Agent Version 中最大的一个没有剩余版本时删除latestClient SDK 重复 release 已包含 A2A CallInterface 且 online 的精确 Version 时成功 no-op不比较或覆盖内容也不移动 latestAdmin 更新已存在精确 Version或 Client release 命中不包含 A2A CallInterface 的精确 Version 时canonical 内容不同返回冲突0.1.0 不提供同版本强制覆盖只有历史 API 已承诺幂等删除时删除不存在的 Agent 或 Version 才成功 no-op。审计要求直接上线、冲突拒绝、删除和 latest 变化必须写审计日志但不得记录完整 descriptor 或敏感 Endpoint metadata。Controller 层入口在 A2aAdminController.java/v3/admin/ai/a2a下的POSTregister、GETget、PUTupdate、DELETEdelete、GET /list分页列表、GET /version/list版本列表全部标注Secured(action ..., signType SignType.AI, apiType ApiType.ADMIN_API)即鉴权身份归属于 AI 资源类型接口标注Since(3.1.0)。5. 旧 Runtime Endpoint 写入CANONICAL 分支的 RAD Naming 适配5.1 标准 Naming layoutCANONICAL分支把旧单条、批量和注销请求适配到标准 RAD Runtime Naming layoutgroupagent-endpoints serviceNamerad-encodedAgentId-a2a runtimeVersionexactVersion versionRange[exactVersion]源码侧groupagent-endpoints对应 Constants.java 中的AGENT_ENDPOINT_GROUPrad-前缀与rad-service-name-v1的稳定命名由 RadServiceNameComposer.java 负责PREFIX rad-、COMPOSER_ID rad-service-name-v1Agent Version 有意不进入 serviceName从而让同一 Agent 的不同 Version 共享同一个标准 Service。5.2 内部子 publisher 机制核心设计旧 SDK 的 redo 和替换身份是(connection, namespaceId, agentName, exactVersion)而标准 Runtime Service 对一个 Naming publisher只保存一份完整批次。为了在两者之间无损对齐兼容层为每个旧精确 Version 创建一个确定性的内部子 publisher并把它绑定到原始 AI gRPC connection。语义如下单条注册把该子 publication 替换为一个 Endpoint批量注册以提交的完整 Batch 覆盖同一子 publication旧 deregister注销该精确 Version 的完整子 publication不同 Version 的子 publisher 写入同一个标准 Service但不会互相覆盖原始 connection 断开时其全部子 publisher 一并释放并继续复用 Naming 的 ClientData Distro、索引、事件和清理能力兼容层不得读取旧 publication 后合并。该机制在 CanonicalA2aEndpointOperationService.java 中有完整实现子 client id 采用A2A_ENDPOINT_前缀 UUID.nameUUIDFromBytes(parentClientId namespaceId agentName version)的确定性派生保证了同一精确 Version 的重连幂等同时不同 Version 之间互不冲突单批校验批内所有 Endpoint 必须属于同一个精确 Version且批量上限MAX_RUNTIME_ENDPOINTS 1000超过即返回OVER_THRESHOLDclientDisConnected只处理LABEL_MODULE_AI的 connection遍历并释放该连接注册过的全部子 publisher转换后的每个 Naming Instance 使用标准 singularruntimeVersion/versionRangemetadata旧protocolVersion和tenant仅作为 A2A 反向投影用的保留 metadata不进入公开 RAD Endpoint 或 Runtime revision旧AgentEndpoint的 URI、transport、健康与权重继续按标准 Runtime 映射校验URI 组装时默认协议取A2A_ENDPOINT_DEFAULT_PROTOCOL启用 TLS 时切换为httpsIPv6 地址自动加[]括号port/path/query 按规范拼接。5.3 LEGACY 分支与 Beta 边界LEGACY分支保持原 Handler 和legacyEncodedAgentName::exactVersionNaming Service 实现不变对应 LegacyA2aOperationService.java以便未来兼容开关需要时仍可运行。Beta 的CANONICAL分支只写标准 Service不双写旧 Service因此直接通过 Naming Gateway 发现历史 serviceName 的调用方不会看到这些新发布兼容双写、开关、回滚和旧 Service 清理由 Beta 后的独立设计处理。其余边界Endpoint 可以先于 Agent 或 Version 定义发布但不得隐式创建 Agent 定义旧 Java SDK 为每个(agentName, exactVersion)独立保存 Endpoint redo且保存调用时 Payload 的防御性快照不同 Version 的发布意图不得因重连缓存 key 冲突而丢失内部子 publisher 是服务端实现细节不进入公开 Payload、Redo key、鉴权资源或管理查询。6. 旧查询投影URL / SERVICE 两种模式的取舍兼容查询先选择一个包含合法protocola2aCallInterface 的 online Version。显式 Version 执行大小写敏感精确查询未指定时使用 Agentlatest。Client 运行时读取还要求 Agent enabled 且可见。投影规则查询模式结果URL返回保存的 native AgentCard 及其声明 interfaces。SERVICE且存在匹配 Runtime Endpoint将确定性 Runtime Endpoint 集合投影到 AgentCard interfaces 和 root URL。SERVICE且无匹配 Runtime Endpoint回退到保存的声明 AgentCard。CANONICAL查询从rad-encodedAgentId-a2a读取并按目标精确 Version 的 binding 过滤LEGACY查询继续读取旧按 Version 划分的 Service。投影细节Runtime 投影排除enabledfalse保留healthyfalse旧 DTO 没有健康字段投影先按 priority、再按 Endpoint 自然键稳定排序source revision、health、priority、weight 和通用 metadata 等 RAD 新字段不进入旧 DTO为保持线上协议兼容完整投影集合必须同时通过supportedInterfaces和历史字段additionalInterfaces返回root URL 与首选传输从同一集合中选择一个成员被选中的成员不得从additionalInterfaces中移除。订阅语义旧 list/version-list 从 Agent 元数据和 online A2A Version 投影旧订阅事件必须经过与 GET 相同的投影。初始目标不存在时旧订阅可以继续保留这是兼容行为不属于 RAD Watch 契约。exact Version 与 latest 订阅使用独立身份Version 当前是否为 latest 不能决定事件只投递给哪一个身份latest 指针切换到已有 exact Cache 时也必须触发 latest 订阅。取消后重新订阅必须恢复轮询SDK shutdown 必须停止所有旧 AgentCard 轮询任务。7. 兼容表面与演进约束7.1 兼容窗口表面状态与窗口JavaA2aService和旧 A2A gRPC Payload仅兼容当前不设删除版本。Admin/v3/admin/ai/a2a和A2aMaintainerService兼容到 4.0.x 窗口。Console/v3/console/ai/a2a兼容到 3.4.x 窗口。兼容窗口内旧路径、Payload type、DTO、能力位、鉴权身份和响应包装保持稳定。新 Agent/RAD API不得暴露registrationType、setAsLatest或 AgentCard 专属列表包装。需要特别强调的是历史数据迁移、混合版本双读双写、回滚和清理仍属于滚动升级设计不由本 API 兼容规范定义上述模式开关只选择实现不提供这些能力。7.2 演进原则上游 AgentCard 字段或 A2A 协议版本变化由 A2A Adapter 和版本化 Agent CallInterface 处理不得重新定义标准 Agent 身份或协议无关的 RAD 结果。ARD 使用的 AgentCard media type 与固定上游 Schema 基线由 AI Registry 适配器规范 共同版本化变化时必须同步更新 adapter fixture、校验器、规范和一致性测试。8. 运维决策清单基于以上契约规划 A2A 接口接入或迁移时请按以下清单决策明确当前基线确认集群各节点版本只有全部成员 ≥ 3.3.0 且显式选用时AUTO才会单向切到CANONICAL否则停留在LEGACY。理解默认行为不配置任何项时默认CANONICAL——旧接口立即走标准 Agent 元数据 Version 存储 RAD Runtime Endpoint旧调用方若通过 Naming Gateway 直接发现历史 serviceName 将看不到新发布。接受可见性后果LEGACY或从LEGACY切到CANONICAL期间无数据迁移、无双读双写切换前后的 Config 数据可见性由运维方承担。锁定兼容窗口Admin/v3/admin/ai/a2a只保障到 4.0.xConsole/v3/console/ai/a2a只保障到 3.4.x窗口内路径、Payload、DTO 与鉴权身份保持稳定JavaA2aService与旧 A2A gRPC Payload 仅兼容、不设删除版本。禁止混用请求级整体路由到单一分支不得按操作混用、回退、双读双写新 API 不暴露registrationType、setAsLatest与 AgentCard 专属列表包装。关注审计直接上线、冲突拒绝、删除和 latest 变化写审计日志但绝不记录完整 descriptor 或敏感 Endpoint metadata。围绕上述契约可进一步阅读 Agent 管理规范标准 Agent 资源模型、RAD 协议规范远程发现与 Runtime Endpoint 语义以及 AI Registry 适配器规范AgentCard media type 与 Schema 基线版本化并结合 ai 模块的 a2a 实现 与 A2aAdminController 验证各分支行为。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Nacos A2A Agent 绑定与兼容规范：CANONICAL / LEGACY / AUTO 三模式下的 AgentCard 迁移与 RAD 适配实战
Nacos A2A Agent 绑定与兼容规范CANONICAL / LEGACY / AUTO 三模式下的 AgentCard 迁移与 RAD 适配实战【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos本文以 A2A Agent Binding 与兼容规范 为主体系统讲解 Nacos 如何把 A2AAgent2Agent协议绑定为标准的 Agent 资源AgentCallInterface并通过nacos.ai.a2a.compatibility.mode开关为历史 AgentCard API 提供兼容 facade。读完本文你将掌握 A2A 在 Nacos 中的标准身份模型、三种兼容模式CANONICAL/LEGACY/AUTO的生效逻辑、旧 AgentCard 定义与 Runtime Endpoint 写入在CANONICAL分支下的适配原理以及旧查询投影与兼容窗口的边界——可直接用于规划从历史 A2A 接口向标准 Agent/RAD 体系迁移。1. 规范定位A2A 是标准 Agent 资源的一种协议 Binding在 Nacos 的 AI 资源体系中A2A不是顶层 AI 资源类型而是标准 Agent 资源的一种协议 Binding。标准资源模型由 Agent 管理规范 定义远程发现则遵循 RAD 协议规范。因此A2A 的标准身份是一条从 namespace 到 protocol 的完整链路namespaceId - agent - agentName - version - protocola2a而历史版本使用的namespaceId - a2a - agentName身份仅用于兼容所有旧请求都会被适配到typeagent一旦启用标准写路径就不允许再创建新的a2a元数据或版本存储。规范本身的状态是实验性目标兼容契约生效条件为配置项nacos.ai.a2a.compatibility.mode默认CANONICAL。从源码结构看这一契约由ai模块下的 service/a2a 包完整实现包括模式枚举、模式解析器、兼容路由服务以及 CANONICAL / LEGACY 两套操作实现。2. 兼容模式开关CANONICAL / LEGACY / AUTO 的生效与边界2.1 三种模式的定义旧 A2A 接口通过nacos.ai.a2a.compatibility.mode选择一套完整的定义实现模式兼容实现CANONICAL标准 Agent metadata、Version 存储与 RAD Runtime Endpoint。当前版本不支持该功能的滚动升级因此默认使用此模式。LEGACY历史 AgentCard Config group 与按精确 Version 划分的 Naming Endpoint。旧实现保持不变。AUTO从LEGACY启动全部已知集群成员都上报 3.3.0 或更高版本后仅单向切换一次到CANONICAL。成员版本缺失或非法时继续使用旧分支。模式 token大小写不敏感。一次请求必须完整路由到同一分支不存在按操作混用、回退、双读或双写。AUTO只预留保守的未来切流入口不构成滚动升级保证单向切换也不会迁移历史 Config 数据。在独立迁移契约落地之前选择LEGACY或后续从LEGACY切到CANONICAL的可见性后果由运维方承担。规范第 27 节对路由到CANONICAL的请求生效路由到LEGACY的请求完整保留历史 Config 定义和按 Version 划分的 Naming Endpoint 行为。AUTO切换后使用与CANONICAL相同的完整分支。2.2 源码级实现证据模式定义在 A2aCompatibilityMode.java就是一个含CANONICAL、LEGACY、AUTO三个枚举常量的 Java enum。真正承载生效条件逻辑的是 A2aCompatibilityModeResolver.java配置项常量MODE_PROPERTY nacos.ai.a2a.compatibility.mode第 44 行默认值取CANONICAL.name()与规范一致MIN_CANONICAL_VERSION 3.3.0第 46 行对应AUTO模式中全部成员上报 3.3.0 或更高版本的判定基线parse()对配置值做trim().toUpperCase(Locale.ROOT)归一化印证了模式 token 大小写不敏感resolve()在AUTO模式下用AtomicBoolean autoCanonical记录单向、仅一次的切换supportsCanonical(allMembers())要求每个集群成员都上报 String 类型的 VERSION 且VersionUtils.compareVersion(version, 3.3.0) 0任一成员版本缺失或非法IllegalArgumentException都返回 false继续停留在LEGACY分支。请求级路由由 A2aCompatibilityOperationService.java 完成current()根据modeResolver.resolve()的结果把 register / release / update / delete / get / list 等全部历史 A2A 定义操作整体委托给A2aServerOperationServiceCANONICAL或LegacyA2aOperationServiceLEGACY从代码层面杜绝了按操作混用与双读双写。2.3 配置方式该配置项通过 Nacos 服务端标准配置渠道注入例如在 distribution/conf/application.properties 中加入nacos.ai.a2a.compatibility.modeCANONICAL取值可为CANONICAL、LEGACY或AUTO大小写不敏感。未配置时默认CANONICAL。3. A2A CallInterfacedescriptor 与字段映射A2A Binding 在标准 Agent 模型里体现为一个AgentCallInterface字段映射关系如下Agent 字段A2A 映射protocol标准 tokena2a。protocolVersion用于快速过滤的规范化 A2A 协议版本。descriptorMediaTypeAgentCard JSON 媒体类型。nativeDescriptor完整规范化 AgentCard不丢失已支持的上游字段。declaredEndpoints从 root URL 和 supported/additional interfaces 派生。endpointSourceOrder从兼容 registration type 派生。关键约束包括当前 descriptor 基线支持A2A 1.0 字段和现有0.x 兼容字段Adapter 规范化时不得用拼装出的通用 Agent 对象替换保存的 native descriptorcommon latest 精确 Version 中的 A2A CallInterface 只有通过该版本基线的完整 AgentCard 校验时才声明 ARD 表示为application/a2a-agent-cardjsonArtifact 直接返回保存的 native descriptor不得把多协议 Nacos Agent 外层对象伪装成 AgentCard旧 online Version 支持 A2A 只影响 RAD 的protocolsAnya2a如果 common latest 不含合法 AgentCard则不产生当前 A2A ARD 表示registrationTypeURL映射为[DECLARED,RUNTIME]registrationTypeSERVICE映射为[RUNTIME,DECLARED]。Registration type 是旧投影字段不参与 Agent 身份也不进入新 API。4. 旧定义写入release / Admin update 的固定规则旧 AgentCard release 和 Admin update 使用与标准 Agent API相同的 AgentName 与 Version 校验。写入成功时创建或复用 Agent 元数据行保存一个 A2A CallInterface并将目标 Version直接置为 online不引入独立的旧 draft Pipeline。固定规则务必逐条对照落地首个 online Version 总是成为latest新增后续 Version 时setAsLatesttrue移动latestfalse保留当前有效指针标准 Agent publish 或 online 操作总是移动latest删除或下线当前 latest 时选择剩余 online Agent Version 中最大的一个没有剩余版本时删除latestClient SDK 重复 release 已包含 A2A CallInterface 且 online 的精确 Version 时成功 no-op不比较或覆盖内容也不移动 latestAdmin 更新已存在精确 Version或 Client release 命中不包含 A2A CallInterface 的精确 Version 时canonical 内容不同返回冲突0.1.0 不提供同版本强制覆盖只有历史 API 已承诺幂等删除时删除不存在的 Agent 或 Version 才成功 no-op。审计要求直接上线、冲突拒绝、删除和 latest 变化必须写审计日志但不得记录完整 descriptor 或敏感 Endpoint metadata。Controller 层入口在 A2aAdminController.java/v3/admin/ai/a2a下的POSTregister、GETget、PUTupdate、DELETEdelete、GET /list分页列表、GET /version/list版本列表全部标注Secured(action ..., signType SignType.AI, apiType ApiType.ADMIN_API)即鉴权身份归属于 AI 资源类型接口标注Since(3.1.0)。5. 旧 Runtime Endpoint 写入CANONICAL 分支的 RAD Naming 适配5.1 标准 Naming layoutCANONICAL分支把旧单条、批量和注销请求适配到标准 RAD Runtime Naming layoutgroupagent-endpoints serviceNamerad-encodedAgentId-a2a runtimeVersionexactVersion versionRange[exactVersion]源码侧groupagent-endpoints对应 Constants.java 中的AGENT_ENDPOINT_GROUPrad-前缀与rad-service-name-v1的稳定命名由 RadServiceNameComposer.java 负责PREFIX rad-、COMPOSER_ID rad-service-name-v1Agent Version 有意不进入 serviceName从而让同一 Agent 的不同 Version 共享同一个标准 Service。5.2 内部子 publisher 机制核心设计旧 SDK 的 redo 和替换身份是(connection, namespaceId, agentName, exactVersion)而标准 Runtime Service 对一个 Naming publisher只保存一份完整批次。为了在两者之间无损对齐兼容层为每个旧精确 Version 创建一个确定性的内部子 publisher并把它绑定到原始 AI gRPC connection。语义如下单条注册把该子 publication 替换为一个 Endpoint批量注册以提交的完整 Batch 覆盖同一子 publication旧 deregister注销该精确 Version 的完整子 publication不同 Version 的子 publisher 写入同一个标准 Service但不会互相覆盖原始 connection 断开时其全部子 publisher 一并释放并继续复用 Naming 的 ClientData Distro、索引、事件和清理能力兼容层不得读取旧 publication 后合并。该机制在 CanonicalA2aEndpointOperationService.java 中有完整实现子 client id 采用A2A_ENDPOINT_前缀 UUID.nameUUIDFromBytes(parentClientId namespaceId agentName version)的确定性派生保证了同一精确 Version 的重连幂等同时不同 Version 之间互不冲突单批校验批内所有 Endpoint 必须属于同一个精确 Version且批量上限MAX_RUNTIME_ENDPOINTS 1000超过即返回OVER_THRESHOLDclientDisConnected只处理LABEL_MODULE_AI的 connection遍历并释放该连接注册过的全部子 publisher转换后的每个 Naming Instance 使用标准 singularruntimeVersion/versionRangemetadata旧protocolVersion和tenant仅作为 A2A 反向投影用的保留 metadata不进入公开 RAD Endpoint 或 Runtime revision旧AgentEndpoint的 URI、transport、健康与权重继续按标准 Runtime 映射校验URI 组装时默认协议取A2A_ENDPOINT_DEFAULT_PROTOCOL启用 TLS 时切换为httpsIPv6 地址自动加[]括号port/path/query 按规范拼接。5.3 LEGACY 分支与 Beta 边界LEGACY分支保持原 Handler 和legacyEncodedAgentName::exactVersionNaming Service 实现不变对应 LegacyA2aOperationService.java以便未来兼容开关需要时仍可运行。Beta 的CANONICAL分支只写标准 Service不双写旧 Service因此直接通过 Naming Gateway 发现历史 serviceName 的调用方不会看到这些新发布兼容双写、开关、回滚和旧 Service 清理由 Beta 后的独立设计处理。其余边界Endpoint 可以先于 Agent 或 Version 定义发布但不得隐式创建 Agent 定义旧 Java SDK 为每个(agentName, exactVersion)独立保存 Endpoint redo且保存调用时 Payload 的防御性快照不同 Version 的发布意图不得因重连缓存 key 冲突而丢失内部子 publisher 是服务端实现细节不进入公开 Payload、Redo key、鉴权资源或管理查询。6. 旧查询投影URL / SERVICE 两种模式的取舍兼容查询先选择一个包含合法protocola2aCallInterface 的 online Version。显式 Version 执行大小写敏感精确查询未指定时使用 Agentlatest。Client 运行时读取还要求 Agent enabled 且可见。投影规则查询模式结果URL返回保存的 native AgentCard 及其声明 interfaces。SERVICE且存在匹配 Runtime Endpoint将确定性 Runtime Endpoint 集合投影到 AgentCard interfaces 和 root URL。SERVICE且无匹配 Runtime Endpoint回退到保存的声明 AgentCard。CANONICAL查询从rad-encodedAgentId-a2a读取并按目标精确 Version 的 binding 过滤LEGACY查询继续读取旧按 Version 划分的 Service。投影细节Runtime 投影排除enabledfalse保留healthyfalse旧 DTO 没有健康字段投影先按 priority、再按 Endpoint 自然键稳定排序source revision、health、priority、weight 和通用 metadata 等 RAD 新字段不进入旧 DTO为保持线上协议兼容完整投影集合必须同时通过supportedInterfaces和历史字段additionalInterfaces返回root URL 与首选传输从同一集合中选择一个成员被选中的成员不得从additionalInterfaces中移除。订阅语义旧 list/version-list 从 Agent 元数据和 online A2A Version 投影旧订阅事件必须经过与 GET 相同的投影。初始目标不存在时旧订阅可以继续保留这是兼容行为不属于 RAD Watch 契约。exact Version 与 latest 订阅使用独立身份Version 当前是否为 latest 不能决定事件只投递给哪一个身份latest 指针切换到已有 exact Cache 时也必须触发 latest 订阅。取消后重新订阅必须恢复轮询SDK shutdown 必须停止所有旧 AgentCard 轮询任务。7. 兼容表面与演进约束7.1 兼容窗口表面状态与窗口JavaA2aService和旧 A2A gRPC Payload仅兼容当前不设删除版本。Admin/v3/admin/ai/a2a和A2aMaintainerService兼容到 4.0.x 窗口。Console/v3/console/ai/a2a兼容到 3.4.x 窗口。兼容窗口内旧路径、Payload type、DTO、能力位、鉴权身份和响应包装保持稳定。新 Agent/RAD API不得暴露registrationType、setAsLatest或 AgentCard 专属列表包装。需要特别强调的是历史数据迁移、混合版本双读双写、回滚和清理仍属于滚动升级设计不由本 API 兼容规范定义上述模式开关只选择实现不提供这些能力。7.2 演进原则上游 AgentCard 字段或 A2A 协议版本变化由 A2A Adapter 和版本化 Agent CallInterface 处理不得重新定义标准 Agent 身份或协议无关的 RAD 结果。ARD 使用的 AgentCard media type 与固定上游 Schema 基线由 AI Registry 适配器规范 共同版本化变化时必须同步更新 adapter fixture、校验器、规范和一致性测试。8. 运维决策清单基于以上契约规划 A2A 接口接入或迁移时请按以下清单决策明确当前基线确认集群各节点版本只有全部成员 ≥ 3.3.0 且显式选用时AUTO才会单向切到CANONICAL否则停留在LEGACY。理解默认行为不配置任何项时默认CANONICAL——旧接口立即走标准 Agent 元数据 Version 存储 RAD Runtime Endpoint旧调用方若通过 Naming Gateway 直接发现历史 serviceName 将看不到新发布。接受可见性后果LEGACY或从LEGACY切到CANONICAL期间无数据迁移、无双读双写切换前后的 Config 数据可见性由运维方承担。锁定兼容窗口Admin/v3/admin/ai/a2a只保障到 4.0.xConsole/v3/console/ai/a2a只保障到 3.4.x窗口内路径、Payload、DTO 与鉴权身份保持稳定JavaA2aService与旧 A2A gRPC Payload 仅兼容、不设删除版本。禁止混用请求级整体路由到单一分支不得按操作混用、回退、双读双写新 API 不暴露registrationType、setAsLatest与 AgentCard 专属列表包装。关注审计直接上线、冲突拒绝、删除和 latest 变化写审计日志但绝不记录完整 descriptor 或敏感 Endpoint metadata。围绕上述契约可进一步阅读 Agent 管理规范标准 Agent 资源模型、RAD 协议规范远程发现与 Runtime Endpoint 语义以及 AI Registry 适配器规范AgentCard media type 与 Schema 基线版本化并结合 ai 模块的 a2a 实现 与 A2aAdminController 验证各分支行为。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 mixin 怎么给自定义控件添加与 button、input 一致的样式与尺寸？)
