Access AI Registry with the Nacos Java SDK - Microservices Engine

Note

The Java SDK provides consumer-side capabilities only for Skills and Prompts. For lifecycle management operations such as uploading, reviewing, and publishing, use the console or Connect Nacos CLI to AI Registry.

Prerequisites

An activated Alibaba Cloud MSE AI Registry instance with a workspace created.
An Alibaba Cloud AccessKey ID and AccessKey secret. The associated RAM user must have read permissions for Skills and Prompts. For instructions, see Configure RAM Permissions for AI Registry.
JDK 8 or later installed in your Java development environment.
Network access configured based on your application's deployment location:
- Local development, IDC, or non-VPC environments — Configure a public network endpoint and IP address whitelist.
- Alibaba Cloud VPC — Configure VPC private network access.

Add the Maven dependency

Add the Nacos Java SDK dependency to your project.

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>${nacos.version}</version>
</dependency>

The following table lists SDK capabilities and their minimum version requirements:

Capability	Minimum nacos-client version
`downloadSkillZip` / `downloadSkillZipByVersion` / `downloadSkillZipByLabel`	3.2.0
`subscribeSkill` / `unsubscribeSkill`	3.2.2
Prompt-related APIs	3.2.3

Note

If you use both download and subscription capabilities, use nacos-client 3.2.2 or later. If you also need Prompt-related APIs, use nacos-client 3.2.3 or later.

Configure access credentials

Step 1: Choose an access method

Choose a network access method based on where your application is deployed:

Public network access — For local development, IDC, or applications not deployed in an Alibaba Cloud VPC. Add a public network endpoint and add your application's outbound public IP address to the whitelist. For configuration steps, see the AI Registry public network access configuration guide (documentation forthcoming).
VPC private network access — For applications deployed in an Alibaba Cloud VPC. Complete the PrivateLink configuration by following AI Registry VPC Privatelink Configurations. After configuration, you receive a private domain name in the format airegistry.{region-id}.mse.aliyuncs.com.

Step 2: Initialize AiService

Configure initialization parameters in a Properties object and call AiFactory.createAiService(properties) to create an AiService instance. Set SERVER_ADDR to the public endpoint or VPC private domain obtained in Step 1.

Properties properties = new Properties();
// For VPC private network access:
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
// For public network access, use the following format instead:
// properties.setProperty(PropertyKeyConst.SERVER_ADDR, "xxxx.airegistry.cn-hangzhou.mse.aliyuncs.com:80");
properties.setProperty(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
properties.setProperty(PropertyKeyConst.ACCESS_KEY, "LTAI5tXXXXXXXXXXXXXX");
properties.setProperty(PropertyKeyConst.SECRET_KEY, "XXXXXXXXXXXXXXXXXXXXxx");

AiService aiService = AiFactory.createAiService(properties);

The following table describes the configuration parameters:

Parameter	Description	Example
`serverAddr`	The AI Registry access address in `{host}:{port}` format. Use the public endpoint for public network access, or the VPC private domain for VPC access.	VPC private: `airegistry.cn-hangzhou.mse.aliyuncs.com:80` · Public: `xxxx.airegistry.cn-hangzhou.mse.aliyuncs.com:80`
`namespace`	The namespace ID of your AI Registry workspace. You can find this value on the Workspace page in the console.	`xxxxxx-xxxx-xxxx-xxxx-xxxxxx`
`accessKey`	Your Alibaba Cloud AccessKey ID.	`LTAI5tXXXXXXXXXXXXXX`
`secretKey`	Your Alibaba Cloud AccessKey secret.	`XXXXXXXXXXXXXXXXXXXXxx`

Note

One AiService instance corresponds to one namespace. To access multiple namespaces, create separate instances. Reuse the same instance within your application where possible, and call shutdown() to release resources when the application exits.

Verify configuration

After the SDK is initialized, call aiService.downloadSkillZip(...) or a Prompt API to retrieve resources. If data is returned, the credentials are configured correctly.

If the call fails, check the following:

Authentication failure — Verify that your AccessKey ID, AccessKey secret, and RAM permissions are correct.
Public network access — Verify that your application's outbound public IP address is added to the whitelist.
VPC private network access — Verify the ECS VPC, security group, and private domain configuration.

SDK capabilities overview

AiService provides consumer-side interfaces for Skills and Prompts. For more information, see Nacos Java SDK Usage.

Skill capabilities

Download Skill ZIP archives by name, version, or label, and subscribe to change notifications:

API	Description
`downloadSkillZip(skillName)`	Downloads the latest version of a Skill ZIP.
`downloadSkillZipByVersion(skillName, version)`	Downloads the ZIP of a specified version.
`downloadSkillZipByLabel(skillName, label)`	Downloads the ZIP of the version bound to a label, for example, `latest`.
`subscribeSkill(skillName, version, label, listener)`	Subscribes to Skill change notifications. The listener callback is triggered when content is updated.
`unsubscribeSkill(skillName, version, label, listener)`	Cancels a Skill subscription.

The returned ZIP byte array contains SKILL.md and all resource files. Binary resources are automatically decoded from Base64.

Prompt capabilities

Retrieve Prompt content by name or version, and subscribe to change notifications:

API	Description
`getPrompt(promptKey)`	Retrieves the latest version of Prompt content as a JSON string.
`getPromptByVersion(promptKey, version)`	Retrieves Prompt content of a specified version.
`subscribePrompt(promptKey, version, listener)`	Subscribes to Prompt change notifications. The listener callback is triggered when content is updated.
`unsubscribePrompt(promptKey, version, listener)`	Cancels a Prompt subscription.

For complete API signatures, parameter descriptions, and code examples, see Nacos Java SDK Usage.

References

Nacos Java SDK Usage: Complete API signatures, parameter descriptions, and code examples.
AI Registry Skill Quick Start: Complete workflow from creating or importing a Skill in the console to CLI, SDK, and AgentScope integration (documentation forthcoming).
Configure Public Network Access for AI Registry: Steps for configuring a public network endpoint and IP address whitelist (documentation forthcoming).
AI Registry VPC Privatelink Configurations: Steps for configuring VPC private network access.
AI Registry Skill Management Guide: Skill version management, publishing, and download through the console.