尧图网页设计 
Nacos Agent 管理规范解读协议中立的 Agent 资源模型、版本生命周期与 A2A 兼容边界【免费下载链接】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本指南基于 Nacos AI Registry 的 Agent Management Spec系统讲解 Nacos 对 AI Agent 的协议中立管理模型从身份定义、版本治理、CallInterface 与 Endpoint 建模到管理读模型、容量安全约束以及旧 A2A 接口的兼容迁移边界。读完本文你将掌握 Agent 资源在 Nacos 中如何被建模、校验、发布与查询并能对照仓库源码ai模块理解每一步校验与状态流转的落地实现。1. 定位与范围Agent 管理模型在 Nacos AI Registry 中的位置Agent Management Spec 是 Nacos AI Registry 对 Agent 的协议中立管理模型protocol-neutral management model它细化了三个上游契约AI Resource Model Spec定义通用的元数据行AiResource与版本行AiResourceVersionAI Resource Lifecycle Spec定义draft/reviewing/reviewed/online/offline通用生命周期Naming 相关规范承载运行时端点发布。同时它声明这是 Agent 模型迁移的规范性目标契约normative target contract。在对应行为实现之前服务器与 SDK 不得对外宣告该能力当前运行时契约仍然是 A2A Agent Spec。模型按生命周期与事实来源将 Agent 拆分为三个互不拥有的事实Agent 1 --- N AgentVersion 1 --- N AgentCallInterface 1 --- N DECLARED Endpoint Runtime publisher --- N RUNTIME Endpoint RUNTIME Endpoint --- versionRange match --- AgentVersion AgentCallInterface事实职责事实来源Agent稳定身份、目录元数据、归属、可见性与版本治理ai_resourceAgentVersion一份带版本号的调用定义仅 draft 阶段可变ai_resource_version与 AI StorageAgentCallInterface一种协议绑定及其声明的地址AgentVersionContentRuntimeEndpoint存活发布者的可调用地址与兼容版本范围Naming 运行时状态关键边界A2A 是首个协议适配器公共 Agent 模型不得包含A2A 专属的 capability、skill、security、task、message 字段这些字段留在协议原生描述符中。本规范也不定义 MCP 资源或真实远程调用——Nacos 只返回调用元数据不代理 Agent 消息、任务、会话、流、重试或凭据。Search / Discover / Watch 与运行时发布线上对象由 RAD Protocol Spec 定义运行时发布的归属、物理存储、Naming 映射、编解码与修订算法由 Agent Storage Spec 定义。2. 身份与校验agentName、Version 与 Endpoint 的三套规则2.1 Agent 身份规范 Agent 身份为namespaceId resourceTypeagent agentNameagentName即公共resourceName规则严格1 到 64 个可打印 ASCII 字符U0020..U007E至少包含一个非空格字符按提交原样存储大小写敏感服务器不得 trim、转小写、slug 化或改写创建后不可变。displayName是可选 Unicode 展示字段仅在agentName缺失或空白时用于展示它绝不参与身份、授权、存储键或端点匹配。精确查询比较原始agentName过滤语义属于对应 API 绑定——RAD Search 用字面子串匹配初始 Admin 列表复用共享的 AI Resource 模糊名称查询不新增 Agent 专属持久化算子。源码侧AgentValidationUtils 中MAX_AGENT_NAME_LENGTH 64validateAgentName对空值与长度进行强制校验AgentOperationService 在创建首版 draft 时用toInitialAgent构造 Agent身份缺失时以DEFAULT_OWNER nacos作为 owner见createDraft实现。2.2 Version 身份Agent Version 身份为namespaceId resourceTypeagent agentName versionversion使用MAJOR.MINOR.PATCH[-PRERELEASE]最长 64 字符MAJOR/MINOR/PATCH为0或正整数不允许前导零PRERELEASE为一个或多个点分隔的[0-9A-Za-z-]标识符纯数字标识符无前导零不接受引入的构建元数据原值存储大小写敏感比较所有 Agent 写路径含兼容门面都应用这些规则。版本优先级比较先按 major/minor/patch 数值比较发布版高于其预发布版预发布标识符从左到右比较数字标识符按数值序且低于非数字标识符非数字标识符按大小写敏感 ASCII 序其余相等时更长的序列更高。这正是 AgentVersionComparator 的实现逻辑它先用AgentValidationUtils.validateVersion校验语法再用内部ParsedVersionBigInteger数值比较 PrereleaseIdentifier规则完成优先级排序。版本标签匹配[A-Za-z0-9][A-Za-z0-9._-]{0,63}大小写敏感latest是服务器管理的保留指针不能通过自定义标签写入创建、替换或删除。2.3 Endpoint 身份DECLARED 与 RUNTIME 共享同一个Endpoint值对象。在一个 Agent 协议组内其自然身份为(namespaceId, agentName, protocol, normalizedHost(uri), effectivePort(uri), normalizedTransport)没有公共endpointId。URI path、query、metadata、priority、weight不参与身份同一发布者可更新它们。3. Agent 资源目录元数据字段与不变量Agent 资源字段如下字段必填含义namespaceId是Nacos 命名空间隔离边界1 到 128 个[A-Za-z0-9_-]字符agentName是稳定公共身份displayName否Unicode 展示名description否目录描述iconUrl否目录图标 URIprovider否提供方name与url不是管理 ownertags[]否公共目录标签RAD Search 精确匹配extensions否命名空间化的MapString, JsonValue公共扩展status是enable或disableowner是管理归属者scope是共享可见性范围本版本为PUBLIC或PRIVATEversionInfo只读共享的 editing / reviewing / online-count / labels 摘要versionCatalog只读在线版本与协议的紧凑目录metaVersion只读与 AI Resource 模型共享的单调元数据修订初始 Admin API 不暴露条件写参数createTime、updateTime只读审计时间戳不变量Agent 元数据不内嵌协议描述符、端点、健康状态或完整版本历史tags是本版本唯一的公共通用分类列表extensions不影响身份、授权、版本选择、端点选择或默认搜索且不得包含凭据或服务器内部状态更新目录或扩展字段推进metaVersion但不创建 Agent Version协议适配器仅在 Agent首次创建时可用原生描述符初始化缺失目录字段后续描述符更新不得覆盖独立治理的 Agent 元数据。versionCatalog含latestVersion与onlineVersions[]每个在线条目仅含version、labels[]、protocols[]由服务器派生非客户端可写事实。4. Agent Version 与生命周期从 draft 到 online 的完整流转4.1 Version 元数据与内容Agent Version 元数据字段必填含义namespaceId、agentName、version是精确版本身份status是共享 AI Resource 版本状态callInterfaces[]是有序协议绑定至少一个author否版本作者changeDescription否版本变更说明contentDigest只读持久化 Version 内容字节的 SHA-256 摘要createTime、updateTime只读审计时间戳完整存储载荷是一个AgentVersionContent对象AgentVersionContent kind AgentVersionContent schemaVersion 1 callInterfaces[]服务器将校验后的对象以 UTF-8 JSON序列化一次同一份字节既持久化、计为size、又哈希为sha256:lowercase hex。读取时对 AI Storage 返回的字节直接校验摘要不重新序列化。对应实现见 AgentVersionContentSerializerserialize先validate校验kind、schemaVersion、callInterfaces1~16 个、协议去重再通过toStorageProjection生成存储投影Endpoint 经EndpointCanonicalizer.canonicalize规范化缺省priority0、weight1最后用digest计算 SHA-256MAX_CONTENT_SIZE 1024 * 1024即 1 MiB 上限。模型类见 AgentVersionContent。4.2 生命周期规则draft 创建是资源创建与版本创建的共同入口若 Agent 元数据不存在创建 draft 同时创建ai_resource元数据。首版 draft 必须包含直接callInterfacesbasedOnVersion无效不存在源 Version。可选目录元数据从同一次请求初始化。服务器派生启用状态、当前 owner 与默认 scope当请求上下文无身份如认证关闭时以nacos为 owner若 Agent 元数据已存在draft 创建遵循普通编辑槽位规则接受直接内容或一个精确源 Version目录元数据属于 Agent 更新生命周期后续 draft 请求不接受。本版本没有独立的仅元数据或createAgent操作首次与后续 draft 创建都返回AgentVersionDetail。源码中createDraftAgentOperationService精确区分meta null走createInitialDraft要求requireInitialDraftContent与已存在两种情况并幂等重试。Agent Version 使用共享生命周期状态内容可改可被普通 RAD 发现draft是否reviewing否否reviewed否否online否是offline否否ai_resource_version.status是生命周期事实来源publishPipelineInfo仅记录评审执行与结果。一个 Agent 最多同时有一个编辑版本和一个评审版本。内容在 draft 进入 reviewing 时冻结reviewed / online / offline 内容不得原地更新本版本契约不提供强制同版本内容替换操作。源码生命周期操作集中在 AgentAdminController/draft、/submit、/publish、/force-publish、/redraft、/online、/offline、/labels业务逻辑在AgentOperationServicesubmit在无 Pipeline 时直接transitionToOnline否则moveToReviewing后startPipelinepublish要求reviewed且 PipelineAPPROVEDrequireApprovedPipelineforcePublish仅接受draft/reviewing/reviewedonline/offline分别限定offline/online状态。4.3 latest 标签的服务器管理规则latest是服务器管理的标签必须始终指向 online 版本。Agent 专属规则细化了公共 AI 生命周期规则每次成功的标准 publish 或 online 迁移其目标 Version 成为latest旧 A2A 发布携带setAsLatestfalse是初始版本中唯一例外保留当前有效latest发布首个 online Version 即使走兼容路径也会建立latest删除或下线当前latest时选择剩余 online 版本中 SemVer 最大者移除最后一个 online 版本时移除latest删除或下线非当前latest的 online 版本不触发重算。每当 online 状态或标签变化服务器必须将versionCatalog作为一次逻辑更新重建存在至少一个 online 版本时必须恰好存在一个有效latestVersion且出现在onlineVersions中。该逻辑由 AgentVersionCatalogBuilder 实现按AgentVersionComparator降序排序在线版本修复缺失/陈旧的latest指向最大在线版本并生成只读目录条目。4.4 生命周期解耦与搜索索引Agent 元数据、Agent Version 定义、Runtime Endpoint互不拥有对方生命周期删除或禁用 Agent 定义只改变读投影不删除仍存活的运行时发布者状态。Agent 目录 Search 文档是可重建的派生状态不是另一个事实来源。以下成功提交按(namespaceId, agent, agentName)调度一次合并的search_index任务Agent 创建、目录元数据或治理更新、Version 发布/上线/下线/删除、common-latest 或自定义标签变化、经旧 A2A 门面的规范定义变化、Agent 删除。任务重新读取当前事实投影 common latest 与完整在线版本目录连续变化只推进任务修订。Runtime Endpoint 注册/注销、Publisher 心跳、健康状态、Runtime 修订不调度该任务也绝不进入 Agent 目录索引调度失败不回滚已成功的生命周期操作持久化任务重试与 Reconciliation 按 AI Resource Search Spec 收敛。Agent 不存在、禁用或没有 online 版本时删除派生文档是正确索引结果。5. CallInterface 与声明的端点5.1 AgentCallInterface每个 Agent Version 含有序非空callInterfaces[]每项字段字段必填含义protocol是规范协议 tokenVersion 内唯一protocolVersion否快速协议协商值不是接口身份descriptorMediaType是nativeDescriptor的媒体类型nativeDescriptor是完整协议原生描述符endpointSourceOrder[]是非空有序集合RUNTIME与DECLAREDdeclaredEndpoints[]否适配器派生的静态端点投影规范协议 token 匹配[A-Za-z0-9][A-Za-z0-9-]{0,31}大小写敏感比较同一 token 用于 CallInterface 唯一性、端点发布、RAD 过滤与 Naming 服务组合。callInterfaces[]的顺序是默认协议偏好重排列表会改变contentDigest第一个具有可用端点的接口是 SDK 默认选择候选。endpointSourceOrder无重复语义如下[RUNTIME, DECLARED]优先存活地址声明地址作回退[DECLARED, RUNTIME]优先声明地址[RUNTIME]或[DECLARED]普通发现中只允许该来源。来源顺序属于单个 CallInterface不属于整个 Version它不阻止运行时发布管理查询即使某 CallInterface 省略RUNTIME也可检查 Runtime Endpoint。5.2 Endpoint 值对象字段必填含义uri是完整可调用 URItransport是规范传输 tokenpriority否数值越小优先级越高weight否同优先级端点间的负载权重metadata否扁平 zone / environment />namespaceId / agentName / protocol / version? items[] { endpoint, bindings[] { runtimeVersion, versionRange }, state, enabled, healthy, lastUpdatedTime } state AVAILABLE | DISABLED | UNHEALTHY状态评估有序enabledfalse为DISABLED否则healthyfalse为UNHEALTHY其余为AVAILABLE。lastUpdatedTime是构建快照所用 NamingServiceInfo投影的lastRefTime同一快照内所有 item 共享同一投影观察时间——它不是逐端点的分布式事实或缓存校验器可能随 Naming 重建而变跨节点相等性与 watch 去重使用内容派生的sourceRevision。protocol必填。不带version时快照按该协议自然 Endpoint 键给出每个有效 item 及全部 Version 绑定带version时只保留匹配绑定无剩余绑定时省略该 item缺失实例产生空items[]。快照不应用endpointSourceOrder也不声称某个 item 可发现控制台只把 Version 详情与快照作为分离的读事实组合。RAD 的AgentDiscoveryResult将一份 online Version 定义与允许的 DECLARED/RUNTIME 端点集组合但它永不作为事实存储。7. 容量与安全写前强制限制写入 Agent 或 Version 事实前强制以下限制字段限制displayName、provider.name128 个 Unicode 码点description2048 字符Icon、provider 或声明端点 URI2048 字符公共 tags32 项每项 64 字符Agentextensions32 项键 128 字符序列化 UTF-8 JSON 总计 16 KiBprotocol、protocolVersion32 与 64 字符每 Version CallInterfaces16每 CallInterface 声明端点64Endpoint metadata32 项键 64、值 256 字符AgentVersionContent1 MiBbiz_tags只存用户提供的公共 tags不含服务器派生索引序列化 JSON 不得超过 1024 字符。描述符、extensions、Endpoint metadata 不得含明文凭据审计记录不得记录完整原生描述符、安全方案或敏感 Endpoint 元数据。运行时发布与物理存储限制由 Agent Storage Spec 定义。源码佐证AgentVersionContentSerializer 以MAX_CALL_INTERFACES 16、MAX_CONTENT_SIZE 1024*1024强制执行AgentResourceExt见 AgentResourceExt以 schemaVersion1 承载displayName/iconUrl/provider/extensions/versionCatalog其中extensions为MapString, Object即规范中的命名空间化扩展。8. A2A 兼容边界旧 API 作为新模型的门面迁移后旧 A2A API 是 Agent 模型之上的兼容门面不创建第二个 AgentCard 事实来源A2A 值Agent 模型投影AgentCard name 与 versionagentName与 Agent Version 身份完整 AgentCardA2A CallInterfacenativeDescriptorA2A 协议版本CallInterfaceprotocolVersion与原生描述符Root URL 与 supported/additional interfaces适配器派生的声明端点registrationTypeURL声明优先的来源顺序registrationTypeSERVICE运行时优先的来源顺序运行时 A2A 端点版本runtimeVersion与精确[version]范围首个实现只支持 A2A 协议因此旧 A2A latest 与公共 Agent latest 使用同一标签。适配器从原生描述符与适用端点投影重建旧查询 DTOURL 风格读取用声明地址service 风格读取用运行时地址无运行时地址时以声明地址作为兼容回退。通过旧 API 的新写入同样适用本规范的身份、Version、不可变性与容量规则它们可使用审计的内部 direct-online 迁移以保留 code-first A2A 发布但不得覆盖已发布 Version 中不同的内容。源码中registerLegacyOnlineVersion、releaseLegacyOnlineVersion、updateLegacyOnlineVersion、deleteLegacyVersionIfPresent、deleteLegacyAgentIfPresentAgentOperationService就是这一门面的落地它们校验后走createInitialOnlineVersion/createOnlineVersion/directOnlineExistingAgent内容不一致时以RESOURCE_CONFLICT拒绝覆盖且对已 online 的精确版本在setAsLatestfalse时保持latest不变。历史 Config 行、历史 Naming 布局、混合版本集群双读/双写、源切换、回滚与畸形历史身份属于独立的滚动升级与数据迁移契约不被本目标模型放宽。9. 与相邻资源的关系与展望Agent 与 AgentSpec 资源可通过通用资源关系互相引用但互不拥有对方生命周期。本版本不新增 Agent 专属的sourceRef、defaultInterfaceId、interfaceId、descriptorDigest或随机 Endpoint 标识符。AI Registry 有意以版本为中心——AI 资产的变化速度常快于应用配置或服务发现数据元数据/版本分离的模型让新资源类型能够复用同一套治理能力。若上游 AI 标准演进使现有模型不安全或有误导性规范将随明确的迁移与兼容规则演化参见 AI Resource Model Spec 的演进说明。延伸阅读生命周期通用规则AI Resource Lifecycle Spec存储、Naming 映射与sourceRevisionAgent Storage Spec数据面消息定义RAD Protocol Spec迁移前运行时契约A2A Agent Spec核心实现AgentOperationService、AgentAdminController、AgentVersionContentSerializer、AgentVersionCatalogBuilder、AgentVersionComparator【免费下载链接】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 Agent 管理规范解读：协议中立的 Agent 资源模型、版本生命周期与 A2A 兼容边界
Nacos Agent 管理规范解读协议中立的 Agent 资源模型、版本生命周期与 A2A 兼容边界【免费下载链接】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本指南基于 Nacos AI Registry 的 Agent Management Spec系统讲解 Nacos 对 AI Agent 的协议中立管理模型从身份定义、版本治理、CallInterface 与 Endpoint 建模到管理读模型、容量安全约束以及旧 A2A 接口的兼容迁移边界。读完本文你将掌握 Agent 资源在 Nacos 中如何被建模、校验、发布与查询并能对照仓库源码ai模块理解每一步校验与状态流转的落地实现。1. 定位与范围Agent 管理模型在 Nacos AI Registry 中的位置Agent Management Spec 是 Nacos AI Registry 对 Agent 的协议中立管理模型protocol-neutral management model它细化了三个上游契约AI Resource Model Spec定义通用的元数据行AiResource与版本行AiResourceVersionAI Resource Lifecycle Spec定义draft/reviewing/reviewed/online/offline通用生命周期Naming 相关规范承载运行时端点发布。同时它声明这是 Agent 模型迁移的规范性目标契约normative target contract。在对应行为实现之前服务器与 SDK 不得对外宣告该能力当前运行时契约仍然是 A2A Agent Spec。模型按生命周期与事实来源将 Agent 拆分为三个互不拥有的事实Agent 1 --- N AgentVersion 1 --- N AgentCallInterface 1 --- N DECLARED Endpoint Runtime publisher --- N RUNTIME Endpoint RUNTIME Endpoint --- versionRange match --- AgentVersion AgentCallInterface事实职责事实来源Agent稳定身份、目录元数据、归属、可见性与版本治理ai_resourceAgentVersion一份带版本号的调用定义仅 draft 阶段可变ai_resource_version与 AI StorageAgentCallInterface一种协议绑定及其声明的地址AgentVersionContentRuntimeEndpoint存活发布者的可调用地址与兼容版本范围Naming 运行时状态关键边界A2A 是首个协议适配器公共 Agent 模型不得包含A2A 专属的 capability、skill、security、task、message 字段这些字段留在协议原生描述符中。本规范也不定义 MCP 资源或真实远程调用——Nacos 只返回调用元数据不代理 Agent 消息、任务、会话、流、重试或凭据。Search / Discover / Watch 与运行时发布线上对象由 RAD Protocol Spec 定义运行时发布的归属、物理存储、Naming 映射、编解码与修订算法由 Agent Storage Spec 定义。2. 身份与校验agentName、Version 与 Endpoint 的三套规则2.1 Agent 身份规范 Agent 身份为namespaceId resourceTypeagent agentNameagentName即公共resourceName规则严格1 到 64 个可打印 ASCII 字符U0020..U007E至少包含一个非空格字符按提交原样存储大小写敏感服务器不得 trim、转小写、slug 化或改写创建后不可变。displayName是可选 Unicode 展示字段仅在agentName缺失或空白时用于展示它绝不参与身份、授权、存储键或端点匹配。精确查询比较原始agentName过滤语义属于对应 API 绑定——RAD Search 用字面子串匹配初始 Admin 列表复用共享的 AI Resource 模糊名称查询不新增 Agent 专属持久化算子。源码侧AgentValidationUtils 中MAX_AGENT_NAME_LENGTH 64validateAgentName对空值与长度进行强制校验AgentOperationService 在创建首版 draft 时用toInitialAgent构造 Agent身份缺失时以DEFAULT_OWNER nacos作为 owner见createDraft实现。2.2 Version 身份Agent Version 身份为namespaceId resourceTypeagent agentName versionversion使用MAJOR.MINOR.PATCH[-PRERELEASE]最长 64 字符MAJOR/MINOR/PATCH为0或正整数不允许前导零PRERELEASE为一个或多个点分隔的[0-9A-Za-z-]标识符纯数字标识符无前导零不接受引入的构建元数据原值存储大小写敏感比较所有 Agent 写路径含兼容门面都应用这些规则。版本优先级比较先按 major/minor/patch 数值比较发布版高于其预发布版预发布标识符从左到右比较数字标识符按数值序且低于非数字标识符非数字标识符按大小写敏感 ASCII 序其余相等时更长的序列更高。这正是 AgentVersionComparator 的实现逻辑它先用AgentValidationUtils.validateVersion校验语法再用内部ParsedVersionBigInteger数值比较 PrereleaseIdentifier规则完成优先级排序。版本标签匹配[A-Za-z0-9][A-Za-z0-9._-]{0,63}大小写敏感latest是服务器管理的保留指针不能通过自定义标签写入创建、替换或删除。2.3 Endpoint 身份DECLARED 与 RUNTIME 共享同一个Endpoint值对象。在一个 Agent 协议组内其自然身份为(namespaceId, agentName, protocol, normalizedHost(uri), effectivePort(uri), normalizedTransport)没有公共endpointId。URI path、query、metadata、priority、weight不参与身份同一发布者可更新它们。3. Agent 资源目录元数据字段与不变量Agent 资源字段如下字段必填含义namespaceId是Nacos 命名空间隔离边界1 到 128 个[A-Za-z0-9_-]字符agentName是稳定公共身份displayName否Unicode 展示名description否目录描述iconUrl否目录图标 URIprovider否提供方name与url不是管理 ownertags[]否公共目录标签RAD Search 精确匹配extensions否命名空间化的MapString, JsonValue公共扩展status是enable或disableowner是管理归属者scope是共享可见性范围本版本为PUBLIC或PRIVATEversionInfo只读共享的 editing / reviewing / online-count / labels 摘要versionCatalog只读在线版本与协议的紧凑目录metaVersion只读与 AI Resource 模型共享的单调元数据修订初始 Admin API 不暴露条件写参数createTime、updateTime只读审计时间戳不变量Agent 元数据不内嵌协议描述符、端点、健康状态或完整版本历史tags是本版本唯一的公共通用分类列表extensions不影响身份、授权、版本选择、端点选择或默认搜索且不得包含凭据或服务器内部状态更新目录或扩展字段推进metaVersion但不创建 Agent Version协议适配器仅在 Agent首次创建时可用原生描述符初始化缺失目录字段后续描述符更新不得覆盖独立治理的 Agent 元数据。versionCatalog含latestVersion与onlineVersions[]每个在线条目仅含version、labels[]、protocols[]由服务器派生非客户端可写事实。4. Agent Version 与生命周期从 draft 到 online 的完整流转4.1 Version 元数据与内容Agent Version 元数据字段必填含义namespaceId、agentName、version是精确版本身份status是共享 AI Resource 版本状态callInterfaces[]是有序协议绑定至少一个author否版本作者changeDescription否版本变更说明contentDigest只读持久化 Version 内容字节的 SHA-256 摘要createTime、updateTime只读审计时间戳完整存储载荷是一个AgentVersionContent对象AgentVersionContent kind AgentVersionContent schemaVersion 1 callInterfaces[]服务器将校验后的对象以 UTF-8 JSON序列化一次同一份字节既持久化、计为size、又哈希为sha256:lowercase hex。读取时对 AI Storage 返回的字节直接校验摘要不重新序列化。对应实现见 AgentVersionContentSerializerserialize先validate校验kind、schemaVersion、callInterfaces1~16 个、协议去重再通过toStorageProjection生成存储投影Endpoint 经EndpointCanonicalizer.canonicalize规范化缺省priority0、weight1最后用digest计算 SHA-256MAX_CONTENT_SIZE 1024 * 1024即 1 MiB 上限。模型类见 AgentVersionContent。4.2 生命周期规则draft 创建是资源创建与版本创建的共同入口若 Agent 元数据不存在创建 draft 同时创建ai_resource元数据。首版 draft 必须包含直接callInterfacesbasedOnVersion无效不存在源 Version。可选目录元数据从同一次请求初始化。服务器派生启用状态、当前 owner 与默认 scope当请求上下文无身份如认证关闭时以nacos为 owner若 Agent 元数据已存在draft 创建遵循普通编辑槽位规则接受直接内容或一个精确源 Version目录元数据属于 Agent 更新生命周期后续 draft 请求不接受。本版本没有独立的仅元数据或createAgent操作首次与后续 draft 创建都返回AgentVersionDetail。源码中createDraftAgentOperationService精确区分meta null走createInitialDraft要求requireInitialDraftContent与已存在两种情况并幂等重试。Agent Version 使用共享生命周期状态内容可改可被普通 RAD 发现draft是否reviewing否否reviewed否否online否是offline否否ai_resource_version.status是生命周期事实来源publishPipelineInfo仅记录评审执行与结果。一个 Agent 最多同时有一个编辑版本和一个评审版本。内容在 draft 进入 reviewing 时冻结reviewed / online / offline 内容不得原地更新本版本契约不提供强制同版本内容替换操作。源码生命周期操作集中在 AgentAdminController/draft、/submit、/publish、/force-publish、/redraft、/online、/offline、/labels业务逻辑在AgentOperationServicesubmit在无 Pipeline 时直接transitionToOnline否则moveToReviewing后startPipelinepublish要求reviewed且 PipelineAPPROVEDrequireApprovedPipelineforcePublish仅接受draft/reviewing/reviewedonline/offline分别限定offline/online状态。4.3 latest 标签的服务器管理规则latest是服务器管理的标签必须始终指向 online 版本。Agent 专属规则细化了公共 AI 生命周期规则每次成功的标准 publish 或 online 迁移其目标 Version 成为latest旧 A2A 发布携带setAsLatestfalse是初始版本中唯一例外保留当前有效latest发布首个 online Version 即使走兼容路径也会建立latest删除或下线当前latest时选择剩余 online 版本中 SemVer 最大者移除最后一个 online 版本时移除latest删除或下线非当前latest的 online 版本不触发重算。每当 online 状态或标签变化服务器必须将versionCatalog作为一次逻辑更新重建存在至少一个 online 版本时必须恰好存在一个有效latestVersion且出现在onlineVersions中。该逻辑由 AgentVersionCatalogBuilder 实现按AgentVersionComparator降序排序在线版本修复缺失/陈旧的latest指向最大在线版本并生成只读目录条目。4.4 生命周期解耦与搜索索引Agent 元数据、Agent Version 定义、Runtime Endpoint互不拥有对方生命周期删除或禁用 Agent 定义只改变读投影不删除仍存活的运行时发布者状态。Agent 目录 Search 文档是可重建的派生状态不是另一个事实来源。以下成功提交按(namespaceId, agent, agentName)调度一次合并的search_index任务Agent 创建、目录元数据或治理更新、Version 发布/上线/下线/删除、common-latest 或自定义标签变化、经旧 A2A 门面的规范定义变化、Agent 删除。任务重新读取当前事实投影 common latest 与完整在线版本目录连续变化只推进任务修订。Runtime Endpoint 注册/注销、Publisher 心跳、健康状态、Runtime 修订不调度该任务也绝不进入 Agent 目录索引调度失败不回滚已成功的生命周期操作持久化任务重试与 Reconciliation 按 AI Resource Search Spec 收敛。Agent 不存在、禁用或没有 online 版本时删除派生文档是正确索引结果。5. CallInterface 与声明的端点5.1 AgentCallInterface每个 Agent Version 含有序非空callInterfaces[]每项字段字段必填含义protocol是规范协议 tokenVersion 内唯一protocolVersion否快速协议协商值不是接口身份descriptorMediaType是nativeDescriptor的媒体类型nativeDescriptor是完整协议原生描述符endpointSourceOrder[]是非空有序集合RUNTIME与DECLAREDdeclaredEndpoints[]否适配器派生的静态端点投影规范协议 token 匹配[A-Za-z0-9][A-Za-z0-9-]{0,31}大小写敏感比较同一 token 用于 CallInterface 唯一性、端点发布、RAD 过滤与 Naming 服务组合。callInterfaces[]的顺序是默认协议偏好重排列表会改变contentDigest第一个具有可用端点的接口是 SDK 默认选择候选。endpointSourceOrder无重复语义如下[RUNTIME, DECLARED]优先存活地址声明地址作回退[DECLARED, RUNTIME]优先声明地址[RUNTIME]或[DECLARED]普通发现中只允许该来源。来源顺序属于单个 CallInterface不属于整个 Version它不阻止运行时发布管理查询即使某 CallInterface 省略RUNTIME也可检查 Runtime Endpoint。5.2 Endpoint 值对象字段必填含义uri是完整可调用 URItransport是规范传输 tokenpriority否数值越小优先级越高weight否同优先级端点间的负载权重metadata否扁平 zone / environment />namespaceId / agentName / protocol / version? items[] { endpoint, bindings[] { runtimeVersion, versionRange }, state, enabled, healthy, lastUpdatedTime } state AVAILABLE | DISABLED | UNHEALTHY状态评估有序enabledfalse为DISABLED否则healthyfalse为UNHEALTHY其余为AVAILABLE。lastUpdatedTime是构建快照所用 NamingServiceInfo投影的lastRefTime同一快照内所有 item 共享同一投影观察时间——它不是逐端点的分布式事实或缓存校验器可能随 Naming 重建而变跨节点相等性与 watch 去重使用内容派生的sourceRevision。protocol必填。不带version时快照按该协议自然 Endpoint 键给出每个有效 item 及全部 Version 绑定带version时只保留匹配绑定无剩余绑定时省略该 item缺失实例产生空items[]。快照不应用endpointSourceOrder也不声称某个 item 可发现控制台只把 Version 详情与快照作为分离的读事实组合。RAD 的AgentDiscoveryResult将一份 online Version 定义与允许的 DECLARED/RUNTIME 端点集组合但它永不作为事实存储。7. 容量与安全写前强制限制写入 Agent 或 Version 事实前强制以下限制字段限制displayName、provider.name128 个 Unicode 码点description2048 字符Icon、provider 或声明端点 URI2048 字符公共 tags32 项每项 64 字符Agentextensions32 项键 128 字符序列化 UTF-8 JSON 总计 16 KiBprotocol、protocolVersion32 与 64 字符每 Version CallInterfaces16每 CallInterface 声明端点64Endpoint metadata32 项键 64、值 256 字符AgentVersionContent1 MiBbiz_tags只存用户提供的公共 tags不含服务器派生索引序列化 JSON 不得超过 1024 字符。描述符、extensions、Endpoint metadata 不得含明文凭据审计记录不得记录完整原生描述符、安全方案或敏感 Endpoint 元数据。运行时发布与物理存储限制由 Agent Storage Spec 定义。源码佐证AgentVersionContentSerializer 以MAX_CALL_INTERFACES 16、MAX_CONTENT_SIZE 1024*1024强制执行AgentResourceExt见 AgentResourceExt以 schemaVersion1 承载displayName/iconUrl/provider/extensions/versionCatalog其中extensions为MapString, Object即规范中的命名空间化扩展。8. A2A 兼容边界旧 API 作为新模型的门面迁移后旧 A2A API 是 Agent 模型之上的兼容门面不创建第二个 AgentCard 事实来源A2A 值Agent 模型投影AgentCard name 与 versionagentName与 Agent Version 身份完整 AgentCardA2A CallInterfacenativeDescriptorA2A 协议版本CallInterfaceprotocolVersion与原生描述符Root URL 与 supported/additional interfaces适配器派生的声明端点registrationTypeURL声明优先的来源顺序registrationTypeSERVICE运行时优先的来源顺序运行时 A2A 端点版本runtimeVersion与精确[version]范围首个实现只支持 A2A 协议因此旧 A2A latest 与公共 Agent latest 使用同一标签。适配器从原生描述符与适用端点投影重建旧查询 DTOURL 风格读取用声明地址service 风格读取用运行时地址无运行时地址时以声明地址作为兼容回退。通过旧 API 的新写入同样适用本规范的身份、Version、不可变性与容量规则它们可使用审计的内部 direct-online 迁移以保留 code-first A2A 发布但不得覆盖已发布 Version 中不同的内容。源码中registerLegacyOnlineVersion、releaseLegacyOnlineVersion、updateLegacyOnlineVersion、deleteLegacyVersionIfPresent、deleteLegacyAgentIfPresentAgentOperationService就是这一门面的落地它们校验后走createInitialOnlineVersion/createOnlineVersion/directOnlineExistingAgent内容不一致时以RESOURCE_CONFLICT拒绝覆盖且对已 online 的精确版本在setAsLatestfalse时保持latest不变。历史 Config 行、历史 Naming 布局、混合版本集群双读/双写、源切换、回滚与畸形历史身份属于独立的滚动升级与数据迁移契约不被本目标模型放宽。9. 与相邻资源的关系与展望Agent 与 AgentSpec 资源可通过通用资源关系互相引用但互不拥有对方生命周期。本版本不新增 Agent 专属的sourceRef、defaultInterfaceId、interfaceId、descriptorDigest或随机 Endpoint 标识符。AI Registry 有意以版本为中心——AI 资产的变化速度常快于应用配置或服务发现数据元数据/版本分离的模型让新资源类型能够复用同一套治理能力。若上游 AI 标准演进使现有模型不安全或有误导性规范将随明确的迁移与兼容规则演化参见 AI Resource Model Spec 的演进说明。延伸阅读生命周期通用规则AI Resource Lifecycle Spec存储、Naming 映射与sourceRevisionAgent Storage Spec数据面消息定义RAD Protocol Spec迁移前运行时契约A2A Agent Spec核心实现AgentOperationService、AgentAdminController、AgentVersionContentSerializer、AgentVersionCatalogBuilder、AgentVersionComparator【免费下载链接】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），仅供参考