AgentScope 对接 Nacos AI Registry 使用 Skill

1. 添加依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
</dependency>

推荐通过 agentscope-bom 统一管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope-bom</artifactId>
            <version>1.0.12</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 初始化 AiService

创建 Nacos AiService 实例，配置 AI 治理中心访问地址和凭证。SERVER_ADDR 可填写公网接入点域名或 VPC 私网域名：

import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.ai.AiFactory;
import com.alibaba.nacos.api.ai.AiService;
import java.util.Properties;

Properties props = new Properties();
props.put(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
props.put(PropertyKeyConst.NAMESPACE, "your-namespace-id");
props.put(PropertyKeyConst.ACCESS_KEY, "LTAI5tXXXXXXXXXXXXXX");
props.put(PropertyKeyConst.SECRET_KEY, "XXXXXXXXXXXXXXXXXXXXxx");

AiService aiService = AiFactory.createAiService(props);

一个 AiService 实例对应一个命名空间。应用内尽量复用实例，退出时调用 aiService.shutdown() 释放资源。

3. 创建 NacosSkillRepository 并加载 Skill

使用 try-with-resources 方式创建 NacosSkillRepository：

import io.agentscope.core.nacos.skill.NacosSkillRepository;
import io.agentscope.core.skill.AgentSkill;

try (NacosSkillRepository repo = new NacosSkillRepository(aiService, "public")) {
    String name = "safe-commit-helper";
    if (repo.skillExists(name)) {
        AgentSkill skill = repo.getSkill(name);
        System.out.println(skill.getName() + " - " + skill.getDescription());
    } else {
        System.out.println("Skill not found: " + name);
    }
}

如果 namespaceId 为空或 null，自动使用 "public"。

4. 将 Skill 绑定到 Agent

通过 SkillBox 将 Skill 仓库关联到 Agent，Agent 在需要时按需从仓库加载 Skill：

import io.agentscope.core.skill.SkillBox;
import io.agentscope.core.ReActAgent;

SkillBox skillBox = new SkillBox(repo);

var agent = ReActAgent.builder()
        .name("MyAgent")
        .systemPrompt("你是一个智能助手。")
        .model(model)
        .skillBox(skillBox)
        .build();

配置方式

通过构造函数 Properties：

按版本加载：

Properties appProps = new Properties();
appProps.setProperty(NacosSkillRepository.SKILL_VERSION_PATH, "v1.0.0");

try (NacosSkillRepository repo =
             new NacosSkillRepository(aiService, "public", appProps)) {
    AgentSkill skill = repo.getSkill("safe-commit-helper");
}

按标签加载：

Properties appProps = new Properties();
appProps.setProperty(NacosSkillRepository.SKILL_LABEL_PATH, "stable");

try (NacosSkillRepository repo =
             new NacosSkillRepository(aiService, "public", appProps)) {
    AgentSkill skill = repo.getSkill("safe-commit-helper");
}

通过环境变量：

export AGENTSCOPE_NACOS_SKILL_VERSION=v1.0.0
# 或
export AGENTSCOPE_NACOS_SKILL_LABEL=stable

通过 JVM 系统属性：

java -Dagentscope.nacos.skill.version=v1.0.0 -jar myapp.jar

优先级示例：

// JVM: -Dagentscope.nacos.skill.version=jvm-ver
// ENV:  AGENTSCOPE_NACOS_SKILL_VERSION=env-ver

Properties props = new Properties();
props.setProperty(NacosSkillRepository.SKILL_VERSION_PATH, "app-ver");

// 此处 "app-ver" 生效
NacosSkillRepository repo = new NacosSkillRepository(aiService, "public", props);
repo.getSkill("my-skill");  // 实际调用 downloadSkillZipByVersion("my-skill", "app-ver")

下载 API 选择逻辑

以下为 NacosSkillRepository 内部实现说明，供理解调用逻辑参考。

NacosSkillRepository 根据 version / label 自动选择下载方式（version 优先）：

1. 若 skillVersion 非空 → AiService.downloadSkillZipByVersion(name, version)

2. 否则若 skillLabel 非空 → AiService.downloadSkillZipByLabel(name, label)

3. 否则 → AiService.downloadSkillZip(name)