Nacos Java SDK 如何用 AiService.publishAgent 发布 A2A 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如果你的 Agent 服务已经实现好了 A2A 协议端点接下来需要把「Agent 定义」名称、版本、描述、能力、调用端点等注册到 Nacos 服务端让其它服务能通过发现接口读到这份定义那么 Java SDK 提供的AiService.publishAgent(AgentPublishRequest)就是对应的代码级入口。该接口在 AiService 上标注Since(3.3.0)当前仓库版本为3.3.0-SNAPSHOT因此客户端与服务端都需要 3.3.0 及以上能力客户端通过AiFactory.createAiService(properties)创建默认走 gRPC 传输也可显式选择 HTTP 传输。本文的操作路径与仓库中的 SDK 集成测试保持一致参考实现是 AgentPublishJavaSdkITCase场景矩阵记录在 AGENT_PUBLISH_SDK_IT_SCENARIOS.md。准备条件Maven 工程需要引入两个依赖nacos-client提供AiServicenacos-maintainer-client用于发布后的交叉核对与清理集成测试中为 test scope。版本与 Nacos 服务端对齐${nacos.version}替换为你实际使用的 3.3.0 及以上版本。dependency groupIdcom.alibaba.nacos/groupId artifactIdnacos-client/artifactId version${nacos.version}/version /dependency dependency groupIdcom.alibaba.nacos/groupId artifactIdnacos-maintainer-client/artifactId version${nacos.version}/version /dependency连接参数通过Properties传给工厂方法关键项是PropertyKeyConst.SERVER_ADDR默认按127.0.0.1:8848理解Properties properties new Properties(); properties.setProperty(PropertyKeyConst.SERVER_ADDR, 127.0.0.1:8848); // 可选指定命名空间。请求本身不能携带命名空间 // 发布进入哪个 namespace 完全由客户端的 NAMESPACE 决定 // properties.setProperty(PropertyKeyConst.NAMESPACE, custom-namespace);创建客户端时默认 gRPC 传输如需显式选择 HTTP 传输再追加AiConstants.AI_TRANSPORT_MODE为AiConstants.AI_TRANSPORT_MODE_HTTP。集成测试验证过同一个发布请求在 gRPC 与 HTTP 两种传输下得到的结果一致相同的contentDigest、相同的错误类别即传输是可选分支不影响主路径。AiService service AiFactory.createAiService(properties);构造 AgentPublishRequest请求体是 AgentPublishRequest除自身新增的autoSubmit字段外还继承草稿创建请求的元数据字段。按集成测试的构造方式一次完整的 A2A 发布请求需要定位字段agentName、version精确版本号如1.0.0、author、changeDescription内容来源callInterfaces元素为AgentCallInterface其中protocol固定为a2anativeDescriptor是由 A2AAgentCard序列化后的 Map或者用basedOnVersion继承已有版本二选一见后文「版本演进」autoSubmitfalse只创建草稿drafttrue在草稿创建后走普通提交流程不是force-publish。下面是可直接运行的示例AGENT_NAME替换为你自己的 Agent 名称其余取值版本1.0.0、协议a2a/1.0、application/json、HTTPJSON/GRPC接口等均取自集成测试的构造代码可原样保留或按需调整String AGENT_NAME my-a2a-agent; // 替换为你自己的 Agent 名称 String version 1.0.0; // 1) 组装 A2A AgentCard支持的接口与能力 AgentInterface jsonRpc new AgentInterface(); jsonRpc.setUrl(https://example.com/ AGENT_NAME /jsonrpc); jsonRpc.setProtocolBinding(HTTPJSON); jsonRpc.setProtocolVersion(1.0); AgentInterface grpc new AgentInterface(); grpc.setUrl(https://example.com/ AGENT_NAME /grpc); grpc.setProtocolBinding(GRPC); grpc.setProtocolVersion(1.0); AgentCapabilities capabilities new AgentCapabilities(); capabilities.setStreaming(Boolean.TRUE); AgentCard card new AgentCard(); card.setName(AGENT_NAME); card.setVersion(version); card.setDescription(code-first A2A agent); card.setSupportedInterfaces(Arrays.asList(jsonRpc, grpc)); card.setCapabilities(capabilities); // 2) 组装 A2A 调用接口协议信息 原生描述 声明端点 Endpoint jsonRpcEndpoint new Endpoint(); jsonRpcEndpoint.setUri(jsonRpc.getUrl()); jsonRpcEndpoint.setTransport(jsonRpc.getProtocolBinding()); Endpoint grpcEndpoint new Endpoint(); grpcEndpoint.setUri(grpc.getUrl()); grpcEndpoint.setTransport(grpc.getProtocolBinding()); AgentCallInterface callInterface new AgentCallInterface(); callInterface.setProtocol(a2a); callInterface.setProtocolVersion(1.0); callInterface.setDescriptorMediaType(application/json); callInterface.setNativeDescriptor(JacksonUtils.toObj(JacksonUtils.toJson(card), Map.class)); callInterface.setEndpointSourceOrder(Arrays.asList(EndpointSource.DECLARED, EndpointSource.RUNTIME)); callInterface.setDeclaredEndpoints(Arrays.asList(jsonRpcEndpoint, grpcEndpoint)); // 3) 组装发布请求 AgentPublishRequest request new AgentPublishRequest(); request.setAgentName(AGENT_NAME); request.setVersion(version); request.setCallInterfaces(Collections.singletonList(callInterface)); request.setAuthor(java-sdk-it); request.setChangeDescription(publish version); request.setAutoSubmit(true); // false 则只创建草稿 // 可选元数据草稿创建请求继承字段 request.setDisplayName(Display AGENT_NAME); request.setDescription(Code-first Agent AGENT_NAME); request.setIconUrl(https://example.com/ AGENT_NAME /icon.png); AgentProvider provider new AgentProvider(); provider.setName(Nacos Java SDK IT); provider.setUrl(https://nacos.io); request.setProvider(provider); request.setTags(Arrays.asList(a2a, it)); request.setExtensions(Collections.singletonMap(marker, v1));注意一个边界callInterfaces与basedOnVersion只能二选一。集成测试中同时设置两者、或两者都不设置都会收到NacosException.INVALID_PARAM。执行发布并观察状态AgentVersionDetail result service.publishAgent(request); System.out.println(result.getStatus() / result.getNamespaceId() / result.getContentDigest());publishAgent返回精确版本的AgentVersionDetailgetStatus()的取值决定了这份定义是否对外可见请求形态结果状态对外可见性首次发布autoSubmitfalsedraftRAD Discover 与 legacy A2A 查询都不暴露该草稿首次发布autoSubmittrueonline无审核 Pipeline 时Discover 与 legacy A2A 查询暴露同一份 A2A 描述符对已存在草稿重放同内容请求且autoSubmittrueonline复用原草稿提交不会产生重复 Version重试是幂等的相同请求重放autoSubmitfalse会返回同一个草稿版本online之后重放等价请求返回既有 Version。同时 SDK 不会改动你传入的request对象集成测试对请求做了序列化快照比对。冲突时抛出NacosException.CONFLICT包括同一精确 Version 但内容、作者、变更描述或初始元数据不同对一个已online的 Version 再发autoSubmitfalse对已下线offline的 Version 用任意模式重发。定义不存在时读取返回NacosException.NOT_FOUND。验证发布结果集成测试用三条互相独立的读路径核对同一次发布建议照此验证1. RAD Discover通用发现接口AgentReference reference new AgentReference(); reference.setAgentName(AGENT_NAME); reference.setVersion(null); // null 表示 latest AgentDiscoveryResult discovery service.discoverAgent(reference); // 期望discovery.getVersion() 1.0.0 // 且 discovery.getContentDigest() 与发布返回值一致草稿状态下执行同样查询会抛NOT_FOUND这本身可以作为「草稿未对外暴露」的验证。2. legacy A2A 查询AgentCardDetailInfo legacy service.getAgentCard(AGENT_NAME, 1.0.0, AiConstants.A2a.A2A_ENDPOINT_TYPE_URL); // 期望legacy.getName()/getVersion() 与发布一致 // getSupportedInterfaces().size() 2与示例中两个 AgentInterface 对应3. Maintainer 交叉核对可选Properties maintainerProperties new Properties(); maintainerProperties.setProperty(PropertyKeyConst.SERVER_ADDR, 127.0.0.1:8848); maintainerProperties.setProperty(PropertyKeyConst.CONTEXT_PATH, /nacos); AgentMaintainerService maintainer AiMaintainerFactory.createAiMaintainerService(maintainerProperties).agent(); // 与发布返回值比对 contentDigest maintainer.getAgentVersion(Constants.DEFAULT_NAMESPACE_ID, AGENT_NAME, 1.0.0) .getContentDigest();三个读路径Discover、legacy 查询、Maintainer应当共享同一份 canonical 定义相同的精确 Version、描述符、声明端点和 digest。可选分支版本演进与端点预注册发布后续版本有两种方式。直接再发一个新版本AgentPublishRequest second new AgentPublishRequest(); second.setAgentName(AGENT_NAME); second.setVersion(2.0.0); second.setCallInterfaces(Collections.singletonList(callInterface)); // 内容不同 second.setAuthor(java-sdk-it); second.setChangeDescription(publish 2.0.0); second.setAutoSubmit(true); AgentVersionDetail secondResult service.publishAgent(second); // 期望secondResult.getContentDigest() 与 1.0.0 的 digest 不同或者用basedOnVersion继承新 Version 不携带callInterfaces只设setBasedOnVersion(2.0.0)得到的 digest 与被继承版本一致。继承有一个前提——首个 Version 不能继承对不存在的 Agent 设置basedOnVersion会抛INVALID_PARAM。先注册运行时端点、后发布定义也是文档支持的路径先用service.registerAgentEndpoint(agentName, endpoint)AgentEndpoint携带 version、address、port、transport、protocolVersion、path预注册端点。此时定义查询仍是NOT_FOUND端点预注册本身不会创建 Agent发布定义之后用getAgentCard(agentName, version, AiConstants.A2a.A2A_ENDPOINT_TYPE_SERVICE)查询即可看到预注册端点已随该 Version 暴露。命名空间隔离由客户端决定NAMESPACE不同的两个客户端各自发布互相discoverAgent对方都得到NOT_FOUND这是集成测试明确断言的行为。限制与清理需要留意的限制均来自测试断言发布走的是普通提交流程autoSubmit不会强制执行 force-publish请求无法指定命名空间只能由客户端NAMESPACE属性决定对 offline 的 Version 重发会失败INVALID_PARAM需要先理解版本状态再操作。测试收尾阶段使用的清理命令可在验证完成后执行service.deregisterAgentEndpoint(AGENT_NAME, endpoint); // 如预注册过端点 maintainer.deleteAgent(Constants.DEFAULT_NAMESPACE_ID, AGENT_NAME); service.shutdown();更完整的场景清单冲突矩阵、多版本 redo、精确/latest 订阅路由、gRPC/HTTP 跨传输组合等见 AGENT_PUBLISH_SDK_IT_SCENARIOS.md其中也标明 Server Watch/Push、数据迁移与 force-publish 不在当前阶段范围内。【免费下载链接】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 Java SDK 如何用 AiService.publishAgent 发布 A2A Agent 定义？
Nacos Java SDK 如何用 AiService.publishAgent 发布 A2A 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如果你的 Agent 服务已经实现好了 A2A 协议端点接下来需要把「Agent 定义」名称、版本、描述、能力、调用端点等注册到 Nacos 服务端让其它服务能通过发现接口读到这份定义那么 Java SDK 提供的AiService.publishAgent(AgentPublishRequest)就是对应的代码级入口。该接口在 AiService 上标注Since(3.3.0)当前仓库版本为3.3.0-SNAPSHOT因此客户端与服务端都需要 3.3.0 及以上能力客户端通过AiFactory.createAiService(properties)创建默认走 gRPC 传输也可显式选择 HTTP 传输。本文的操作路径与仓库中的 SDK 集成测试保持一致参考实现是 AgentPublishJavaSdkITCase场景矩阵记录在 AGENT_PUBLISH_SDK_IT_SCENARIOS.md。准备条件Maven 工程需要引入两个依赖nacos-client提供AiServicenacos-maintainer-client用于发布后的交叉核对与清理集成测试中为 test scope。版本与 Nacos 服务端对齐${nacos.version}替换为你实际使用的 3.3.0 及以上版本。dependency groupIdcom.alibaba.nacos/groupId artifactIdnacos-client/artifactId version${nacos.version}/version /dependency dependency groupIdcom.alibaba.nacos/groupId artifactIdnacos-maintainer-client/artifactId version${nacos.version}/version /dependency连接参数通过Properties传给工厂方法关键项是PropertyKeyConst.SERVER_ADDR默认按127.0.0.1:8848理解Properties properties new Properties(); properties.setProperty(PropertyKeyConst.SERVER_ADDR, 127.0.0.1:8848); // 可选指定命名空间。请求本身不能携带命名空间 // 发布进入哪个 namespace 完全由客户端的 NAMESPACE 决定 // properties.setProperty(PropertyKeyConst.NAMESPACE, custom-namespace);创建客户端时默认 gRPC 传输如需显式选择 HTTP 传输再追加AiConstants.AI_TRANSPORT_MODE为AiConstants.AI_TRANSPORT_MODE_HTTP。集成测试验证过同一个发布请求在 gRPC 与 HTTP 两种传输下得到的结果一致相同的contentDigest、相同的错误类别即传输是可选分支不影响主路径。AiService service AiFactory.createAiService(properties);构造 AgentPublishRequest请求体是 AgentPublishRequest除自身新增的autoSubmit字段外还继承草稿创建请求的元数据字段。按集成测试的构造方式一次完整的 A2A 发布请求需要定位字段agentName、version精确版本号如1.0.0、author、changeDescription内容来源callInterfaces元素为AgentCallInterface其中protocol固定为a2anativeDescriptor是由 A2AAgentCard序列化后的 Map或者用basedOnVersion继承已有版本二选一见后文「版本演进」autoSubmitfalse只创建草稿drafttrue在草稿创建后走普通提交流程不是force-publish。下面是可直接运行的示例AGENT_NAME替换为你自己的 Agent 名称其余取值版本1.0.0、协议a2a/1.0、application/json、HTTPJSON/GRPC接口等均取自集成测试的构造代码可原样保留或按需调整String AGENT_NAME my-a2a-agent; // 替换为你自己的 Agent 名称 String version 1.0.0; // 1) 组装 A2A AgentCard支持的接口与能力 AgentInterface jsonRpc new AgentInterface(); jsonRpc.setUrl(https://example.com/ AGENT_NAME /jsonrpc); jsonRpc.setProtocolBinding(HTTPJSON); jsonRpc.setProtocolVersion(1.0); AgentInterface grpc new AgentInterface(); grpc.setUrl(https://example.com/ AGENT_NAME /grpc); grpc.setProtocolBinding(GRPC); grpc.setProtocolVersion(1.0); AgentCapabilities capabilities new AgentCapabilities(); capabilities.setStreaming(Boolean.TRUE); AgentCard card new AgentCard(); card.setName(AGENT_NAME); card.setVersion(version); card.setDescription(code-first A2A agent); card.setSupportedInterfaces(Arrays.asList(jsonRpc, grpc)); card.setCapabilities(capabilities); // 2) 组装 A2A 调用接口协议信息 原生描述 声明端点 Endpoint jsonRpcEndpoint new Endpoint(); jsonRpcEndpoint.setUri(jsonRpc.getUrl()); jsonRpcEndpoint.setTransport(jsonRpc.getProtocolBinding()); Endpoint grpcEndpoint new Endpoint(); grpcEndpoint.setUri(grpc.getUrl()); grpcEndpoint.setTransport(grpc.getProtocolBinding()); AgentCallInterface callInterface new AgentCallInterface(); callInterface.setProtocol(a2a); callInterface.setProtocolVersion(1.0); callInterface.setDescriptorMediaType(application/json); callInterface.setNativeDescriptor(JacksonUtils.toObj(JacksonUtils.toJson(card), Map.class)); callInterface.setEndpointSourceOrder(Arrays.asList(EndpointSource.DECLARED, EndpointSource.RUNTIME)); callInterface.setDeclaredEndpoints(Arrays.asList(jsonRpcEndpoint, grpcEndpoint)); // 3) 组装发布请求 AgentPublishRequest request new AgentPublishRequest(); request.setAgentName(AGENT_NAME); request.setVersion(version); request.setCallInterfaces(Collections.singletonList(callInterface)); request.setAuthor(java-sdk-it); request.setChangeDescription(publish version); request.setAutoSubmit(true); // false 则只创建草稿 // 可选元数据草稿创建请求继承字段 request.setDisplayName(Display AGENT_NAME); request.setDescription(Code-first Agent AGENT_NAME); request.setIconUrl(https://example.com/ AGENT_NAME /icon.png); AgentProvider provider new AgentProvider(); provider.setName(Nacos Java SDK IT); provider.setUrl(https://nacos.io); request.setProvider(provider); request.setTags(Arrays.asList(a2a, it)); request.setExtensions(Collections.singletonMap(marker, v1));注意一个边界callInterfaces与basedOnVersion只能二选一。集成测试中同时设置两者、或两者都不设置都会收到NacosException.INVALID_PARAM。执行发布并观察状态AgentVersionDetail result service.publishAgent(request); System.out.println(result.getStatus() / result.getNamespaceId() / result.getContentDigest());publishAgent返回精确版本的AgentVersionDetailgetStatus()的取值决定了这份定义是否对外可见请求形态结果状态对外可见性首次发布autoSubmitfalsedraftRAD Discover 与 legacy A2A 查询都不暴露该草稿首次发布autoSubmittrueonline无审核 Pipeline 时Discover 与 legacy A2A 查询暴露同一份 A2A 描述符对已存在草稿重放同内容请求且autoSubmittrueonline复用原草稿提交不会产生重复 Version重试是幂等的相同请求重放autoSubmitfalse会返回同一个草稿版本online之后重放等价请求返回既有 Version。同时 SDK 不会改动你传入的request对象集成测试对请求做了序列化快照比对。冲突时抛出NacosException.CONFLICT包括同一精确 Version 但内容、作者、变更描述或初始元数据不同对一个已online的 Version 再发autoSubmitfalse对已下线offline的 Version 用任意模式重发。定义不存在时读取返回NacosException.NOT_FOUND。验证发布结果集成测试用三条互相独立的读路径核对同一次发布建议照此验证1. RAD Discover通用发现接口AgentReference reference new AgentReference(); reference.setAgentName(AGENT_NAME); reference.setVersion(null); // null 表示 latest AgentDiscoveryResult discovery service.discoverAgent(reference); // 期望discovery.getVersion() 1.0.0 // 且 discovery.getContentDigest() 与发布返回值一致草稿状态下执行同样查询会抛NOT_FOUND这本身可以作为「草稿未对外暴露」的验证。2. legacy A2A 查询AgentCardDetailInfo legacy service.getAgentCard(AGENT_NAME, 1.0.0, AiConstants.A2a.A2A_ENDPOINT_TYPE_URL); // 期望legacy.getName()/getVersion() 与发布一致 // getSupportedInterfaces().size() 2与示例中两个 AgentInterface 对应3. Maintainer 交叉核对可选Properties maintainerProperties new Properties(); maintainerProperties.setProperty(PropertyKeyConst.SERVER_ADDR, 127.0.0.1:8848); maintainerProperties.setProperty(PropertyKeyConst.CONTEXT_PATH, /nacos); AgentMaintainerService maintainer AiMaintainerFactory.createAiMaintainerService(maintainerProperties).agent(); // 与发布返回值比对 contentDigest maintainer.getAgentVersion(Constants.DEFAULT_NAMESPACE_ID, AGENT_NAME, 1.0.0) .getContentDigest();三个读路径Discover、legacy 查询、Maintainer应当共享同一份 canonical 定义相同的精确 Version、描述符、声明端点和 digest。可选分支版本演进与端点预注册发布后续版本有两种方式。直接再发一个新版本AgentPublishRequest second new AgentPublishRequest(); second.setAgentName(AGENT_NAME); second.setVersion(2.0.0); second.setCallInterfaces(Collections.singletonList(callInterface)); // 内容不同 second.setAuthor(java-sdk-it); second.setChangeDescription(publish 2.0.0); second.setAutoSubmit(true); AgentVersionDetail secondResult service.publishAgent(second); // 期望secondResult.getContentDigest() 与 1.0.0 的 digest 不同或者用basedOnVersion继承新 Version 不携带callInterfaces只设setBasedOnVersion(2.0.0)得到的 digest 与被继承版本一致。继承有一个前提——首个 Version 不能继承对不存在的 Agent 设置basedOnVersion会抛INVALID_PARAM。先注册运行时端点、后发布定义也是文档支持的路径先用service.registerAgentEndpoint(agentName, endpoint)AgentEndpoint携带 version、address、port、transport、protocolVersion、path预注册端点。此时定义查询仍是NOT_FOUND端点预注册本身不会创建 Agent发布定义之后用getAgentCard(agentName, version, AiConstants.A2a.A2A_ENDPOINT_TYPE_SERVICE)查询即可看到预注册端点已随该 Version 暴露。命名空间隔离由客户端决定NAMESPACE不同的两个客户端各自发布互相discoverAgent对方都得到NOT_FOUND这是集成测试明确断言的行为。限制与清理需要留意的限制均来自测试断言发布走的是普通提交流程autoSubmit不会强制执行 force-publish请求无法指定命名空间只能由客户端NAMESPACE属性决定对 offline 的 Version 重发会失败INVALID_PARAM需要先理解版本状态再操作。测试收尾阶段使用的清理命令可在验证完成后执行service.deregisterAgentEndpoint(AGENT_NAME, endpoint); // 如预注册过端点 maintainer.deleteAgent(Constants.DEFAULT_NAMESPACE_ID, AGENT_NAME); service.shutdown();更完整的场景清单冲突矩阵、多版本 redo、精确/latest 订阅路由、gRPC/HTTP 跨传输组合等见 AGENT_PUBLISH_SDK_IT_SCENARIOS.md其中也标明 Server Watch/Push、数据迁移与 force-publish 不在当前阶段范围内。【免费下载链接】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），仅供参考
