agentscope-extensions-nacos 把 Nacos 用作 AgentScope 的统一控制面:注册发现 A2A Agent、动态加载 Prompt、托管 Skill。包含三个子模块,按需组合使用。
A2A 注册发现
添加依赖
服务端:把 AgentCard 注册到 Nacos
AgentCard。version("1.2.3") 是 Agent 的业务版本;AgentInterface 的最后一个参数 "1.0" 是接口协议版本,按 A2A 规范使用主版本和次版本。注册更高的业务版本不代表支持更高的协议版本。
接口元数据随新版本发布生效;已经发布的版本不会被同版本注册覆盖,如需修正旧记录,请发布新的业务版本。
上例设置了 setAsLatest(true)。未启用发布审核时,注册会自动发布该版本,发布完成后消费者即可发现。
如果设置
setAsLatest(false),后续新版本可能保留为草稿,需要在 Nacos 控制台完成发布;首次创建的版本仍会自动提交。如果启用了发布审核,即使设置为 true,也需要在控制台完成相应的审核和发布步骤。端点更新兼容性:在 Nacos 3.3 中,同一客户端重新注册同一 Agent 版本时,会替换该版本的完整端点集合。更新地址时,请向
registry.registerAgent(...) 提交所有需要保留的端点配置。不要在注册新地址后再注销旧地址,否则会撤销该版本的整组注册;其他客户端的注册不受影响。A2A 1.0 字段兼容性:使用多租户时,将
AgentInterface 的第三个参数设为 tenant;注册会保留每个接口的 tenant 和协议版本。配置运行时地址时,按传输类型匹配 Card 接口;存在多个候选时优先匹配 URL,仍有不同 tenant 或协议版本的歧义则拒绝注册。A2A 技能级 securityRequirements 尚不能完整保存,直接导入含鉴权要求的标准 A2A 1.0 JSON 也尚不兼容。上例通过 Java 对象注册;注册成功并不表示所有 A2A 1.0 字段均受支持。客户端:通过 Nacos 拿到远端 AgentCard
-Dagentscope.nacos.a2a.discovery.mode=a2a 或 rad 显式指定;auto 表示自动选择。参数在创建 Resolver 时读取,实际选择在首次查询时完成,之后不会自动切换。
升级提示:支持 RAD 的服务端现在默认使用原生发现。Agent 或所选版本、标签被删除后,
getAgentCard(...) 返回 null,重建后自动恢复;显式选择 a2a 可保留旧模式下缓存最后一个 AgentCard 的行为。首次 RAD 查询在订阅完成后最多等待 10 秒接收初始状态,超时会报错,后续查询继续使用同一订阅。能力尚未确定或查询失败时会报错,不会自动降级;可在连接就绪后重试。发现结果无法转换为 A2A Card 时也会报告转换错误。Prompt 配置中心
添加依赖
用法
prod 标签读取模板;需要固定版本时,将第二个参数设为版本号(如 "1.0.0"),第三个参数设为 null。调用参数会覆盖模板中的变量默认值。当模板不存在、为空,或读取失败时,使用最后一个参数提供的默认模板。
在 Nacos 更新模板或切换标签后,变更会自动同步,无需重启应用。应在需要生成提示词时调用 getPrompt(...);已经返回的字符串不会自动变化。
升级提示:Prompt 的
version 和 label 现在会校验互斥。如果现有调用同时传入两者,请改为只指定一个,否则会抛出 IllegalArgumentException。Skill 仓库
agentscope-extensions-nacos-skill 提供一个 AgentSkillRepository 实现,把 Nacos AI 模块管理的技能 ZIP 包下载下来解析。
Properties → JVM -D 系统属性 → 环境变量。同时设置版本和标签时,版本优先,标签不会用于下载。
在 Nacos 发布 Skill 新版本后,需要重新调用 getSkill(...) 并将返回的 Skill 加载到 Agent;已经加载的 Skill 不会自动替换。若指定了固定版本,还需先将版本配置改为目标版本并重新创建仓库。