Microservices Engine：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)