### Install Agent Finder Skill (Marketplace)

Source: https://agenticresourcediscovery.org/connect/claude

Use these two commands to add the connectors repository as a plugin and then install the agentfinder skill.

```bash
/plugin marketplace add ards-project/connectors
/plugin install agentfinder@ard-connectors

```

--------------------------------

### Install Hugging Face CLI

Source: https://agenticresourcediscovery.org/ref_implementations

Installs the Hugging Face CLI tool. This is a prerequisite for using the `hf discover` commands.

```bash
# Install the Hugging Face CLI tool:
uv tool install huggingface_hub
```

--------------------------------

### Install Agent Finder Skill (Manual)

Source: https://agenticresourcediscovery.org/connect/claude

Manually copy the agentfinder skill folder into your Claude skills directory.

```bash
cp -r connectors/skills/agentfinder ~/.claude/skills/

```

--------------------------------

### Example Baseline AI Catalog Entry

Source: https://agenticresourcediscovery.org/ai_catalog_spec

A baseline ai-catalog.json manifest includes specVersion, host information, entries for agentic resources, and links to collections. This example shows a single OCR Text Extractor entry.

```json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Systems",
    "identifier": "acme.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:acme.com:tool:ocr",
      "displayName": "OCR Text Extractor",
      "type": "application/mcp-server+json",
      "url": "https://tools.acme.com/ocr/mcp.json",
      "description": "Extracts plain text and structured tables from scanned PDFs and PNGs."
    }
  ]
}

```

--------------------------------

### Federation Response Example (Referrals Mode)

Source: https://agenticresourcediscovery.org/spec

This JSON snippet shows a typical response from the Registry API when using 'referrals' mode. It includes local results and a list of 'referrals' to other registries that the client can query.

```json
{
  "results": [
    {
      "identifier": "urn:ai:acme.com:agent:expense",
      "displayName": "Corporate Expenses",
      "type": "application/a2a-agent-card+json",
      "url": "https://internal.corp/agents/expense.json",
      "score": 97,
      "source": "https://finder.internal.corp"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:ai:blweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry",
      "url": "https://finder.nlweb.ai/search"
    },
    {
      "identifier": "urn:ai:example.com:registry:travel",
      "displayName": "Travel Agent Finder",
      "type": "application/ai-registry",
      "url": "https://travel.finder.example/search"
    }
  ]
}

```

--------------------------------

### Federation Request Example (Referrals Mode)

Source: https://agenticresourcediscovery.org/spec

This JSON snippet demonstrates a request to the Registry API with the federation set to 'referrals'. This mode instructs the Registry to return its own results along with catalog entries for other Registries.

```json
{
  "query": {
    "text": "find me a flight booking agent"
  },
  "federation": "referrals"
}

```

--------------------------------

### List (GET /agents)

Source: https://agenticresourcediscovery.org/spec

Deterministic browsing, designed for developer portals. Highly cacheable, relies on strict database filtering, and does not support relevance-based sorting.

```APIDOC
## GET /agents

### Description
Deterministic browsing, designed for developer portals. Highly cacheable, relies on strict database filtering, and does not support relevance-based sorting.

### Method
GET

### Endpoint
/agents

### Parameters
#### Query Parameters
- **filter** (String) - EBNF filter expression.
- **orderBy** (String) - Sorting fields (e.g., name, created_at DESC).
- **pageSize** (Integer) - Max results (default: 20, max: 100).
- **pageToken** (String) - Pagination token.
```

--------------------------------

### Example `ai-catalog.json` Manifest

Source: https://agenticresourcediscovery.org/how_to_publish

This JSON manifest lists agentic resources, including their identifiers, display names, types, URLs, capabilities, and descriptions. It is used to make resources discoverable by ARD services.

```json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Dev Tools",
    "identifier": "did:web:acme.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:acme.com:server:weather",
      "displayName": "Acme Weather Telemetry Server",
      "type": "application/mcp-server+json",
      "url": "https://api.acme.com/mcp/weather.json",
      "capabilities": ["WeatherTool", "ForecastTool"],
      "description": "An enterprise weather MCP server providing live telemetry.",
      "representativeQueries": [
        "what is the current wind speed in Chicago",
        "get the 5-day forecast for Seattle"
      ]
    }
  ]
}
```

--------------------------------

### AI Catalog Manifest Example

Source: https://agenticresourcediscovery.org/spec

This JSON object represents a capability manifest file. It lists various AI agents and services, including their identifiers, display names, types, URLs, descriptions, and in some cases, representative queries, capabilities, nested data, or trust information. This structure is used to advertise discoverable AI artifacts.

```json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Enterprise AI",
    "identifier": "did:web:acme.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:acme.com:agent:assistant",
      "displayName": "Corporate Assistant (A2A)",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme.com/agents/assistant.json",
      "description": "General-purpose corporate A2A assistant.",
      "representativeQueries": [
        "help me draft an email to the security working group",
        "summarize my unread messages from Todd"
      ]
    },
    {
      "identifier": "urn:ai:acme.com:server:weather",
      "displayName": "Weather Data Node",
      "type": "application/mcp-server+json",
      "url": "https://api.acme.com/mcp/weather.json",
      "capabilities": ["WeatherTool", "ForecastTool"],
      "description": "Enterprise weather MCP server for live telemetry.",
      "representativeQueries": [
        "what is the current wind speed in Chicago",
        "get the 5-day forecast for Seattle"
      ]
    },
    {
      "identifier": "urn:ai:acme.com:plugin:finance-suite",
      "displayName": "Finance Tool Bundle",
      "type": "application/ai-catalog+json",
      "description": "A static nested bundle containing an A2A agent and its required market dataset.",
      "tags": ["finance", "bundle"],
      "data": {
        "specVersion": "1.0",
        "entries": [
          {
            "identifier": "urn:ai:acme.com:finance:a2a",
            "displayName": "Finance Trading Agent",
            "type": "application/a2a-agent-card+json",
            "url": "https://api.acme.com/agents/finance-trader.json"
          },
          {
            "identifier": "urn:ai:acme.com:market:2026",
            "displayName": "Market Dataset 2026",
            "type": "application/parquet",
            "url": "https://data.acme.com/market-2026.parquet"
          }
        ]
      }
    },
    {
      "identifier": "urn:ai:acme.com:registry:global",
      "displayName": "Acme Global Agent Registry",
      "type": "application/ai-registry+json",
      "url": "https://registry.acme.com/api/v1/",
      "description": "Dynamic REST API search interface to discover all approved enterprise agents.",
      "tags": ["registry", "search", "dynamic"],
      "trustManifest": {
        "identity": "spiffe://acme.com/registry/global",
        "identityType": "spiffe",
        "attestations": [
          {
            "type": "SPIFFE-X509",
            "uri": "https://acme.com/.well-known/spiffe/jwks"
          },
          {
            "type": "SOC2-Type2",
            "uri": "https://trust.acme.com/reports/soc2.pdf"
          }
        ]
      }
    },
    {
      "identifier": "urn:ai:acme.com:catalog:engineering",
      "displayName": "Engineering Department Catalogs",
      "type": "application/ai-catalog+json",
      "url": "https://acme.com/catalogs/engineering.json",
      "description": "Sub-catalogs containing CI/CD and internal deployment agents."
    }
  ]
}
```

--------------------------------

### Validate Local AI Catalog Manifest with AJV CLI

Source: https://agenticresourcediscovery.org/spec

Use the AJV CLI to validate a local AI catalog JSON file against its schema. Ensure AJV CLI is installed.

```bash
npx ajv-cli validate -s spec/schemas/ai-catalog.schema.json -d path/to/ai-catalog.json

```

--------------------------------

### Run One-Click Conformance Demo

Source: https://agenticresourcediscovery.org/spec

Execute the automated demo script for a complete end-to-end conformance verification. This includes manifest validation, mock registry testing, and cleanup.

```bash
./conformance/bin/run-conformance-demo

```

--------------------------------

### Search Hugging Face Resources via CLI

Source: https://agenticresourcediscovery.org/ref_implementations

Searches for resources on Hugging Face using the CLI. Use specific keywords to find relevant models or applications.

```bash
# Search for resources to train a model
hf discover search "Fine tune a language model"
```

--------------------------------

### Search Discovery Service

Source: https://agenticresourcediscovery.org/how_to_build_a_client

This snippet shows how to send a search query to the discovery service and format the output using `jq`.

```shell
curl -s https://your-discovery-service/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"summarize a PDF"},"pageSize":3}' \
  | jq '.results[] | {displayName, type, url, score}'

```

--------------------------------

### Standard Manifest Hosting Path

Source: https://agenticresourcediscovery.org/how_to_publish

Host your `ai-catalog.json` manifest at this standard path on your domain. Ensure HTTPS, correct Content-Type, and CORS headers are configured.

```http
https://<your-domain>/.well-known/ai-catalog.json
```

--------------------------------

### Explore (POST /explore)

Source: https://agenticresourcediscovery.org/spec

Accepts a query and returns an aggregation over the matched set rather than ranked entries. This allows clients to introspect a registry and obtain facet breakdowns.

```APIDOC
## POST /explore

### Description
Accepts a `query` and returns an aggregation over the matched set rather than ranked entries. Explore lets clients introspect a registry — for example, "which media types are available?" — and obtain facet breakdowns narrowed by the same `text` and `filter` as Search. For Explore, `text` and `filter` are both optional; when both are absent, the aggregation covers the entire registry.

### Method
POST

### Endpoint
/explore

### Parameters
#### Request Body
- **query** (Object) - Required. The query object, including optional `text` and `filter` fields.
- **resultType** (Object) - Required. The shape of result to compute. The only defined shape is facets.
  - **facets** (Array) - Required. Each element of `resultType.facets` defines a field to aggregate.
    - **field** (String) - Required. Field path to aggregate.
    - **limit** (Integer) - Optional. Maximum number of buckets returned. Default: 20.
    - **minCount** (Integer) - Optional. Suppress buckets with counts below this threshold.

### Request Example
```json
{
  "query": {
    "text": "currency conversion",
    "filter": {
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  },
  "resultType": {
    "facets": [
      { "field": "type" },
      { "field": "publisher", "limit": 50 }
    ]
  }
}
```

### Response
#### Success Response (200)
- **resultType** (String) - The type of result, e.g., "facets".
- **facets** (Object) - An object containing the aggregated facets.
  - **buckets** (Array) - An array of buckets, each with a `value` and `count`.
  - **otherCount** (Integer) - The number of matching entries in buckets beyond `limit`.

#### Response Example
```json
{
  "resultType": "facets",
  "facets": {
    "type": {
      "buckets": [
        { "value": "application/mcp-server+json", "count": 1247 },
        { "value": "application/a2a-agent-card+json", "count": 389 }
      ],
      "otherCount": 23
    },
    "publisher": {
      "buckets": [
        { "value": "acme.com", "count": 412 }
      ]
    }
  }
}
```
```

--------------------------------

### Navigate Federated Catalog via CLI

Source: https://agenticresourcediscovery.org/ref_implementations

Navigates a federated ARD catalog from a given website URL using the Hugging Face CLI. Useful for exploring distributed resource discovery.

```bash
# Navigate a federated catalog from a website
hf discover navigate <web-url> "Research biomedical datasets"
```

--------------------------------

### Copy GitHub Copilot Skill Folder

Source: https://agenticresourcediscovery.org/connect/github-copilot

Copy the GitHub Copilot skill into the appropriate directory for Copilot to scan. This makes the skill available for use.

```bash
cp -r connectors/skills/github-copilot ~/.copilot/skills/
```

--------------------------------

### Validate Local AI Catalog Manifest with Conformance Tool

Source: https://agenticresourcediscovery.org/spec

Use the official conformance testing tool to validate a local AI catalog manifest file. This tool performs schema and custom semantic checks.

```bash
./conformance/bin/conformance-test manifest path/to/ai-catalog.json

```

--------------------------------

### Send Search Query to Discovery Service

Source: https://agenticresourcediscovery.org/how_to_build_a_client

Send the user's intent to a discovery service's POST /search endpoint. Use 'query.text' for the natural-language need and 'query.filter' for structured fields. 'federation' and 'pageSize' are root-level parameters.

```shell
POST https://your-discovery-service/search

{
  "query": {
    "text": "book me a flight to Tokyo",
    "filter": { "type": ["application/mcp-server+json"] }
  },
  "federation": "referrals",
  "pageSize": 3
}


```

--------------------------------

### Explore Response Schema

Source: https://agenticresourcediscovery.org/spec

Illustrates the structure of an Explore response, detailing the aggregated facets, their buckets with values and counts, and other counts for buckets beyond the specified limit.

```json
{
  "resultType": "facets",
  "facets": {
    "type": {
      "buckets": [
        { "value": "application/mcp-server+json", "count": 1247 },
        { "value": "application/a2a-agent-card+json", "count": 389 }
      ],
      "otherCount": 23
    },
    "publisher": {
      "buckets": [
        { "value": "acme.com", "count": 412 }
      ]
    }
  }
}

```

--------------------------------

### Find MCP Servers via CLI

Source: https://agenticresourcediscovery.org/ref_implementations

Searches for MCP Servers on Hugging Face using the CLI, filtering by kind. Outputs results in JSON format.

```bash
# Find MCP Servers to generate an image
hf discover search "Generate an image" --json --kind mcp
```

--------------------------------

### DNS TXT Record for Manifest URL

Source: https://agenticresourcediscovery.org/how_to_publish

Publish a DNS TXT record to point to your raw JSON manifest location if the standard path is not usable. This is an alternative for hosting the manifest.

```dns
Name / Host | Type | Value  
---|---|---  
`_catalog._agents.yourdomain.com` | `TXT` | `"url=https://custom-bucket.s3.amazonaws.com/ai-catalog.json"`
```

--------------------------------

### Configure Remote MCP Connector for Older Claude Desktop

Source: https://agenticresourcediscovery.org/connect/claude

For older versions of Claude Desktop that do not natively support remote connectors, configure 'mcp-remote' in your 'claude_desktop_config.json' file to bridge the connection.

```json
{
  "mcpServers": {
    "agent-finder": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://agentfinder.github.com/api/v1/mcp"]
    }
  }
}

```

--------------------------------

### Pull Cisco AI Catalog Manifest

Source: https://agenticresourcediscovery.org/ref_implementations

Fetches the Cisco AI Catalog manifest and extracts specific metadata like version and display name. Uses `curl` and `jq`.

```bash
curl -sS https://ai-catalog.outshift.io/.well-known/ai-catalog.json | jq '.specVersion, .host.displayName'
```

--------------------------------

### Search Other Registries via CLI

Source: https://agenticresourcediscovery.org/ref_implementations

Searches for resources in other ARD-compliant registries using the Hugging Face CLI. Requires specifying the registry URL.

```bash
# Search other registries
hf discover search "Purchase aeroplane tickets" --registry-url <catalog-url>
```

--------------------------------

### Validate Remote AI Catalog Manifest with Conformance Tool

Source: https://agenticresourcediscovery.org/spec

Use the official conformance testing tool to validate a remote AI catalog manifest accessible via a URL. This ensures the manifest adheres to the defined schema.

```bash
./conformance/bin/conformance-test manifest https://example.com/.well-known/ai-catalog.json

```

--------------------------------

### Search Cisco AI Catalog for MCP Cards and Trust Details

Source: https://agenticresourcediscovery.org/ref_implementations

Searches the Cisco AI Catalog for MCP server cards and extracts trust manifest details along with display name and card URL. Outputs results as JSON.

```bash
curl -sS 'https://ai-catalog.outshift.io/v1/agents?filter=type%3Dapplication%2Fmcp-server-card%2Bjson' \
    | jq -r '.results[] | {displayName, identity: .trustManifest.identity, identityType: .trustManifest.identityType, cardUrl: .data.card_data.url} | @json'
```

--------------------------------

### Configure Remote MCP Connector in VS Code

Source: https://agenticresourcediscovery.org/connect/github-copilot

Add the Agent Finder server configuration to your VS Code workspace's `.vscode/mcp.json` file. This specifies the default endpoint for agent discovery.

```json
{
  "servers": {
    "agent-finder": {
      "type": "http",
      "url": "https://agentfinder.github.com/api/v1/mcp"
    }
  }
}
```

--------------------------------

### GitHub Hosted Skill Manifest

Source: https://agenticresourcediscovery.org/spec

Manifest for a skill hosted on GitHub, specifying its identifier, display name, type, URL, and a brief description.

```json
{
  "specVersion": "1.0",
  "host": { "displayName": "Alice's AI Tools" },
  "entries": [
    {
      "identifier": "urn:ai:github.com:alice-dev:pptx-creator",
      "displayName": "pptx-creator",
      "type": "application/ai-skill",
      "url": "https://github.com/alice-dev/pptx-creator",
      "description": "Create professional PowerPoint presentations following brand guidelines."
    }
  ]
}
```

--------------------------------

### Discovery via GitHub Pages Manifest

Source: https://agenticresourcediscovery.org/spec

Manifest combining agents from Hugging Face Spaces and GitHub, discoverable via GitHub Pages. It includes URLs for each entry.

```json
{
  "specVersion": "1.0",
  "host": { "displayName": "Alice's AI Tools" },
  "entries": [
    {
      "identifier": "urn:ai:hf.co:alice-dev:weather-agent",
      "displayName": "Weather Agent",
      "type": "application/mcp-server+json",
      "url": "https://alice-dev.github.io/weather-agent/entry.json"
    },
    {
      "identifier": "urn:ai:github.com:alice-dev:pptx-creator",
      "displayName": "pptx-creator",
      "type": "application/ai-skill+md",
      "url": "https://github.com/alice-dev/pptx-creator"
    }
  ]
}
```

--------------------------------

### Hugging Face Spaces Agent Manifest

Source: https://agenticresourcediscovery.org/spec

Manifest for an agent hosted on Hugging Face Spaces, defining its identifier, display name, type, and inline details including tools and input schemas.

```json
{
  "specVersion": "1.0",
  "host": { "displayName": "Alice's AI Tools" },
  "entries": [
    {
      "identifier": "urn:ai:hf.co:alice-dev:weather-agent",
      "displayName": "Weather Agent",
      "type": "application/mcp-server+json",
      "inline": {
        "name": "Weather Agent",
        "description": "Simple weather lookup using open data",
        "tools": [
          {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "inputSchema": {
              "type": "object",
              "properties": { "city": { "type": "string" } },
              "required": ["city"]
            }
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### Search

Source: https://agenticresourcediscovery.org/spec

Accepts a query and returns catalog entries ranked by relevance. For Search, 'text' is required; 'filter' is optional.

```APIDOC
## POST /search

### Description
Accepts a `query` and returns catalog entries ranked by relevance. For Search, `text` is required; `filter` is optional.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **federation** (String) - Optional - auto (default), referrals, or none.
- **pageSize** (Integer) - Optional - Max results to return per page (default: 10, max: 100).
- **pageToken** (String) - Optional - Pagination token to retrieve the next page.

#### Request Body
- **query** (Object) - Required - The search query object.
  - **text** (String) - Required - The natural language search query.
  - **filter** (Object) - Optional - Filters to apply to the search.
    - **type** (Array[String]) - Optional - Array of MIME types to filter by.

### Request Example
```json
{
  "query": {
    "text": "find me a flight booking agent",
    "filter": {
      "type": ["application/a2a-agent-card+json"]
    }
  },
  "federation": "referrals",
  "pageSize": 5
}
```

### Response
#### Success Response (200)
- **results** (Array[Object]) - Catalog entries ranked by relevance.
  - **identifier** (String) - Unique identifier for the entry.
  - **displayName** (String) - Display name of the entry.
  - **type** (String) - MIME type of the entry.
  - **url** (String) - URL to access the entry.
  - **score** (Integer) - Semantic relevance score (0-100).
  - **source** (String) - Source of the entry.
  - **capabilities** (Array[String]) - Optional - Capabilities of the entry.
- **referrals** (Array[Object]) - Optional - Referrals to other registries.
  - **identifier** (String) - Unique identifier for the referral.
  - **displayName** (String) - Display name of the referral.
  - **type** (String) - MIME type of the referral.
  - **url** (String) - URL for the referral.
- **pageToken** (String) - Pagination token for the next page.

#### Response Example
```json
{
  "results": [
    {
      "identifier": "urn:ai:acme.com:agent:assistant",
      "displayName": "Corporate Assistant (A2A)",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme.com/agents/assistant.json",
      "score": 95,
      "source": "https://registry.acme.com/api/v1/"
    },
    {
      "identifier": "urn:ai:example.com:weather-server",
      "displayName": "Global Weather Service",
      "type": "application/mcp-server+json",
      "url": "https://weather.example.com/mcp",
      "capabilities": ["WeatherTool"],
      "score": 88,
      "source": "https://finder.external.org/api/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:ai:nlweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry",
      "url": "https://finder.nlweb.ai/search"
    }
  ],
  "pageToken": "eyJwYWdlIjogMn0="
}
```
```

--------------------------------

### Configure Gemini CLI MCP Server

Source: https://agenticresourcediscovery.org/connect/gemini

Add a remote MCP server configuration to your Gemini CLI settings.json file. This allows the CLI to connect to external services for agent discovery.

```json
{
  "mcpServers": {
    "agent-finder": {
      "httpUrl": "https://agentfinder.github.com/api/v1/mcp"
    }
  }
}

```

--------------------------------

### DNS SRV Record for Dynamic Discovery

Source: https://agenticresourcediscovery.org/how_to_publish

Publish a DNS SRV record for dynamic discovery services (e.g., `POST /search`). This directs services to the correct target and port for searching agentic resources.

```dns
Name / Service | Type | Port | Target  
---|---|---|---  
`_search._agents.yourdomain.com` | `SRV` | `443` | `search.yourdomain.com`
```

--------------------------------

### Search Discovery Service

Source: https://agenticresourcediscovery.org/how_to_build_a_client

Sends a user's intent to the discovery service to find relevant resources. It supports natural language queries and structured filtering.

```APIDOC
## POST /search

### Description
Sends a user's intent to the discovery service to find relevant resources. It supports natural language queries and structured filtering.

### Method
POST

### Endpoint
https://your-discovery-service/search

### Parameters
#### Query Parameters
- **query.text** (string) - Required - The task in plain language.
- **query.filter** (object) - Optional - Structured constraints (e.g., `type`, `tags`, `capabilities`, `publisher`, `trustManifest.*`). Within a key, values are OR'd; across keys, AND'd.
- **federation** (string) - Optional - Controls how results are merged. Can be `auto` (merges upstream results), `referrals` (returns other services to query), or `none`.
- **pageSize** (integer) - Optional - Paging control. Defaults to 10, with a maximum of 100.

### Request Example
```json
{
  "query": {
    "text": "book me a flight to Tokyo",
    "filter": { "type": ["application/mcp-server+json"] }
  },
  "federation": "referrals",
  "pageSize": 3
}
```

### Response
#### Success Response (200)
- **results** (array) - Ranked catalog entries, each containing schema and endpoint information.
- **referrals** (array) - Optional list of other services to query.

#### Response Example
```json
{
  "results": [
    {
      "identifier": "urn:ai:acme.com:travel:concierge",
      "displayName": "Travel Concierge",
      "type": "application/mcp-server+json",
      "url": "https://api.acme.com/mcp/travel.json",
      "score": 95,
      "source": "https://registry.acme.com/api/v1/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:ai:example.org:registry",
      "type": "application/ai-registry",
      "url": "https://finder.example.org/search"
    }
  ]
}
```
```

--------------------------------

### Validate Agent Registry REST API with Conformance Tool

Source: https://agenticresourcediscovery.org/spec

Use the official conformance testing tool to validate a running Agent Registry REST API. This checks endpoints, status codes, and response structures.

```bash
./conformance/bin/conformance-test registry http://localhost:9010/api

```

--------------------------------

### Explore Request Schema

Source: https://agenticresourcediscovery.org/spec

Defines the structure for an Explore request, including query parameters for text and filters, and result type specifications for facets.

```json
{
  "query": {
    "text": "currency conversion",
    "filter": {
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  },
  "resultType": {
    "facets": [
      { "field": "type" },
      { "field": "publisher", "limit": 50 }
    ]
  }
}

```

--------------------------------

### Search API Response Schema

Source: https://agenticresourcediscovery.org/spec

Illustrates the structure of a search response, containing ranked catalog entries with relevance scores, potential referrals, and pagination tokens.

```json
{
  "results": [
    {
      "identifier": "urn:ai:acme.com:agent:assistant",
      "displayName": "Corporate Assistant (A2A)",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme.com/agents/assistant.json",
      "score": 95,
      "source": "https://registry.acme.com/api/v1/"
    },
    {
      "identifier": "urn:ai:example.com:weather-server",
      "displayName": "Global Weather Service",
      "type": "application/mcp-server+json",
      "url": "https://weather.example.com/mcp",
      "capabilities": ["WeatherTool"],
      "score": 88,
      "source": "https://finder.external.org/api/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:ai:nlweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry",
      "url": "https://finder.nlweb.ai/search"
    }
  ],
  "pageToken": "eyJwYWdlIjogMn0="
}
```

--------------------------------

### Search and Explore Query Model

Source: https://agenticresourcediscovery.org/spec

The ARD API provides `POST /search` and `POST /explore` endpoints that accept a common query object. This object includes a `text` field for natural language descriptions and a `filter` object for structured constraints. The `filter` allows for precise targeting of catalog entries based on various fields, including nested and custom attributes.

```APIDOC
## Query Model

The `POST /search` and `POST /explore` endpoints accept a common `query` object with two members, `text` and `filter`.

```json
{
  "query": {
    "text": "find me a flight booking agent",
    "filter": {
      "type": ["application/a2a-agent-card+json"],
      "tags": ["finance"],
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  }
}
```

### Query Object Fields

- **text** (String): Natural-language description of the need. Narrows the result set by semantic relevance.
- **filter** (Object): Structured constraints. Keys are field paths into the catalog entry; values are arrays (a bare scalar is accepted as a single-element array).

**Filter Semantics**: Field paths are dot-separated to address nested fields (e.g. `trustManifest.attestations.type`). When the value at a path is an array, a constraint matches if any element satisfies it. Within a single key, values are combined with OR; across keys, with AND.

**Extensibility**: Any attribute present in a catalog entry MAY be used as a filter key — standard fields (type, tags, capabilities, publisher, version, …), nested fields under `trustManifest` or `host`, custom `metadata.*` fields, and `Schema.org`-vocabulary fields. New attributes become filterable without changes to this specification.

The `publisher` key is derived from the `<publisher>` segment of an entry's URN identifier, not a stored field; registries extract it from the identifier.

**Registry Support**: Registries SHOULD support filtering on common standard fields; support for `metadata.*` and other extension fields is registry-defined. A registry MAY reject a filter that references an unsupported field path with a 400 error.
```

--------------------------------

### Enterprise Agent Manifest with Trust Manifest

Source: https://agenticresourcediscovery.org/spec

Enterprise manifest using trustManifest for compliance, including identity, attestations for SPIFFE-X509, SOC2-Type2, and GDPR.

```json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Enterprise AI",
    "identifier": "did:web:acme.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:acme.com:travel:concierge",
      "displayName": "Travel Concierge",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme.com/travel/concierge.json",
      "description": "AI-powered travel planning",
      "trustManifest": {
        "identity": "spiffe://acme.com/travel/concierge",
        "identityType": "spiffe",
        "attestations": [
          {
            "type": "SPIFFE-X509",
            "uri": "https://acme.com/.well-known/spiffe/jwks"
          },
          {
            "type": "SOC2-Type2",
            "uri": "https://trust.acme.com/reports/soc2.pdf"
          },
          {
            "type": "GDPR",
            "uri": "https://trust.acme.com/compliance/gdpr"
          }
        ]
      }
    }
  ]
}
```