Nacos Java SDK Agent 代码发布Code-First Publication集成测试场景全解析【免费下载链接】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 仓库中 AGENT_PUBLISH_SDK_IT_SCENARIOS.md 记录的 Agent 代码发布Code-FirstJava SDK 集成测试场景矩阵展开系统梳理AiService.publishAgent公开契约、autoSubmit草稿/在线状态机、版本演化与冲突规则、RAD/旧版 A2A 双投影一致性以及旧版A2aService端点预注册与订阅恢复等关键行为。读者阅读本文后将掌握如何用 Nacos Java SDK 以纯代码方式发布 Agent 定义、理解草稿—提交—在线各状态下的可观察性与错误码语义并能在 gRPC/HTTP 双传输、命名空间隔离、多版本端点预注册等真实场景中编写可复现的集成测试。注本文所有测试矩阵、断言与源码引用均以当前仓库实际内容为准场景验证代码位于 test/java-sdk-test/src/test/java/com/alibaba/nacos/test/sdk/ai/AgentPublishJavaSdkITCase.java。一、场景矩阵总览为什么需要 Code-First 发布在 Nacos 3.x 的 AI 资源体系中Agent 的定义AgentCard、callInterfaces、端点等既可以通过控制台/管理端录入也可以由应用代码直接发布。本文档所记录的正是第二种路径——代码优先Code-First定义发布其对外契约是公开的AiService.publishAgent(AgentPublishRequest)方法见 api/src/main/java/com/alibaba/nacos/api/ai/AiService.java自 Nacos 3.3.0 起提供。场景矩阵分为三大板块板块覆盖范围Code-First 定义发布autoSubmitfalse/true、续提Resume、重试收敛、冲突与状态机、版本演化、命名空间隔离、传输等价性、端点独立性旧版 A2aService 一版对齐端点预注册、多版本重做、重放快照隔离、精确/latest 路由、重新订阅、优雅关闭复合跨面工作流通用 SDK 发布 RAD/Console/旧版 A2A 交叉读取、定义与端点发布顺序、多版本演进订阅、HTTP/gRPC 双向交叉所有测试以外部 Java 客户端身份连接独立standalone服务器运行保证场景与真实生产调用链一致。二、Code-First 定义发布核心契约1.publishAgent请求模型与默认行为AgentPublishRequest继承自AgentDraftCreateRequest仅增加一个autoSubmit布尔字段见 api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentPublishRequest.java。父类AgentDraftCreateRequest携带的字段即完整请求体字段类型含义agentNameStringAgent 唯一标识必填displayNameString展示名descriptionString描述iconUrlString图标地址providerAgentProvider提供方信息name/urltagsListString标签extensionsMapString,Object扩展信息versionString精确版本号必填callInterfacesListAgentCallInterface直接内容二选一authorString作者changeDescriptionString变更说明basedOnVersionString基于某个已有版本继承内容二选一autoSubmitboolean是否在草稿创建后自动走普通提交管线关键语义源码 Javadoc 明示默认只建草稿autoSubmit缺省为false服务端仅创建draft状态版本不会直接对外暴露。autoSubmittrue不是 force-publish它触发的是普通提交管线submit pipeline如果配置了审核 Pipeline版本会停留在reviewing只有无审核管线时才会直接变为online。AiConstants中定义的版本状态机为见 api/src/main/java/com/alibaba/nacos/api/ai/constant/AiConstants.javadraft→reviewing→reviewed→online→offline。内容来源校验在AgentDraftCreateRequest.validate()中实现见 api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentDraftCreateRequest.javacallInterfaces与basedOnVersion必须且只能出现一个否则抛出IllegalArgumentException对应集成测试中的NacosException.INVALID_PARAM断言。2.autoSubmitfalse草稿发布与不可见性场景断言要点对应测试方法 AgentPublishJavaSdkITCase.java首次调用publishAgent后返回的AgentVersionDetail.status draftnamespaceId为请求方 AiService 的命名空间。Admin 与 Console 读取到相同内容与 digestSDK 侧通过maintainer.getAgentVersion(...)与发布结果做 digest 一致性校验。RAD Discover 与旧版 A2A 查询均不暴露草稿discoverAgent(reference)抛出NacosException.NOT_FOUNDgetAgentCard(agentName)同样 NOT_FOUND。SDK 不得篡改调用方请求测试在发布前后对请求做JacksonUtils.toJson快照对比保证对象引用级别的所有权不被破坏。3.autoSubmittrue一次成文直接上线首次请求即创建并提交首个直接内容版本无审核 Pipeline 时状态为online。RAD Discover 与旧版 A2A 查询此时都能拿到同一个 A2A 描述符discoverAgent返回1.0.0版本与online的contentDigest一致getAgentCard(agentName, version, A2A_ENDPOINT_TYPE_URL)返回相同 name/version且supportedInterfaces包含 2 个接口HTTPJSON 与 GRPC。4. Resume草稿续提而不产生重复版本先以autoSubmitfalse发布草稿再以等价请求仅autoSubmit改为true重复提交服务端复用已有草稿并提交不会创建重复版本返回的contentDigest与草稿完全一致。这正是发布场景中先审后发、审完一键上线的典型用法。5. 重试收敛Retry Convergence等价的false重试返回既有草稿幂等。等价的true重试已在线返回既有版本不重复创建。提交结果二义性后的重试通过重新读取状态收敛而非盲目重放由 Java SDK IT 服务端单元故障注入共同覆盖。6. 冲突与状态机Conflict and State冲突情形期望错误码相同精确版本号、内容不同NacosException.CONFLICT相同版本、author 不同CONFLICT相同版本、changeDescription 不同CONFLICT显式提供初始元数据不一致CONFLICT对已上线版本以autoSubmitfalse提交CONFLICT不覆盖对 offline 版本以任一模式提交INVALID_PARAM不覆盖测试中对相同请求重放draftOnlyRetry直接断言CONFLICT说明完全等价请求的重试收敛与内容/元数据变更请求是区分对待的前者幂等返回既有版本后者报冲突。7. 版本演化Version Evolution发布后续直接内容版本direct-content Version每个版本各自持有内容digest 不同。发布basedOnVersion继承版本新版本复制被继承版本的内容因此contentDigest与被继承版本一致但版本号不同RAD Discover 指向新版本号。拒绝首版本继承对全新 Agent 使用basedOnVersion报INVALID_PARAM。拒绝两源皆无/两源皆有既不带callInterfaces又无basedOnVersion或两者同时出现均报INVALID_PARAM源码validate()中directContent copiedContent即命中。8. 命名空间与调用方隔离默认命名空间与自定义命名空间完全隔离自定义命名空间发布的 Agent在默认命名空间的 gRPC 客户端上discoverAgent返回NOT_FOUND。请求不能自行指定命名空间命名空间取自 AiService 客户端本身PropertyKeyConst.NAMESPACE。SDK 拷贝语义发布请求的每个调用方持有字段与嵌套值在往返中保持不变由代理单元测试proxy unit tests覆盖深拷贝与不可变性。9. 传输等价性Transport Parity同一请求与错误类别在显式选择 gRPC 与 HTTP 传输时行为一致gRPC 发布的 Agent 可在 HTTP 客户端上 Discover且 HTTP 客户端以相同请求再次发布返回相同 digest幂等。未协商的能力在本地即失败不支持的能力不会发出远程请求直接本地抛错对应NacosException.SERVER_NOT_IMPLEMENTED一类语义。传输模式由AiConstants.AI_TRANSPORT_MODEnacosAiTransportMode控制取值grpc/http/auto见 AiConstants.java测试中通过Properties注入AiConstants.AI_TRANSPORT_MODE创建客户端。10. 端点独立性Endpoint Independence定义前预注册端点可以成功且不会创建 Agent 定义getAgentCard仍 NOT_FOUND。定义优先definition-first与端点优先endpoint-first两条工作流在发布后收敛到同一结果RAD 与旧版 SERVICE 查询都能解析出同一个精确版本对应端点。三、旧版 A2aService 一版对齐Legacy Alignment该板块保证旧版A2aServiceRAD 出现前的 AgentCard 查询/订阅接口与新的代码发布契约在第一版本语义上对齐。1. 端点预注册Endpoint Pre-registration先将旧版精确版本端点registerAgentEndpoint(agentName, endpoint)注册进规范 Runtime Service此时定义查询仍为空。再发布 AgentCardRAD Discover 与旧版 SERVICE 查询A2A_ENDPOINT_TYPE_SERVICE同时暴露预注册端点。测试通过containsLegacyEndpoint校验 URLhttp://{address}:{port}{path}、transportJSONRPC与 protocolVersion 全部匹配端点默认 transport 见 AiConstants.java。2. 多版本重做Multi-Version Redo一个 SDK 以两个独立规范子发布者身份为两个精确版本发布旧版端点然后真实重启 standalone 服务器重启后两个 Runtime 绑定均恢复且不会覆盖父连接上的协议中立发布protocol-neutral publication。该场景是服务端重启后旧版端点绑定可恢复的定向 Java SDK IT。3. 重放快照隔离Redo Snapshot Isolation注册之后再修改调用方原始 Endpoint 对象或集合不会改变重放replay载荷——即发布请求在注册瞬间完成快照拷贝由聚焦客户端单元测试覆盖。4. 精确/latest 路由精确订阅即使该版本恰为 latest精确订阅者也能收到变更。latest 订阅即使目标精确版本已在缓存中latest 指针移动事件依然会下发。测试覆盖latest 从 v3 回退到已缓存的 v2offlinev3 后 latest 指针移动等确定性场景配合缓存/通知器单元测试。5. 重新订阅Resubscribe取消订阅后再以已缓存值重新订阅轮询会重新启动且能观察到后续变更如 v4 发布后收到事件。集成测试用CountDownLatchAbstractNacosAgentCardListener断言事件到达轮询超时 25 秒。6. 关闭Shutdown反复调用 SDKshutdown()停止旧版 AgentCard 轮询、释放 executor且关闭后不再产生任何回调由 Java SDK IT 生命周期单元测试覆盖。四、复合跨面工作流Compound Cross-Surface Workflows工作流交叉校验内容通用 SDK 以autoSubmittrue发布 A2A再经 RAD Search/Discover、Console/Admin、旧版 A2A 读取所有投影共享同一规范定义、精确版本、描述符、声明端点与 digest旧版端点先行、通用 SDK 定义后行端点发布永不创建定义定义发布后 RAD 与旧版 SERVICE 查询解析出同一规范 Runtime 端点与绑定通用 SDK 发布 v1 → 注册运行时端点 → 订阅 latest → 发布 v2 → 注册 v2 端点Search、精确/latest Discover、轮询订阅、旧版 A2A 查询、旧版订阅在每个迁移点收敛HTTP 发布 gRPC Discover随后 gRPC 发布 HTTP Discover定义状态与错误映射传输等价持久化定义发布不需要 Publisher 心跳身份最后一行尤为重要它明确了本阶段的边界——Server Watch/Push、本地getAll/selectOneHealthy辅助方法、管理元数据订阅、滚动升级、数据迁移、双写dual writes与 force-publish 均不在本阶段范围之内属于后续阶段能力。五、如何运行与复现这些场景场景全部以 JUnit 5 集成测试形式存在于 test/java-sdk-test 模块关键用例AgentPublishJavaSdkITCase.java草稿/续提/冲突/版本演化/命名空间/传输等价/端点预注册/路由与重订阅/关闭等全部核心断言。AiTransportResourceMatrixJavaSdkITCase.java以grpc/http/auto三种模式对 Agent、MCP、Prompt、Skill、AgentSpec 五大 AI 资源族做传输矩阵验证其中 Agent 部分验证publishAgent后 Search/Discover/订阅/运行时端点注册全链路并断言 Skill/AgentSpec 在 gRPC 模式下的SERVER_NOT_IMPLEMENTED受控失败。运行前提先启动 standalone 模式的 Nacos 服务器nacosServer相关启动入口见仓库根目录 README.md 与 distribution/conf/application.properties。测试客户端通过JavaSdkBaseITCase.sdkProperties()连接服务器CONTEXT_PATH设为/nacos。可选指定nacosAiTransportModegrpc|http|auto验证传输等价性。复现要点从测试代码提炼的最小客户端配置Properties properties new Properties(); properties.setProperty(PropertyKeyConst.SERVER_ADDR, 127.0.0.1:8848); properties.setProperty(PropertyKeyConst.NAMESPACE, namespaceId); // 命名空间隔离 properties.setProperty(AiConstants.AI_TRANSPORT_MODE, grpc); // grpc | http | auto AiService service AiFactory.createAiService(properties); // 参见 api 模块工厂 AgentVersionDetail detail service.publishAgent(request); // Code-First 发布六、边界与阶段声明Out of Scope按 AGENT_PUBLISH_SDK_IT_SCENARIOS.md 末尾声明以下能力不在本阶段覆盖Server Watch / Push服务端主动推送本地getAll或selectOneHealthy辅助方法管理元数据订阅management metadata subscription滚动升级rolling upgrade、数据迁移data migration、双写dual writesforce-publish强制发布这些能力将在后续阶段补齐本阶段聚焦代码发布 双投影一致性 旧版对齐这一最小可用闭环。结语AGENT_PUBLISH_SDK_IT_SCENARIOS.md所记录的场景矩阵本质上是 Nacos AI 注册中心代码优先定义发布的可验证契约以AiService.publishAgent为入口以autoSubmit为草稿/在线状态开关以 digest 为一致性锚点同时保证 RAD 与旧版 A2A 双投影共享同一规范定义并以严格的冲突/错误码语义守住版本不可变与命名空间隔离。对于需要以纯代码方式注册 AI Agent 的开发者这套场景即是最权威的契约说明书与回归测试清单。【免费下载链接】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），仅供参考
