Listing AgentScope Agents on HiMarket

Table of Contents

• Overview
• Part 1: Develop and Register AgentScope Agent to Nacos
  • Environment Preparation
  • Develop Agent
  • Configure Nacos Registration
  • Verify Registration
• Part 2: Import Nacos Instance into HiMarket
• Part 3: Create and Associate Agent Product
• Part 4: Publish to Portal
• FAQ

Overview

What is AgentScope?

AgentScope is a development framework for building AI Agent applications that supports rapid construction of intelligent dialogue agents, tool invocation, and multi-agent collaboration capabilities.

Technical Architecture

The complete chain for listing AgentScope Agents on HiMarket:

AgentScope Java Agent (Development)
        ↓
    Register to Nacos (Agent Registry)
        ↓
HiMarket Imports Nacos Instance (Connect Data Source)
        ↓
Create Agent Product and Associate (Pull Configuration)
        ↓
   Publish to Portal (Visible to Users)

Core Concepts

• AgentScope Runtime: AgentScope runtime environment that supports the A2A protocol
• A2A Protocol: Agent-to-Agent protocol for standardized communication between agents
• Nacos: Agent registry that stores agent configurations and metadata
• HiMarket: API and Agent product management platform that provides a unified display and management portal

Language Support

Part 1: Develop and Register AgentScope Agent to Nacos

Environment Preparation

1.1 Prerequisites

• Java 17 or higher
• Maven 3.6 or higher
• Nacos Server 3.1.0 or higher
• DashScope API Key (or other LLM service)

1.2 Start Nacos Server

Download and Start:

# Linux/Mac
sh bin/startup.sh -m standalone

# Windows
cmd bin/startup.cmd -m standalone

Verify by accessing the console: http://localhost:8848/nacos

For detailed installation steps, refer to: Nacos Quick Start

Develop Agent

2.1 Add Maven Dependencies

Add to pom.xml:

Version Requirement: AgentScope and AgentScope Extensions require version 1.0.3 or higher.

<properties>
    <agentscope.version>1.0.3</agentscope.version>
    <agentscope-extensions.version>1.0.3</agentscope-extensions.version>
    <spring-boot.version>3.5.7</spring-boot.version>
</properties>
<dependencies>
    <!-- Spring Boot -->
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-core</artifactId>
        <version>${agentscope.version}</version>
    </dependency>
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-a2a-spring-boot-starter</artifactId>
        <version>${agentscope.version}</version>
    </dependency>
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-a2a-nacos-spring-boot-starter</artifactId>
        <version>${agentscope-extensions.version}</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring-boot.version}</version>
    </dependency>

</dependencies>

2.2 Create Spring Boot Main Class

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class A2aRegistryExampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(A2aRegistryExampleApplication.class, args);
    }
}

2.3 Create Configuration File

Configure in src/main/resources/application.yaml:

server:
  port: 8888

agentscope:
  dashscope:
    api-key: ${AI_DASHSCOPE_API_KEY}
  agent:
    enabled: true
    name: customer-service-agent
    sys-prompt: "You are an intelligent customer service assistant who can answer user questions"
  a2a:
    server:
      card:
        description: "Example of A2A(Agent2Agent) Protocol Agent"
        provider:
          organization: Alibaba Nacos
          url: https://nacos.io
      nacos:
        server-addr: ${NACOS_SERVER_ADDRESS:127.0.0.1:8848}
        username: ${NACOS_USERNAME:nacos}
        password: ${NACOS_PASSWORD:nacos}

2.4 Core Configuration Explanation

Agent Configuration

Configuration related to the Agent itself, used to define the basic properties and behavior of the Agent.

AgentCard Configuration

AgentCard-related configuration exposed by the Agent through the A2A protocol, used to describe the metadata information of the Agent. More supported fields can be found in the AgentCard definition in the A2A protocol.

Nacos Configuration

Configuration related to the Nacos agent registry, used to register the Agent to the Nacos agent registry.

Server Configuration

Basic server configuration used to set server-level parameters such as service listening ports.

2.5 MSE Nacos Configuration (Optional)

If using Alibaba Cloud MSE Nacos:

agentscope:
  a2a:
    server:
      nacos:
        endpoint: ${NACOS_ENDPOINT:your-endpoint.mse.aliyuncs.com}
        namespace: ${NACOS_NAMESPACE:your-namespace-id}
        access-key: ${NACOS_ACCESS_KEY}
        secret-key: ${NACOS_SECRET_KEY}

2.6 Start Application

Set environment variables:

export AI_DASHSCOPE_API_KEY=your_api_key
export NACOS_USERNAME=nacos
export NACOS_PASSWORD=nacos

Run the application:

mvn spring-boot:run

Verify Registration

3.1 Check Logs

Confirm you see the following logs:

Auto register agent customer-service-agent into Registry Nacos.
Auto register agent customer-service-agent into Registry Nacos successfully.

3.2 Access Nacos Console

1. Open http://localhost:8848/nacos
2. Go to “Agent Management” → “Agent List”
3. Find the customer-service-agent Agent
4. Click Details to view Agent Card

Part 2: Import Nacos Instance into HiMarket

Import Process

After logging into the HiMarket Admin backend, go to the “Nacos Instance Management” page.

Click “Import/Create Instance” and choose the import method.

Method A: Import from MSE (Recommended)

Step 1: Enter Alibaba Cloud Credentials

Select “MSE Nacos” and fill in:

• Region: Alibaba Cloud region (e.g. cn-hangzhou)
• Access Key: Alibaba Cloud AK
• Secret Key: Alibaba Cloud SK

Click “Get Instance List”

Step 2: Select Instance

Select the target MSE Nacos instance from the list and click “Import”

Step 3: Supplement Information

The system will auto-fill information. Supplement:

• Server Address: Select public or private network address
• Username/Password: Nacos authentication information

Click “Create”

Method B: Manually Create Open Source Nacos

Select “Open Source Nacos” and manually fill in:

• Instance Name: e.g. “Development Environment Nacos”
• Server Address: e.g. http://localhost:8848
• Username/Password: Nacos authentication information
• Description: Instance description

Click “Create”

Part 3: Create and Associate Agent Product

Create Product

1. Go to API Products

Click “API Products” in the left navigation

2. Create Product

Click “Create API Product” and fill in:

Click “Create”

Associate Nacos Agent

1. Go to Association Page

Go to the product details page and click the “Link API” tab, then click “Associate API”

2. Select Data Source

In the pop-up dialog:

Step 1: Select “Nacos” as the data source type

Step 2: Select the previously imported Nacos Instance

Step 3: Select Namespace (e.g. public)

Step 4: Select Agent (e.g. customer-service-agent)

3. Confirm Association

Click “Associate”, and the system will:

1. Connect to the Nacos instance
2. Pull the complete Agent configuration (Agent Card, protocol, routing, etc.)
3. Save to HiMarket database
4. Update product status to READY

After successful association, you can view the Agent configuration details:

The configuration includes:

• Supported Protocols: a2a, http
• Agent Card: Name, Version, Description, URL
• Skill List: Agent capability tags

Improve Usage Documentation (Optional)

Click the “Usage Guide” tab and write usage instructions (Markdown format):

Part 4: Publish to Portal

Publishing Process

1. Go to Publishing Page

Click the “Portal” tab

2. Select Portal

Click “Publish to Portal” and select target portals (multiple selections allowed):

3. Confirm Publication

Click “Publish” and the product will be discoverable and usable by users on the portal.

User Access

After users access the HiMarket portal:

1. Browse Agent Market: Click “Agents” on the homepage
2. Search for Agent: Use keywords to search or filter by category
3. View Details: Click the Agent card to go to the details page
4. View Configuration:
   • Overview Tab: View usage guide
   • Configuration Tab: View Agent Card, protocols, routing, and other technical information
5. Invoke Agent: Call the Agent API according to the configuration information

FAQ

Q1: Agent registration to Nacos failed?

Possible Causes:

• Nacos Server not started or inaccessible
• Nacos Server version lower than 3.1.0
• Incorrect authentication information

Solutions:

• Confirm Nacos Server is running properly
• Check server-addr, username, password configuration
• Check detailed error messages in application logs

Q2: Cannot find registered Agent in HiMarket?

Possible Causes:

• Nacos instance not correctly imported into HiMarket
• Incorrect namespace selection
• Agent registration failed

Solutions:

• Verify Nacos instance connection in HiMarket
• Confirm Agent is registered in Nacos console
• Check if namespace configuration is consistent

Q3: Incomplete configuration information after association?

Possible Causes:

• Agent configuration in Nacos does not conform to A2A specification
• Network issues causing configuration pull failure

Solutions:

• Check Agent metadata in Nacos console
• Ensure Agent Card information is complete
• Try unlinking and re-associating

Q4: How to update Agent configuration?

Update Process:

1. Modify configuration in Agent code
2. Restart Agent application to re-register to Nacos
3. Click “Unlink” on the HiMarket product details page
4. Re-associate the same Agent
5. System will pull the latest configuration

Note: Unlinking will not delete the product, only disconnect from the Agent.

Q5: Users cannot see the product after publication?

Checklist:

• Is the product status READY or PUBLISHED
• Has it been successfully published to the target portal
• Is the portal address accessed by users correct
• Do users have access permissions to that portal

Complete Example Code

The code examples in this document show key configurations. For a complete, runnable example project, please refer to:

📦** GitHub Sample Project**: agentscope-extensions-nacos/java/example/a2a-example

Includes:

• Agent registration example
• Agent discovery and invocation example
• Complete Maven project configuration
• Detailed README instructions

More Resources

• AgentScope Official Documentation
• Nacos Official Documentation
• AgentScope Extensions Nacos GitHub
• HiMarket Product Documentation