Agent Management

Nacos introduced A2A Agent registration and discovery in 3.1. In 3.3, Agent management becomes a general Agent resource model: it manages identity, catalog metadata, versioned call definitions and runtime endpoints, with search, discovery and subscriptions through RAD (Remote Agent Discovery).

A2A remains a supported integration. AgentCard is retained as the native descriptor of an A2A call interface, and existing A2A applications can continue to connect. This page covers management and publishing; see the RAD Integration Guide for a complete application example covering endpoint registration, discovery and subscriptions.

Nacos tells applications which Agent to use, how it can be called and where its endpoints are. Agent applications and their protocol clients perform the actual message, task and streaming calls.

1. Understanding Agent Resources

1.1. Identity, Catalog and Versions

An Agent is uniquely identified by namespaceId + agentName. Different namespaces can use the same name; names must be unique within a namespace. agentName is immutable after creation, case-sensitive, and contains 1–64 printable ASCII characters, with at least one non-space character. Use displayName for names containing other characters.

Versions use MAJOR.MINOR.PATCH, for example 1.0.0 or 1.1.0-rc.1, with a maximum of 64 characters and no +build suffix. Published version content cannot be overwritten. Updating the Agent’s catalog description or business tags does not require a new definition version.

Agent management covers callable Agents; AgentSpecs Management covers distributable specification packages. Each manages its own versions and lifecycle.

1.2. Call Protocols and Address Sources

callInterfaces is an ordered list of call interfaces. A protocol cannot appear twice in the same version. An A2A interface uses protocol=a2a, with its AgentCard as nativeDescriptor. Protocol-specific skills, capabilities and security schemes stay in the native descriptor.

Each call interface has two address sources:

endpointSourceOrder specifies the recommended order: ["RUNTIME", "DECLARED"] prefers runtime endpoints, while ["DECLARED", "RUNTIME"] prefers declared addresses. Both sources must appear exactly once. The order does not disable either source; consumers can explicitly filter sources during discovery.

Publishing a definition does not start the Agent application. Registering runtime endpoints does not create or publish a definition. Providers must keep declared addresses reachable; runtime endpoints also require health and version compatibility checks.

2. Prerequisites

• Use Nacos Server 3.3. For an existing cluster, complete the A2A migration steps in the Upgrading Manual before using the general Agent/RAD endpoints.
• Nacos 3.3 enables client authentication by default. Management accounts need permission to manage the target Agent; application accounts need the relevant read or endpoint write permissions. Follow Access Credentials to prepare NACOS_USERNAME and NACOS_PASSWORD. HTTP examples use NACOS_ACCESS_TOKEN saved after login.
• Use the same intended namespace for publishers and consumers. The examples use public.
• Prepare a running Agent application. http://127.0.0.1:9999/a2a is a local example address; replace it with an address reachable by consumers in your deployment.

The built-in visibility policy defaults new Agents to PUBLIC. For a private release, create a draft, set it to PRIVATE through the separate scope endpoint, then submit it for publication. Scope applies to the whole Agent; new versions and retries do not reset an existing private setting, and create requests do not accept scope directly. See Change a resource’s scope for examples.

Public visibility does not bypass authentication or grant write permission. See the Visibility Plugin for defaults and explicit grants. Nacos login credentials do not replace credentials required by the Agent service itself.

3. Creating and Publishing an Agent

3.1. Managing Through the Console

1. Open Agent Management in the AI Registry, select the namespace and click Create Agent.
2. If you have an AgentCard, choose Import a known protocol, paste the complete A2A AgentCard and verify the name, version and interface addresses in the preview. Alternatively, choose Create from scratch and enter the catalog metadata, initial version and call protocol.
3. Saving creates a draft. Check its content, endpoint source order and visibility, then submit it for review.
4. Without a configured review workflow, submission publishes the version immediately. If a review workflow is configured, wait for approval, then publish the version.
5. Inspect the definition and runtime endpoint area in the version details, then verify discovery and actual calls from a consumer.

Use Edit Metadata to change catalog information and Edit Draft to modify an unpublished call definition. To change published content, choose Create draft from this version and specify a new version number.

3.2. Creating a Draft Through HTTP

Management integrations use endpoints under /nacos/v3/admin/ai/agents. This example creates the route-planner Agent and its 1.0.0 draft. Save the following call definition as agent-call-interfaces.json:

[
  {
    "protocol": "a2a",
    "protocolVersion": "0.3.0",
    "descriptorMediaType": "application/json",
    "nativeDescriptor": {
      "protocolVersion": "0.3.0",
      "name": "route-planner",
      "description": "Plan a route between two locations.",
      "url": "http://127.0.0.1:9999/a2a",
      "preferredTransport": "JSONRPC",
      "version": "1.0.0",
      "capabilities": {"streaming": false},
      "defaultInputModes": ["text"],
      "defaultOutputModes": ["text"],
      "skills": [
        {
          "id": "plan-route",
          "name": "Route planning",
          "description": "Plan a route between two locations.",
          "tags": ["routing"]
        }
      ]
    },
    "endpointSourceOrder": ["RUNTIME", "DECLARED"],
    "endpointSets": [
      {
        "source": "DECLARED",
        "endpoints": [
          {"uri": "http://127.0.0.1:9999/a2a", "transport": "JSONRPC"}
        ]
      }
    ]
  }
]

This is an A2A 0.3.0 descriptor example. For another A2A version, provide its complete AgentCard and keep its name and version consistent with the enclosing Agent definition. When submitting the general HTTP form directly, keep the AgentCard addresses and DECLARED endpoints consistent. The Console A2A import flow performs this conversion.

Run the following Bash command from the directory containing the file:

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/admin/ai/agents/draft' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'agentName=route-planner' \
  --data-urlencode 'version=1.0.0' \
  --data-urlencode 'description=Plan a route between two locations.' \
  --data-urlencode 'tags=["routing"]' \
  --data-urlencode 'callInterfaces@agent-call-interfaces.json'

Complex fields such as callInterfaces and tags are JSON strings inside the form, not a JSON request body. A successful creation leaves the version in draft; ordinary runtime discovery cannot use it yet.

3.3. Submitting and Checking the Result

Submit the draft:

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/admin/ai/agents/submit' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'agentName=route-planner' \
  --data-urlencode 'version=1.0.0'

Check the response and version status. When review is required, inspect the result in the Console or read the exact version:

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/admin/ai/agents/version' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'agentName=route-planner' \
  --data-urlencode 'version=1.0.0'

Run the publish command below only when the version is reviewed and approved. If it is already online, proceed to discovery verification. If review failed, inspect the reason before redrafting or resubmitting.

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/admin/ai/agents/publish' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'agentName=route-planner' \
  --data-urlencode 'version=1.0.0'

3.4. Subsequent Versions and Publishing from Code

An Agent can have at most one editing version and one reviewing version. For a subsequent draft, either supply new callInterfaces or copy an existing exact version with basedOnVersion; do not provide both. After copying, update protocol descriptor versions, addresses and other content in the draft before submission.

The two SDK publication APIs behave differently:

• The older A2A releaseAgentCard API publishes the first version immediately and makes it the latest version (latest), even with setAsLatest=false. Later new versions also go online immediately; setAsLatest=true makes them latest, while false keeps the previous latest version.
• The new RAD publishAgent API automatically attempts to publish the first version regardless of autoSubmit. For later new versions or existing drafts, autoSubmit=false saves a draft and true submits it for publication.

“First version” means the Agent has no versions yet; an existing draft counts as a version. Automatic publication through the new API follows any configured review workflow, so approval may still be needed. Check the returned AgentVersionDetail.getStatus() to confirm that the version is online.

Compatibility in the 3.3 SDK: when releaseAgentCard connects to a server that supports RAD, the SDK automatically uses the new publication workflow. No manual selection is needed. In this case, setAsLatest acts like autoSubmit: for later versions, false saves a draft and true submits it. The method has no return value; check publication status in the console.

The new API can update drafts. Versions already submitted for review, online or offline remain unchanged; create a new version to change their content. After a publication timeout, check whether the version was saved or published before retrying.

See AI Resource Lifecycle for state and operation rules. Standard publishing or bringing a version online sets latest to that version. Taking the current latest offline selects the greatest remaining online version. The server manages latest; custom labels cannot overwrite it.

4. Discovering and Using Agents

4.1. Search, Discover and Watch

Search’s agentNameContains is case-sensitive; tagsAll requires every tag to match exactly; protocolsAny requires at least one online version to expose any specified protocol. These are Agent catalog filters, not semantic search over arbitrary AgentCard skills or descriptions. A Search match does not guarantee healthy endpoints.

After querying the catalog, use Discover to get call addresses, then call the Agent with an A2A or other appropriate protocol client. See the RAD Integration Guide for examples, filters and subscription cleanup.

4.2. Choosing Versions Explicitly

version and label are mutually exclusive. Applications that must strictly follow the latest definition should explicitly set label=latest. When pinning a version or using a rollout label, verify that the target version is online. Filters only narrow the selected definition’s interfaces and addresses; they do not select another version.

5. A2A Integration and Compatibility

5.1. AgentCard and the General Agent Model

An A2A AgentCard is stored as the nativeDescriptor of a protocol=a2a call interface. The Card’s name and version identify the Agent and version; its interface URLs provide declared addresses. Existing A2A APIs still publish, query and subscribe to Cards. General RAD APIs return discovery results containing the native Card and endpoint sets.

• Existing A2A applications can continue using releaseAgentCard, getAgentCard and subscribeAgentCard. The 3.3 SDK adapts to the server automatically; no manual RAD selection is needed. See section 3.4 for publication behavior changes.
• New applications can directly use the RAD APIs: searchAgents, discoverAgent, subscribeAgent and registerAgentEndpoints. The server must support RAD. See the RAD Integration Guide for complete examples.

When one SDK instance registers A2A addresses for the same Agent, use the registration and deregistration methods from either the older A2A API or the new RAD API consistently. Configure Nacos access credentials separately from credentials for calling the Agent service.

5.2. Custom A2A Applications

The 3.3 Java SDK retains AgentCard operations through the following entry point. agentCard must be the complete Card supplied by the application:

import com.alibaba.nacos.api.ai.AiFactory;
import com.alibaba.nacos.api.ai.AiService;
import com.alibaba.nacos.api.ai.AgentService;
import com.alibaba.nacos.api.ai.model.a2a.AgentCard;
import java.util.Properties;

Properties properties = new Properties();
properties.setProperty("serverAddr", "127.0.0.1:8848");
properties.setProperty("namespace", "public");
properties.setProperty("username", System.getenv("NACOS_USERNAME"));
properties.setProperty("password", System.getenv("NACOS_PASSWORD"));
AiService aiService = AiFactory.createAiService(properties);
AgentService agentService = aiService.agent();

try {
    // Publish the application's complete AgentCard. See section 3.4 for version behavior.
    agentService.releaseAgentCard(agentCard, "SERVICE", false);
} finally {
    aiService.shutdown();
}

This fragment publishes the application’s complete Card. Confirm online status through management first, then register runtime endpoints and query or subscribe from consumers; see the Java SDK guide. Keep runtime clients alive, deregister endpoints through the same instance and close it on exit.

With the older subscribeAgentCard API, the SDK protects subscribers by default when an AgentCard is deleted or temporarily cannot be found: it does not pass null or an empty Card to the listener, or send a deletion notification.

To integrate with the legacy A2A management HTTP endpoint, save a complete AgentCard as agent-card.json and import it:

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/admin/ai/a2a' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'agentCard@agent-card.json'

This submits the Card itself; do not use the callInterfaces array file from section 3. This endpoint follows the legacy A2A compatibility path described above. Management integrations that require draft review should use the general Agent management endpoint.

5.3. Publish Agent by Spring AI Alibaba

The following retains the Spring AI Alibaba 1.0.0.4 integration example for applications already using that version. Check dependencies and configuration for other framework versions against its version guide and A2A guide. Upgrading Nacos Server does not automatically upgrade the framework’s Nacos Client dependency; publishing behavior depends on the actual Client version and selected integration.

5.3.1. Dependencies

<!-- Spring AI Alibaba version 1.0.0.4 -->
<properties>
    <spring.ai.alibaba.version>1.0.0.4</spring.ai.alibaba.version>
</properties>

<dependencies>
    <!-- A2A Server starter -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-a2a-server</artifactId>
        <version>${spring.ai.alibaba.version}</version>
    </dependency>
    <!-- A2A Nacos Registry -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-a2a-registry</artifactId>
        <version>${spring.ai.alibaba.version}</version>
    </dependency>
    <!-- The Bailian LLM client can be substituted with other Spring AI LLM clients, such as OpenAI. -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        <version>${spring.ai.alibaba.version}</version>
    </dependency>
</dependencies>

5.3.2. Code Agent

The following demonstrates how to use the Agentic API defined in Spring AI Alibaba to rapidly define and build agent execution logic. This example creates an Agent that directly accesses LLM:

@Configuration
public class RootAgentConfiguration {

    @Bean
    @Primary
    public BaseAgent rootAgent(ChatModel chatModel) throws GraphStateException {
        return ReactAgent.builder().name("{your_agent_name}").description("{your_agent_description}").model(chatModel)
                .instruction("{your_agent_system_prompt}").build();
    }
}

5.3.3. Agent Auto-register properties

server:
  port: 9999

spring:
  application:
    name: a2a-server-example
  ai:
    # options for LLM, such as API_KEY, model type.
    dashscope:
      api-key: ${BAILIAN_API_KEY}
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      chat:
        options:
          model: qwen-plus-latest
    alibaba:
      a2a:
        # Address,username and password of Nacos.
        nacos:
          server-addr: ${NACOS_ADDRESS:localhost:8848}
          username: ${NACOS_USERNAME:nacos}
          password: ${NACOS_PASSWORD}
        # extension information for agent in AgentCard, such as skills, provider and so on.
        server:
          version: 1.0.1
          card:
            # URL of agent, if no endpoint can be access, this url will be used.
            url: http://localhost:9999/a2a
            skills:
              - id: nacos-question-answer
                name: Nacos Question Answer
                description: Answer questions about Nacos.
                tags:
                  - Nacos
                examples:
                  - What is Nacos?
            icon-url: https://img.alicdn.com/imgextra/i4/O1CN01rW3vAB1FDWKSOiFf0_!!6000000000453-2-tps-204-40.png
            documentation-url: https://nacos.io
            provider:
              organization: Alibaba
              url: https://www.alibaba.com

5.3.4. Bootstrap A2A Server Agent

Start the A2A Server (for example, with mvn spring-boot:run), then inspect its Agent version status and endpoints in the Nacos Console. If the actual Client publishes into a review flow, complete review and publishing before verifying calls.

5.4. Query/Subscriber and Request Agent by Spring AI Alibaba

5.4.1. Dependencies

<!-- Spring AI Alibaba version 1.0.0.4 -->
<properties>
    <spring.ai.alibaba.version>1.0.0.4</spring.ai.alibaba.version>
</properties>

<dependencies>
    <!-- A2A Client starter -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-a2a-client</artifactId>
        <version>${spring.ai.alibaba.version}</version>
    </dependency>
    <!-- A2A Nacos Registry -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-a2a-registry</artifactId>
        <version>${spring.ai.alibaba.version}</version>
    </dependency>
</dependencies>

5.4.2. Code A2A Agent Client

Spring AI Alibaba’s Agentic API provides declarative methods for invoking Agents, enabling developers to quickly build A2A Agent clients.

@Configuration
public class RootAgentConfiguration {

    @Bean
    public BaseAgent rootAgent(AgentCardProvider agentCardProvider) throws GraphStateException {
        return A2aRemoteAgent.builder()
                // Using Nacos AgentCard Provider autowired by spring starter
                .agentCardProvider(agentCardProvider)
                // set the name of agent, and Nacos AgentCard Provider will use this name to query and subscribe AgentCard.
                .name("{remote_agent_name}").description("{remote_agent_description}").build();
    }
}

5.4.3. Agent Auto-discovery properties

spring:
  application:
    name: a2a-client-example
  ai:
    alibaba:
      a2a:
        nacos:
          # enabled auto-discovery from nacos.
          discovery:
            enabled: true
          server-addr: ${NACOS_ADDRESS:localhost:8848}
          username: ${NACOS_USERNAME:nacos}
          password: ${NACOS_PASSWORD}

5.4.4. Calling or request for A2A Agent Client

At runtime, obtain the pre-built A2A Agent Client for invocation. The Agent will automatically subscribe to the AgentCard and service endpoints of Agents in Nacos, and select an available endpoint for invocation, such as:

@RestController
@RequestMapping("/")
public class TestController {

    private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(TestController.class);

    private final BaseAgent rootAgent;

    public TestController(BaseAgent rootAgent) {
        this.rootAgent = rootAgent;
    }

    @GetMapping("stream")
    public Flux<String> stream(@RequestParam("question") String question)
            throws GraphStateException, GraphRunnerException {
        return rootAgent.stream(Map.of("messages", List.of(new UserMessage(question)))).mapNotNull(output -> {
            LOGGER.debug("stream agent invoke : `{}`", output.toString());
            if (output.isSTART() || output.isEND()) {
                return null;
            }
            if (output instanceof StreamingOutput) {
                return ((StreamingOutput) output).chunk();
            }
            return null;
        }).publishOn(Schedulers.parallel());
    }
}

6. Troubleshooting