Microservices Engine:Integrate AgentScope with Nacos AI Registry to Use Skills

Example

The following is an end-to-end runnable example showing the complete flow from initializing the Nacos connection to starting an agent conversation. Replace SERVER_ADDR with the public endpoint domain or VPC private domain:

import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.ai.AiFactory;
import com.alibaba.nacos.api.ai.AiService;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.nacos.skill.NacosSkillRepository;
import io.agentscope.core.skill.AgentSkill;
import io.agentscope.core.skill.SkillBox;
import java.util.Properties;

public class NacosSkillDemo {

    public static void main(String[] args) throws Exception {
        // 1. Create AiService
        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, "your-access-key");
        props.put(PropertyKeyConst.SECRET_KEY, "your-secret-key");

        AiService aiService = AiFactory.createAiService(props);

        // 2. Create NacosSkillRepository and load a Skill
        try (NacosSkillRepository repo = new NacosSkillRepository(aiService, "public")) {
            AgentSkill skill = repo.getSkill("safe-commit-helper");
            System.out.println("Loaded: " + skill.getName());
            System.out.println("Description: " + skill.getDescription());

            // 3. Bind to Agent
            // SkillBox reads Skills from the repository on demand. The getSkill call above
            // demonstrates that a Skill exists; the SkillBox itself uses the repository
            // directly when the agent invokes tool calls during conversation.
            SkillBox skillBox = new SkillBox(repo);

            var model = DashScopeChatModel.builder()
                    .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                    .modelName("qwen-max")
                    .build();

            var agent = ReActAgent.builder()
                    .name("DevAssistant")
                    .systemPrompt("You are a programming assistant.")
                    .model(model)
                    .skillBox(skillBox)
                    .build();

            // 4. Use the Agent
            var response = agent.call(io.agentscope.core.message.Msg.of("Help me generate a commit message"));
            System.out.println(response.getText());
        } finally {
            aiService.shutdown();
        }
    }
}

1. Add Dependencies

Add the following dependency to your pom.xml:

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

For version management, use 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. Initialize AiService

Create a Nacos AiService instance and configure the AI Governance Center access address and credentials. SERVER_ADDR can be the public endpoint domain or VPC private domain:

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);

A single AiService instance corresponds to one namespace. If you need to access multiple namespaces, create a separate instance for each. Reuse instances within the same application and call aiService.shutdown() on exit to release resources.

3. Create NacosSkillRepository and Load a Skill

Create a NacosSkillRepository instance using try-with-resources:

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);
    }
}

If namespaceId is empty or null, "public" is used automatically. The skillExists check verifies the Skill before downloading; if it returns false, check the Skill name and namespace.

4. Bind Skills to the Agent

Load Skills from the repository into the agent through SkillBox:

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

SkillBox skillBox = new SkillBox(repo);

var model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen-max")
        .build();

var agent = ReActAgent.builder()
        .name("MyAgent")
        .systemPrompt("You are an intelligent assistant.")
        .model(model)
        .skillBox(skillBox)
        .build();

To verify the agent can use the Skill, send a test message and check that the response reflects Skill-generated content:

var response = agent.call(io.agentscope.core.message.Msg.of("Help me review my code."));
System.out.println(response.getText());

Download API Selection

NacosSkillRepository automatically selects the download method based on version and label (version takes priority):

1. If skillVersion is non-empty → AiService.downloadSkillZipByVersion(name, version)

2. Otherwise, if skillLabel is non-empty → AiService.downloadSkillZipByLabel(name, label)

3. Otherwise → AiService.downloadSkillZip(name)

Load by Version

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");
}

Load by Label

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");
}

Via Environment Variables

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

Via JVM System Properties

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

Priority Example

When Properties, JVM properties, and environment variables are all set, the value in Properties takes precedence:

// 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" takes effect here
NacosSkillRepository repo = new NacosSkillRepository(aiService, "public", props);
repo.getSkill("my-skill");  // actually calls downloadSkillZipByVersion("my-skill", "app-ver")

When both version and label are configured, version takes priority and label is ignored.