ARD Integration Guide

ARD (Agentic Resource Discovery) is an open specification for describing, searching, and discovering AI resources. The official specification credits Junjie Bu (Google), R. V. Guha (Microsoft), and Shaun Smith (Hugging Face) as authors. Its source is available in the official GitHub repository.

Nacos 3.3 provides ARD-compatible endpoints for searching Agents, Skills, Prompts, and MCP Servers and retrieving their artifacts.

This page covers server configuration and HTTP integration. For publishing requirements, result types, and how to use them, see ARD Resource Discovery in AI Registry. Applications that need Agent runtime endpoints or change subscriptions should use the RAD Integration Guide. RAD stands for Remote Agent Discovery and serves a different purpose.

1. Enable ARD

Configure the following in the Nacos Server conf/application.properties file:

nacos.ai.ard.enabled=true
nacos.ai.resource.search.enabled=true
nacos.ai.registry.port=9080
nacos.ai.ard.catalog.base-url=http://127.0.0.1:9080

Restart Nacos Server. ARD serves requests on a separate HTTP port. The base URL above is suitable for local verification; replace it with an address reachable by clients on other machines.

For an existing cluster, follow the Upgrade Guide to complete the 3.3 upgrade and database initialization first. Basic keyword search does not require a vector model or pgvector.

1.1. Access through a gateway

Set nacos.ai.ard.catalog.base-url to the complete public URL of the adaptor, including any gateway path prefix. For example:

nacos.ai.ard.catalog.base-url=https://nacos.example.com/ard

Returned resource URLs then start with https://nacos.example.com/ard/v3/ai/ard/. The gateway must forward requests under /ard/ to the adaptor port and remove that prefix. This property only affects returned URLs: it does not create gateway routes or append the main server’s /nacos path.

If clients discover the Registry through the host-root path /.well-known/ai-catalog.json, also forward that path to the same path on the adaptor. With the default configuration, direct requests to port 9080 do not include /nacos.

1.2. Enhance resource discovery with a vector plugin

To add retrieval of similar content, configure the AI Vector Plugin. Once configured and indexed, ARD search combines keyword and vector results. Clients continue using the search requests shown in this guide.

The plugin is optional. Installing pgvector does not automatically integrate an external embedding model. See the plugin guide for the default embedding method, database preparation, relevance evaluation, and troubleshooting. Publishing, visibility, and authentication requirements remain unchanged.

2. Prepare resources and credentials

1. Publish at least one resource in Nacos for verification. For example, follow Agent Management to create route-planner in the public namespace and publish version 1.0.0.
2. Confirm that the resource is enabled and latest points to an online version. Grant the integration account the required read permissions.
3. Sign in as described in Configure Access Credentials and save the returned accessToken in the same terminal.

The following commands use Bash. On Windows, use Git Bash or WSL:

export ARD_BASE_URL='http://127.0.0.1:9080'
export NACOS_ACCESS_TOKEN='<accessToken-from-login-response>'

The default authentication plugin’s login endpoint is on the main server, for example http://127.0.0.1:8848/nacos/v3/auth/user/login. ARD requests use port 9080 and carry that token in the accessToken header. Sign in again when the token expires.

Nacos 3.3 enables client authentication by default, and ARD also requires valid credentials. With the default authentication plugin, anonymous reads are allowed only when nacos.plugin.auth.nacos.anonymous.ai.enabled=true is explicitly configured, and anonymous callers can discover only public resources. Requests carrying an invalid or expired token still return 401 UNAUTHENTICATED; they do not fall back to anonymous access. PUBLIC is a visibility scope, not a replacement for anonymous-access settings or API permissions. See Visibility Plugin for resource-specific defaults and scope changes, and ARD Resource Discovery for publishing requirements.

3. Search resources

curl -sS -X POST "${ARD_BASE_URL}/v3/ai/ard/search?namespaceId=public" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text": "route",
      "filter": {
        "type": ["application/a2a-agent-card+json"]
      }
    },
    "federation": "none",
    "pageSize": 10
  }'

query.text is required. This example searches only resources that can export an A2A AgentCard. Remove filter to search all four resource types; see ARD Resource Discovery for other type values.

query.filter filters by fields such as type, tags, and capabilities. Values within one field’s array are matched with OR; different fields are combined with AND. namespaceId is a Nacos extension and should be passed as a URL query parameter. It defaults to public.

The search response is an ARD JSON object with these main fields:

Search pageSize defaults to 10 and has a maximum of 50. federation accepts auto, referrals, and none, with auto as the default. Without an upstream Registry configured, all three modes search only local resources.

4. Browse resources and explore facets

4.1. List resources with pagination

Use /agents to browse without keywords. Despite its name, this endpoint also returns Skills, Prompts, and MCP Servers.

curl -sS -G "${ARD_BASE_URL}/v3/ai/ard/agents" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode "filter=type = 'application/a2a-agent-card+json'" \
  --data-urlencode 'orderBy=displayName' \
  --data-urlencode 'pageSize=20'

The list response uses items. When pageToken is present, pass it as a query parameter to retrieve the next page. pageSize defaults to 20 and has a maximum of 100. Quote filter values with single quotes and join multiple conditions with AND. A time condition can be written as createdAfter > '2026-01-01'.

4.2. Explore resource categories

explore returns counts for matching resource categories, useful for type or tag filters in a tool selection page:

curl -sS -X POST "${ARD_BASE_URL}/v3/ai/ard/explore?namespaceId=public" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "resultType": {
      "facets": [
        {"field": "type", "limit": 10},
        {"field": "tags", "limit": 20}
      ]
    }
  }'

The response includes value and count in facets.type.buckets and facets.tags.buckets. Counts include only resources discoverable by the caller. Add query.filter as in a search request to narrow the scope.

5. Discover catalogs and retrieve artifacts

The host-level catalog provides the Registry entry:

curl -sS "${ARD_BASE_URL}/.well-known/ai-catalog.json" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

Its entries array contains an entry of type application/ai-registry+json. The metadata.searchEndpoint, metadata.exploreEndpoint, and metadata.listEndpoint fields provide the corresponding endpoint URLs. This catalog does not list every resource.

To retrieve a namespace’s resource catalog:

curl -sS "${ARD_BASE_URL}/v3/ai/ard/ai-catalog.json?namespaceId=public" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

The catalog’s entries contains the Registry entry and discoverable resources. Select a resource entry and use its url to download the artifact. Search results and list items also provide this URL.

export ARTIFACT_URL='<resource-url-from-response>'
curl -f -sS "${ARTIFACT_URL}" \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -o artifact.bin

Resource URLs point to /v3/ai/ard/artifacts on the adaptor. Parse the file according to the entry’s type and the response Content-Type: Skills return complete ZIP packages; other resources return JSON. Preserve the full URL, including its version and other parameters. Agent URLs also include the content digest and representation. If a version goes offline or the URL becomes invalid, search again for an available version.

6. Troubleshooting

ARD errors use {"errorCode":"...","message":"..."}, without the Nacos v3 API code and data wrapper.

See the ARD specification for protocol background. Nacos 3.3 uses upstream draft 5fa2f5a as its compatibility baseline; use the supported scope described on this page when integrating.