Skip to main content
agentscope-extensions-nacos uses Nacos as AgentScope’s unified control plane: register and discover A2A Agents, hot-load prompts, and host skills. It contains three sub-modules — pick the ones you need.

A2A registry & discovery

Add the dependency

Server side: register the AgentCard with Nacos

The example uses an A2A 1.0 AgentCard. version("1.2.3") identifies the Agent’s business version; the final AgentInterface argument, "1.0", identifies the interface protocol using the major and minor version required by A2A. Registering a higher business version does not establish support for a higher protocol version. Interface metadata takes effect when publishing a new version. Registering an already published version does not overwrite it; publish a new business version to correct an existing record. The example sets setAsLatest(true). When publication review is disabled, registration automatically publishes the version, and consumers can discover it once publication completes.
With setAsLatest(false), subsequent new versions may remain drafts and need to be published in the Nacos console; the first version is still submitted automatically. If publication review is enabled, complete the required review and publication steps in the console even when this option is true.
Endpoint update compatibility: with Nacos 3.3, registering the same Agent version again replaces that client’s complete endpoint set for the version. Pass every endpoint you want to retain to registry.registerAgent(...). Do not deregister the old address after registering its replacement: that would remove the version’s entire registration. Registrations from other clients are unaffected.
A2A 1.0 field compatibility: for multi-tenancy, set the third AgentInterface argument to the tenant. Registration preserves each interface’s tenant and protocol version. Runtime addresses match Card interfaces by transport, preferring a matching URL when there are multiple candidates. Registration rejects remaining ambiguity in tenant or protocol version. A2A skill-level securityRequirements cannot yet be fully preserved, and importing standard A2A 1.0 JSON with security requirements is not yet compatible. The example registers a Java object; successful registration does not mean that every A2A 1.0 field is supported.

Client side: resolve a remote AgentCard via Nacos

Discovery automatically selects the API supported by the Nacos server. You can still set -Dagentscope.nacos.a2a.discovery.mode=a2a or rad explicitly; auto selects automatically. The option is read at construction, and the API is selected on the first lookup and retained for the resolver’s lifetime.
Upgrade note: RAD-capable servers now use native discovery by default. If the agent or selected version or label is deleted, getAgentCard(...) returns null and recovers automatically after recreation. Explicit a2a mode preserves the previous behavior of retaining the last AgentCard. The first RAD lookup waits up to 10 seconds after subscription returns for initial state; a timeout is reported, and later lookups reuse the same subscription. Unknown capability or query failures are reported without automatic fallback; retry after the connection is ready. Discovery results that cannot be represented as A2A Cards also produce conversion errors.

Prompt config center

Add the dependency

Usage

This example selects the prod label. To pin a version, set the second argument to a version such as "1.0.0" and the third to null. Call arguments override the template’s variable defaults. The last argument provides a fallback template when the prompt is missing, empty, or cannot be retrieved. Template updates and label changes in Nacos synchronize automatically without restarting the application. Call getPrompt(...) whenever you need to generate a prompt; strings already returned do not change automatically.
Upgrade note: Prompt version and label are now validated as mutually exclusive. If an existing call supplies both, change it to specify only one; otherwise it throws IllegalArgumentException.

Skill repository

agentscope-extensions-nacos-skill provides an AgentSkillRepository implementation that downloads and parses skill ZIP packages managed by the Nacos AI module.
Version/label resolution order: Properties provided to the constructor → JVM -D system properties → environment variables. When both version and label resolve, version wins and the label is not used for download. After publishing a new Skill version in Nacos, call getSkill(...) again and load the returned Skill into the Agent. Skills already loaded are not replaced automatically. If you pinned a version, first update the version setting and recreate the repository.

Pairs well with

  • A2A: inject a Nacos-backed AgentRegistry into AgentScopeA2aServer.builder().agentRegistry(...) to publish AgentCards cluster-wide on startup.
  • Skill repositories: coexist with Git/MySQL AgentSkillRepository to assemble a Toolkit from multiple sources.