[Feature Proposal] Nacos AI Registry: Agent Protocol Registration Abstraction / Nacos AI Registry Agent 协议注册抽象与可扩展架构

🌐 Background / 背景

随着AI Agent生态的快速发展，Agent之间的通信协议呈现多元化趋势。目前除了Google主导的A2A（Agent-to-Agent）协议外，业界还在积极探索其他协议标准，如：

ACP (Agent Communication Protocol) - 更轻量级的Agent交互协议
Matrix Protocol - 去中心化的Agent通信方案
其他新兴协议 - 各云厂商和开源社区正在提出的新标准

当前Nacos的Agent管理功能主要基于A2A协议实现，这种紧耦合设计限制了Nacos对多协议生态的支持能力。需要明确的是，Nacos作为注册中心，不负责Agent之间的实际通信，而是提供Agent注册、AgentCard（AgentMeta）注册、Agent发现、AgentEndpoint获取等注册中心能力。

为了适应未来Agent通信协议的多样化发展，Nacos需要向上抽象一层通用的Agent注册协议接口，支持不同协议的Agent注册元数据管理。

此外，Nacos 3.2.0发布后引入了统一的ai_resource抽象层（见#14801），现有的A2A模块以及新引入的A2A协议适配（#14621 和 #14439）也需要：

迁移到新的ai_resource管理体系
保持旧版API的结构和兼容性

📦 Current State / 当前进展

Nacos 3.2.0已完成ai-resource和ai-resource-version基础表结构设计
Agent管理当前直接依赖A2A协议实现
#14621和#14439正在推进新的A2A协议适配

🎯 Vision & Core Concepts / 愿景与核心概念

1. Protocol Abstraction for Registration / 注册协议抽象层

设计一个与具体协议无关的Agent注册抽象层，支持：

统一的Agent注册、AgentCard注册接口
Agent发现与AgentEndpoint获取
可插拔的协议适配器机制
协议元数据的规范化存储

注意：抽象层仅覆盖注册中心职责，不涉及Agent间通信协议本身。

2. Multi-Protocol Support / 多协议支持

协议	优先级	适配策略
A2A (现有)	P0	迁移至抽象层，保持兼容
A2A (新版 #14621)	P0	新适配器实现
ACP	P1	新适配器实现
Matrix	P2	社区贡献
自定义协议	P2	开放SPI扩展

3. Unified AI Resource Management / 统一AI资源管理

A2A模块迁移至ai_resource管理体系
Agent作为一类特殊的AI Resource进行生命周期管理
复用#14801定义的资源分级加载、审计追溯等能力

4. Backward Compatibility / 向后兼容

现有A2A API保持100%兼容
旧版客户端无需修改即可继续工作
通过适配器模式实现新旧协议共存

🛠 Technical Proposal / 技术方案规划

Architecture Overview / 架构概览

┌─────────────────────────────────────────────────────────────┐
│                    Agent Registration API                    │
│              (REST / gRPC / MCP Endpoint)                    │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│              Protocol Abstraction Layer                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   A2A       │  │   ACP       │  │   Matrix            │  │
│  │  Adapter    │  │  Adapter    │  │  Adapter (Future)   │  │
│  │  (Legacy)   │  │             │  │                     │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────────┴──────────┐  │
│  │  A2A New    │  │  ACP Core   │  │  Matrix Core        │  │
│  │  Adapter    │  │             │  │                     │  │
│  │  (#14621)   │  │             │  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│              AI Resource Management Layer                    │
│         (ai_resource / ai_resource_version)                  │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  ┌─────────────┐  │   Version   │  │   Audit     │        │
│  │  Agent      │  │  Control    │  │   Trail     │        │
│  │  Registry   │  └─────────────┘  └─────────────┘        │
│  │  (Metadata) │                                           │
│  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────┘

Core Capabilities / 核心能力

1. Agent Registration / Agent注册

支持不同协议的Agent注册请求
提取并标准化Agent元数据
存储Agent身份标识和协议类型

2. AgentCard Registration / AgentCard注册

管理Agent的能力描述信息（AgentCard/AgentMeta）
支持协议特定的扩展字段
版本化管理AgentCard变更

3. Agent Discovery / Agent发现

按协议类型、能力标签等条件查询Agent
支持语义化搜索（结合[Feature Proposal] Nacos AI Registry: Semantic Intelligent Retrieval / Nacos AI Registry 语义化智能检索能力规划 #14789）
返回标准化的Agent列表信息

4. AgentEndpoint Resolution / AgentEndpoint获取

根据AgentID获取可访问的Endpoint地址
支持多协议Endpoint的协商
提供Endpoint健康状态信息

2. AI Resource Integration / AI资源集成

Agent映射为ai_resource类型：RESOURCE_TYPE_AGENT
协议适配器作为资源元数据的一部分存储
复用现有资源版本控制、生命周期管理能力

3. Compatibility Layer / 兼容层

现有A2A API路由到Legacy A2A Adapter
请求/响应格式转换保持透明
支持渐进式迁移

🔍 Key Discussion Points / 核心讨论方向

AgentCard标准化：不同协议的Agent描述格式差异较大，如何定义一个兼容各协议的AgentCard标准？
协议元数据存储：各协议特有的元数据字段如何灵活存储？是否需要JSON Schema约束？
ai_resource集成方式：Agent作为独立资源类型，还是作为现有资源（如Skill）的扩展属性？
Endpoint安全暴露：AgentEndpoint可能涉及敏感网络信息，如何在服务发现中保障安全？
多协议共存：当同一个Agent支持多种协议时，注册和发现机制如何设计？
旧API兼容性边界：哪些旧API必须保持兼容？哪些可以标记为Deprecated？

🤝 Call for Discussion & Contribution / 社区讨论与贡献方向

诚邀社区参与以下方向的讨论和贡献：

架构设计：协议抽象层的职责边界、SPI扩展机制
协议适配：ACP、Matrix等协议的适配器实现
迁移方案：现有A2A模块向ai_resource迁移的具体方案
AgentCard标准：跨协议的Agent元数据标准设计
安全设计：AgentEndpoint的安全暴露和访问控制
文档规范：协议适配器开发指南和最佳实践

Agent 管理与 RAD 首版实现方向

结合 Agent 协议抽象讨论 #14804、Gateway 服务名兼容问题 #15450 和中文 Agent 名称问题 #15230，目前计划按以下方向推进首版实现。

1. 定位

将现有 A2A 管理向上抽象为通用 Agent 管理，并定义 RAD（Remote Agents Discovery）作为统一发现模型。

Nacos 负责 Agent 定义、版本、运行地址和调用元信息的注册与发现，不负责代理实际 Agent 调用，也不定义消息、任务、会话和流式调用协议。

2. 核心模型

Agent
└── AgentVersion
    └── CallInterface（首版为 A2A）

Runtime Endpoint（独立生命周期）

Agent 保存稳定身份、展示信息、标签和治理状态。
AgentVersion 保存精确版本的调用定义和生命周期，上线后首版不可原地修改。
CallInterface 保存协议类型、协议原生描述和声明 Endpoint。
Runtime Endpoint 独立注册到 Naming，允许先注册 Endpoint、后创建 Agent 或 Version。

内部存储复用：

ai_resource：Agent 资源。
ai_resource_version：版本与生命周期。
AI Storage：完整版本调用定义。
Naming：Runtime Endpoint、健康状态及连接生命周期。

agentName 作为稳定机器标识，增加可选、支持 Unicode 的 displayName。Naming 物理服务名使用可逆 ASCII 编码，只包含字母、数字和 -，保留大小写；服务名按 Agent + protocol 组织，不再包含 Version。Version 作为实例的 runtimeVersion/versionRange 保存，从而避免 Gateway URI 兼容问题和服务数量膨胀。

3. 发现模型

数据面提供两个主要动作：

Search：Agent 未知时，按名称、标签和协议搜索候选 Agent。
Discover：Agent 已知时，一次返回选定版本的调用定义以及当前可用 Endpoint。

Discover 支持精确 Version、Label 或 latest，并可按 protocol、transport、Endpoint 来源和 metadata 过滤。调用方不需要分别调用 describe、resolve 后自行拼装结果。

声明 Endpoint 来自 AgentVersion，Runtime Endpoint 来自 Naming；二者由 endpointSourceOrder 决定发现优先级。

4. 旧 A2A API 兼容

现有 Java A2aService、gRPC、Admin 和 Console API 继续保留原路径、方法和 DTO，由服务端 Adapter 转换到新模型：

AgentCard 转换为 Agent + AgentVersion + A2A CallInterface。
旧 Endpoint 注册直接转换并写入新 Runtime Endpoint Registry。
URL 类型查询返回 AgentCard 中的声明地址。
SERVICE 类型查询优先返回 Runtime Endpoint；没有运行实例时回退声明地址。
首版只有 A2A，因此旧 A2A latest 与 Agent 通用 latest 使用同一个版本指针。
已存在的同版本发布保持幂等，不提供同版本内容强制覆盖；内容冲突时返回错误。
旧 API 的新增数据执行统一的 AgentName、Version 和内容校验。

Console API 计划兼容至 3.4，Admin API 与 Maintainer SDK 计划兼容至 4.0；Java A2A Client API 的废弃时间后续单独讨论。

5. 首版范围

首版只实现 A2A，不纳入 MCP 和其他 Agent 调用协议，但模型保留后续扩展能力。

以下内容暂不进入首版：

已发布同版本的管理员应急强制更新。
历史异常 AgentName/Version 的迁移。
旧 Config、旧 Naming 数据迁移。
新旧 Server 混合集群的滚动升级方案。
实际 Agent 调用代理。

历史迁移和滚动升级将作为独立方案继续设计。

希望社区重点反馈以下几点：

Agent、AgentVersion、CallInterface 和 Runtime Endpoint 的边界是否合理。
Search + Discover 是否能够覆盖主要 Agent 发现场景。
AgentName/displayName 和新版 Naming 服务名设计是否可接受。
旧 A2A API 的兼容范围及首版暂不支持同版本覆盖是否合理。

如果整体方向没有异议，下一步将先补充 RAD、Agent 管理、内部存储和兼容相关 Specs/Schema，然后开始实现。

Agent 管理抽象与 RAD 0.1.0 方案讨论

结合 #14804、#15450、#15230，目前方案已初步收敛，希望先在社区确认模型与协议方向，再进入实现。

1. 目标与范围

本次计划将现有 A2A Agent 提升为协议无关的通用 Agent 资源，并接入统一 AI 资源模型：

ai_resource + ai_resource_version + AI Storage

同时定义 RAD（Remote Agent Discovery），负责搜索 Agent、发现调用元信息，以及注册运行时 Endpoint。

本次包含：

Agent、Agent Version、CallInterface 和 Endpoint 模型；
RAD Search、Discover、Watch、Register、Deregister；
Client、Admin、Console 和 Maintainer SDK API；
现有 A2A API 的双向兼容。

本次不包含 MCP，也不定义实际 Agent Calling。Nacos 返回调用描述和可用地址，但不代理 message、task、session 或 stream。

2. 核心模型

Agent
  └── AgentVersion
        └── AgentCallInterface
              └── DECLARED Endpoint

Runtime Publisher
  └── RUNTIME Endpoint
        └── versionRange 匹配 AgentVersion

Agent：稳定身份、展示信息、Tags、Owner、Scope 和在线版本目录。
AgentVersion：一个可治理、可发布的精确版本。
AgentCallInterface：该版本支持的一种调用协议，保存原生协议描述及 Endpoint 来源顺序。
DECLARED Endpoint：随版本定义发布的静态地址。
RUNTIME Endpoint：由运行实例动态注册，生命周期独立于 Agent Definition。
A2A 不再作为独立 Agent 类型，而是首个 Protocol Binding 和旧 API 兼容 Facade。

agentName 保持可打印 ASCII、大小写敏感和原值保存；可选 displayName 用于 Unicode 展示。Config 和 Naming 使用独立 Codec 生成物理标识，不改变公开 Agent 身份。

3. RAD 0.1.0

RAD 0.1.0 定义五个操作：

操作	请求	返回	用途
Search	`AgentSearchRequest`	`AgentCatalogPage`	搜索候选 Agent
Discover	`AgentDiscoveryRequest`	`AgentDiscoveryResult`	获取完整调用快照
Watch	`AgentDiscoveryRequest`	`AgentDiscoveryResult` 流	订阅完整替换快照
Register	`AgentEndpointRegistrationBatch`	成功或错误	注册 Runtime Endpoint
Deregister	`AgentEndpointDeregistrationBatch`	成功或错误	注销 Runtime Endpoint

协议只定义六个根对象：

AgentSearchRequest
AgentCatalogPage
AgentDiscoveryRequest
AgentDiscoveryResult
AgentEndpointRegistrationBatch
AgentEndpointDeregistrationBatch

主要规则：

Search 返回目录信息和完整在线版本列表，不返回 Descriptor 或 Endpoint。
Discover 支持精确 Version、Label 或默认 latest，并可按 Protocol、Transport、Endpoint 来源和 Metadata 过滤。
Discover 一次返回调用描述及 DECLARED、RUNTIME Endpoint，不要求调用方先 Describe 再 Resolve。
Watch 首次和后续都返回完整快照，调用方整体替换旧结果。
Runtime Endpoint 不暴露 endpointId，在 Agent Protocol 范围内使用 host + effectivePort + transport 作为自然键。
Runtime 注册支持 runtimeVersion 和 Maven/POM 风格的单个连续 versionRange。
允许先注册 Endpoint、后创建 Agent 或 Version。
同一自然 Endpoint 在所有 Publisher 和 Version Binding 下必须使用同一份 Endpoint Payload；多个兼容范围聚合到 bindings[]。
enabled=false 不进入数据面发现；healthy=false 仍然返回，由 SDK 或业务方决定是否使用。
Registry 不隐式选择唯一 Endpoint；健康过滤及 Priority/Weight 选址属于 SDK 或调用方。

4. 存储映射

Agent Metadata                  -> ai_resource
Agent Version Metadata          -> ai_resource_version
CallInterface + DECLARED        -> AI Storage
RUNTIME Endpoint                -> Naming Runtime State

内置 AI Storage 使用 Nacos Config：

group   = agent-version
dataId  = agent__<encodedAgentId>__<version>.json
content = 完整 AgentVersionContent

Runtime Endpoint 复用 Naming：

一个 agentName + protocol 对应一个 Naming Service，不按 Version 拆分；
Transport 映射为 Cluster；
Version 兼容关系存入 Instance 的 bindings[] Metadata；
Version 不进入 ServiceName，避免服务数量膨胀和 Gateway 兼容问题。

新增 rad-ascii-v1 Codec，输出仅包含 [A-Za-z0-9-] 并保留大小写；旧 AsciiAgentIdCodec 保留，用于后续历史兼容和迁移。

5. 旧 A2A API 兼容

现有 A2A API 作为新模型上的兼容层：

旧 AgentCard 写入转换为 Agent、online AgentVersion 和 protocol=a2a 的 CallInterface。
AgentCard 中的 URL 和 supported interfaces 转换为 DECLARED Endpoint。
旧 Endpoint API 转换为精确 versionRange=[version] 的 Runtime Publication。
旧查询从 Agent 模型、A2A Descriptor 和 Runtime Endpoint 反向组装原 AgentCard DTO。
首版只有 A2A Binding，因此旧 A2A latest 和通用 Agent latest 使用同一指针。
已发布的同版本内容首版不允许强制覆盖；未来如有应急需求，再设计 Owner 或管理员的受审计入口。

兼容窗口暂定：

Console A2A API 保留到 3.4.x；
Admin API 和 Maintainer SDK 保留到 4.0.x；
Java A2aService 和旧 gRPC 暂不设置删除版本。

历史数据迁移及新旧 Server 滚动升级单独设计，不混入本轮 API 兼容。

6. API 与实现计划

Client：HTTP + gRPC，提供 Search、Discover、Watch、Register、Deregister。
Admin：HTTP，提供 Agent CRUD、Version 生命周期和 Runtime Endpoint 查询。
Console：HTTP，作为 Admin 语义的 UI Facade。
普通 Client SDK 绑定 Namespace；Maintainer SDK 每次显式传入 Namespace。
HTTP Runtime Publisher 使用 X-Nacos-Client-Id，按 Client 维度心跳，并通过 Distro 路由和故障接管。

计划按以下顺序实现：

Agent、RAD、API、Storage 中英文 Specs 和内外部 Schema。
公共对象、校验、SemVer/range、Codec、Digest 和 Revision。
Agent Resource/Version 与 AI Storage。
Runtime Endpoint Registry 和 Naming 映射。
RAD 数据面与 HTTP/gRPC Client API。
Java SDK、Admin、Maintainer SDK 和 Console。
旧 A2A API 双向 Adapter。
OpenAPI IT、Java SDK IT、Maintainer SDK IT、兼容矩阵和性能基准。
单独设计滚动升级、存量迁移及混合集群行为。

对应草案路径：

specs/{zh-cn,en}/ai/agent-management-spec.md
specs/{zh-cn,en}/ai/rad-protocol-spec.md
specs/{zh-cn,en}/ai/agent-api-spec.md
specs/{zh-cn,en}/ai/agent-storage-spec.md

specs/schemas/ai/rad/0.1.0/rad-protocol.schema.json
specs/schemas/ai/agent/0.1.0/agent-management.schema.json
specs/schemas/ai/agent/internal/v1/agent-storage.schema.json

希望社区重点反馈：

将 A2A 抽象为通用 Agent 的 Protocol Binding 是否合适？
Search 与 Discover 的职责划分是否符合使用习惯？
Runtime Endpoint 使用自然键而不暴露 endpointId 是否满足注册和注销场景？
runtimeVersion + versionRange 是否足以表达实例兼容关系？
Agent Version 和 Runtime Endpoint 分别使用 AI Storage 与 Naming，是否遗漏关键运维场景？
旧 A2A API 的兼容窗口和反向投影语义是否合理？

[ISSUE #14804] Add Agent management and RAD specifications (#15545)

[ISSUE #14804] Add Agent and RAD contract models (#15551)

[ISSUE #14804] Add RAD physical identity algorithms (#15558)

[ISSUE #14804] Add Agent version fingerprints and storage adapter (#1…

[ISSUE alibaba#14804] Add Agent persistence orchestration

[ISSUE #14804] Add Agent resource persistence foundations (#15566)

[ISSUE #14804] Align Agent contracts and improve test coverage (#15569)

[ISSUE #14804] Implement Agent draft persistence (#15573)

[ISSUE #14804] Implement Agent lifecycle persistence (#15588)

[ISSUE alibaba#14804] Implement Agent lifecycle persistence (alibaba#…

[ISSUE #14804] Add historical A2A rolling-upgrade migration (#15814)

[ISSUE #14804] Improve Agent console detail workflows (#15825)

[ISSUE #14804] Restore legacy Agent A2A console workflow (#15826)

[ISSUE #14804] Align Agent draft and version history layout (#15832)

[ISSUE #14804] Add resource services and per-resource transports to t…

[ISSUE #14804] Consolidate Agent and RAD models across APIs and SDKs (#…

[ISSUE alibaba#14804] Respect auth mode in A2A migration catalog checks

[ISSUE alibaba#14804] Cover A2A RAD capability, publication and Watch…

[ISSUE #14804] Adapt A2A clients to RAD with transport negotiation (#…

[ISSUE alibaba#14804] Fix flaky A2aMigrationReconciliationTaskTest st…

[ISSUE #15876] Fix ephemeral instance never re-registered after recon…

[ISSUE #14804] Improve Agent SDK discovery and Watch reliability (#15927

[ISSUE #15799] Sync develop into summer-ospp#15799 (#15937)

[ISSUE #14804] Trace Agent Discover request origins (#15943)

[Feature Proposal] Nacos AI Registry: Agent Protocol Registration Abstraction / Nacos AI Registry Agent 协议注册抽象与可扩展架构 #14804

Description

🌐 Background / 背景

📦 Current State / 当前进展

🎯 Vision & Core Concepts / 愿景与核心概念

1. Protocol Abstraction for Registration / 注册协议抽象层

2. Multi-Protocol Support / 多协议支持

3. Unified AI Resource Management / 统一AI资源管理

4. Backward Compatibility / 向后兼容

🛠 Technical Proposal / 技术方案规划

Architecture Overview / 架构概览

Core Capabilities / 核心能力

1. Agent Registration / Agent注册

2. AgentCard Registration / AgentCard注册

3. Agent Discovery / Agent发现

4. AgentEndpoint Resolution / AgentEndpoint获取

2. AI Resource Integration / AI资源集成

3. Compatibility Layer / 兼容层

🔍 Key Discussion Points / 核心讨论方向

🤝 Call for Discussion & Contribution / 社区讨论与贡献方向

Activity

KomachiSion commented on Jul 20, 2026

Agent 管理与 RAD 首版实现方向

1. 定位

2. 核心模型

3. 发现模型

4. 旧 A2A API 兼容

5. 首版范围

KomachiSion commented on Jul 21, 2026

Agent 管理抽象与 RAD 0.1.0 方案讨论

1. 目标与范围

2. 核心模型

3. RAD 0.1.0

4. 存储映射

5. 旧 A2A API 兼容

6. API 与实现计划

30 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions