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
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
-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
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.
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
AgentRegistryintoAgentScopeA2aServer.builder().agentRegistry(...)to publish AgentCards cluster-wide on startup. - Skill repositories: coexist with Git/MySQL
AgentSkillRepositoryto assemble a Toolkit from multiple sources.