diff --git a/docs/introduction.md b/docs/introduction.md index af56af7..63aee5f 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -12,6 +12,6 @@ This is the problem the **Agentic Resource Discovery Specification (ARD)** solve ARD only handles discovery. The client invokes the agentic resource it selects through that agentic resource's own mechanism — MCP, an API, an agent framework, a workflow system, or something else. ARD sits *before* invocation; it helps the client decide which capability to use. *What* to search over, *when* to search, and *what to do* with the results returned are all choices left to the designer of the system. -ARD is not a product. Any number of [discovery services](glossary.md#discovery-service) can implement it — **GitHub's [Agent Finder](https://github.com/agentfinder)** and **Hugging Face's [Discover](https://github.com/huggingface/hf-discover)** are two such services. The point is that an agentic resource published once should be discoverable by many clients, and a client should be able to find useful agentic resources well beyond the small set it already knows about. +ARD is not a product. Any number of [discovery services](glossary.md#discovery-service) can implement it — **GitHub's [Agent Finder](https://github.com/agentfinder)**, **Hugging Face's [Discover](https://github.com/huggingface/hf-discover)**, and the self-hostable **[ANS Finder](https://github.com/agentnameservice/ans)** are three such services. The point is that an agentic resource published once should be discoverable by many clients, and a client should be able to find useful agentic resources well beyond the small set it already knows about. To see how that works in practice, read **[How ARD works](how_ard_works.md)**. diff --git a/docs/ref_implementations.md b/docs/ref_implementations.md index 546813a..37f5514 100644 --- a/docs/ref_implementations.md +++ b/docs/ref_implementations.md @@ -106,3 +106,46 @@ curl -sS https://ora.ai/api/ard/attestation/resend.com \ ### MCP Ora is also reachable as an MCP server at `https://ora.ai/api/mcp` (streamable HTTP); its `discover_products`, `get_score`, and `search_capabilities` tools query the same index. + +## ANS Finder + +The [ANS Finder](https://github.com/agentnameservice/ans) is the discovery service of the open-source **Agent Name Service (ANS)** reference implementation — a registration authority, transparency log, and offline verifier in Go, based on the ANS IETF draft. The Finder tails the registry's lifecycle event feed, projects every ANS-registered agent into a search index, and serves the ARD Registry REST interface: `POST /v1/search` and `POST /v1/explore` (ARDS v0.9). What sets it apart is verifiable registration: every catalog entry's `trustManifest.attestations[]` carries an `ANS-Registration` attestation whose URI resolves to a SCITT COSE receipt on the ANS Transparency Log, so a client can cryptographically verify an agent's registration — independently of the Finder — before invoking it. It validates against this project's [conformance suite](https://github.com/ards-project/ard-spec/tree/main/conformance) (registry mode). + +ANS Finder is self-hosted: run the stack locally (or deploy your own) rather than querying a public endpoint. + +### Run the demo stack + +```bash +git clone https://github.com/agentnameservice/ans && cd ans +scripts/demo/start.sh # builds + starts the registry :18080, transparency log :18081, finder :18082 +scripts/demo/register.sh --v2 translator.example.com # register an MCP agent and drive it to ACTIVE +``` + +The Finder polls the registry's event feed (every 2s in the demo) and indexes the agent; a Swagger UI serves the Finder's ARD contract at `http://localhost:18082/docs`. + +### Search + +```bash +curl -sS -X POST http://localhost:18082/v1/search \ + -H 'content-type: application/json' \ + -d '{"query":{"text":"translator"},"pageSize":5}' \ + | jq '.results[] | {identifier, displayName, url, score}' +``` + +### Verify an entry against the Transparency Log + +Each result's `trustManifest.attestations[]` carries the SCITT receipt URI on the Transparency Log: + +```bash +curl -sS -X POST http://localhost:18082/v1/search \ + -H 'content-type: application/json' \ + -d '{"query":{"text":"translator"},"pageSize":1}' \ + | jq -r '.results[0].trustManifest.attestations[0].uri' +``` + +### Check conformance + +```bash +git clone https://github.com/ards-project/ard-spec +ard-spec/conformance/bin/conformance-test registry http://localhost:18082/v1 +```