From 015fdae09992ad22b3b35fd2d613da4641a8c08e Mon Sep 17 00:00:00 2001 From: kperry Date: Thu, 23 Jul 2026 21:00:53 +0200 Subject: [PATCH 1/2] docs: add ANS Finder to reference implementations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the open-source Agent Name Service (ANS) Finder — the ARD discovery service over the ANS reference implementation (registration authority, transparency log, offline verifier in Go). Serves POST /v1/search and /v1/explore per ARDS v0.9 and validates against the ard-spec conformance suite in registry mode. Unlike the existing entries it is self-hosted rather than a public endpoint, so the entry gives a run-it-locally quickstart: demo stack, search, SCITT receipt verification against the transparency log, and the conformance check. Co-Authored-By: Claude Fable 5 Signed-off-by: kperry --- docs/ref_implementations.md | 43 +++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) 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 +``` From f610531f1b765d28d69e9619994537356268f70e Mon Sep 17 00:00:00 2001 From: kperry Date: Thu, 23 Jul 2026 21:18:58 +0200 Subject: [PATCH 2/2] docs: name ANS Finder among introduction's example discovery services Co-Authored-By: Claude Fable 5 Signed-off-by: kperry --- docs/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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)**.