Dns Aid

DNS-AID

DNS-based Agent Identification and Discovery

Reference implementation for IETF draft-mozleywilliams-dnsop-dnsaid-02.

DNS-AID enables AI agents to discover each other via DNS, using the internet's existing naming infrastructure instead of centralized registries or hardcoded URLs.

Relationship to IETF

The DNS-AID specification is being developed within the IETF: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/.

This repository provides a reference implementation.

This project does not define the specification. The IETF draft is authoritative.

Scope of this Repository

This project focuses on implementation, tooling, and ecosystem activities.

Changes to protocol behavior should be discussed within the IETF.

New to DNS-AID? Start with the Getting Started Guide for install, first agent publication, and backend setup.

Documentation

• Getting Started Guide — install, first agent publication, backend setup
• API Reference — Python SDK, CLI, and MCP server tool reference
• ARD ai-catalog discovery — interop with Agentic Resource Discovery: catalog discovery, the host-anywhere DNS pointer, and card dereferencing
• Architecture — protocol layers, metadata resolution, integration points
• Integrations — backend-specific setup notes
• Demo Guide — end-to-end walkthrough for talks and presentations
• Roadmap — where the project is headed, near/medium/long term
• Privacy Policy | Security Policy | Trademarks

Ecosystem and Integrations

DNS-AID is a substrate. The library in this repository is sufficient on its own — it publishes and resolves agent records against any DNS provider, with no dependency on a particular directory, indexer, or telemetry backend.

When a search, indexing, or telemetry layer is useful, the SDK can point at any HTTP endpoint that implements the documented interfaces. Operators are encouraged to run their own — the indexer is a thin layer over the same DNS records this library publishes and discovers, and the SDK telemetry sink is configurable via DNS_AID_SDK_HTTP_PUSH_URL (off by default). Independent directory implementations exist across the ecosystem; DNS-AID is designed to remain interoperable with any of them rather than canonicalize a single one.

Quick Start

Install

# Install from PyPI

pip install "dns-aid[cli,mcp]"

Or install the latest unreleased main from GitHub

pip install "dns-aid[cli,mcp] @ git+https://github.com/dns-aid/dns-aid-core.git"

For backend-specific extras (route53, cloudflare, ns1, cloud_dns, infoblox, akamai-edgedns, ddns), see the Getting Started Guide.

Python Library

import dns_aid

Publish your agent to DNS

await dns_aid.publish( name="my-agent", domain="example.com", protocol="mcp", endpoint="agent.example.com", capabilities=["chat", "code-review"] )

Discover agents at a domain (Path A: DNS substrate)

agents = await dns_aid.discover("example.com") for agent in agents: print(f"{agent.name}: {agent.endpoint_url}")

Discover via HTTP index (richer metadata; format aligns with the ANS schema) —

also auto-detects and dereferences ARD ai-catalogs (see docs/ard-catalog.md)

agents = await dns_aid.discover("example.com", use_http_index=True)

(0.26.3+) A catalog on your own domain needs nothing. An off-domain catalog

pointer is trusted only via per-record JWS (verify_signatures=True) or, opt-in,

a DNSSEC-validated pointer (trust_dnssec_pointers=True) — otherwise it is ignored

and discovery falls back to the on-domain catalog. The trust basis is surfaced as

AgentRecord.catalog_trust (tls_domain | dnssec | jws). See docs/ard-catalog.md.

(0.26.4+) Opt-in DNSSEC/DANE hardening (SDK/CLI/MCP; all default off — DNSSEC is

never required). require_dnssec / min_dnssec enforce the resolver AD flag on

DNS-plane agents (ARD / HTTP-catalog agents are exempt — they carry no DNS SVCB

record). verify_dane binds each agent endpoint's TLS cert to its DANE/TLSA record

(defense-in-depth, meaningful only under DNSSEC) → AgentRecord.dane_verified.

(0.26.5+) trust_dnssec_pointers (above) is exposed the same way — CLI

--trust-dnssec-pointers / MCP — so all four opt-in trust controls have SDK/CLI/MCP parity.

Filtered discovery — pure-Python predicates over the in-memory result (v0.19.0+)

result = await dns_aid.discover( "example.com", capabilities=["payment-processing"], auth_type="oauth2", realm="prod", require_signed=True, require_signature_algorithm=["ES256", "Ed25519"], )

Verify an agent's DNS records

result = await dns_aid.verify("my-agent.example.com") print(f"Security Score: {result.security_score}/100")

Path B: cross-domain search via an external directory (v0.19.0+)

When the caller does not yet know which domain hosts the agent it wants, the SDK can query any directory backend that implements the search endpoint. The directory layer is opt-in convenience; the DNS substrate remains the authoritative trust gate.

from dns_aid.sdk import AgentClient, SDKConfig

Point at whichever directory the caller has chosen to trust.

Can also be set via DNS_AID_SDK_DIRECTORY_API_URL.

config = SDKConfig(directory_api_url="https://your-directory.example.com")

async with AgentClient(config=config) as client: response = await client.search(q="payment processing", protocol="mcp") for r in response.results: print(r.agent.fqdn)

After the directory returns candidates, re-resolve each one through Path A and validate signatures / DNSSEC before invoking. This is the substrate-as-authority pattern: the directory provides ranking and discovery convenience, but never sits in the trust path between the caller and the agent.

async with AgentClient(config=config) as client:

response = await client.search(q="fraud detection") for candidate in response.results: verified = await dns_aid.discover( candidate.agent.domain, name=candidate.agent.name, require_signed=True, )

Invoke only when DNS substrate confirms the directory's claim.

The SDK exposes additional filter parameters (capabilities, min_security_score, verified_only, etc.) for directories that compute and return those signals; see API Reference for the full surface. The semantics of those values are defined by whichever directory the caller has chosen — DNS-AID does not centralize them.

SDK: Invoke Agents & Capture Telemetry (v0.6.0+)

import dns_aid

Discover + invoke in one line — telemetry captured automatically

result = await dns_aid.discover("example.com", protocol="mcp") agent = result.agents[0]

resp = await dns_aid.invoke(agent, method="tools/list") print(f"Latency: {resp.signal.invocation_latency_ms}ms") print(f"Status: {resp.signal.status}") print(f"Tools: {resp.data}")

Rank multiple agents by your own local telemetry signals

ranked = await dns_aid.rank(result.agents, method="tools/list") for r in ranked: print(f"{r.agent_fqdn}: score={r.composite_score:.1f}")

OpenTelemetry (v0.23.0+): install dns-aid[otel] and set otel_enabled=True (or DNS_AID_SDK_OTEL_ENABLED=true) to emit spans + metrics per invoke and propagate W3C trace context to downstream agents. See docs/integrations/opentelemetry.md.

For advanced usage (connection reuse, OpenTelemetry export, pluggable telemetry sink):

from dns_aid.sdk import AgentClient, SDKConfig

config = SDKConfig( otel_enabled=True, # Export to any OpenTelemetry collector caller_id="my-app",

Optional: push telemetry to any HTTP endpoint the caller controls

http_push_url="https://your-telemetry.example.com/v1/signals",

)

async with AgentClient(config=config) as client: resp = await client.invoke(agent, method="tools/call", arguments={...}) fqdns = [a.fqdn for a in agents] ranked = client.rank(fqdns) # Rank by the caller's own observed telemetry

If an external aggregator publishes community-wide rankings over HTTP, the SDK can fetch them via client.fetch_rankings(...); the endpoint is configured by the caller, not by the library.

SDK: Per-Invoke Credential Provider Callback (v0.21.0+)

For short-lived credentials (RFC 8693 token exchange, AWS STS assume-role, HashiCorp Vault dynamic secrets, HSM/KMS-backed signing keys), pass an opt-in async credential_provider callback to invoke(). The SDK awaits the callback lazily at invoke time with the target AgentRecord and uses the returned dict for auth resolution. Strictly additive — every existing call site continues to work without source change.

async def token_exchange_provider(agent: AgentRecord) -> dict[str, str]:

Mint a fresh delegation token per call — e.g., RFC 8693 token exchange

against Keycloak / Okta / Auth0 / Microsoft Entra ID.

return {"token": await my_idp.exchange_token(subject_token, agent.fqdn)}

async with AgentClient(config=config) as client: resp = await client.invoke( agent, method="tools/list", credential_provider=token_exchange_provider, )

Precedence: auth_handler > credentials > credential_provider > no_auth. See docs/security-credentials.md for the per-handler security matrix, audit-trail flow, and the examples/integration_oauth2_token_exchange.py and examples/integration_aws_sts_assume_role.py canonical patterns.

CLI Usage

# Publish an agent to DNS

dns-aid publish \ --name my-agent \ --domain example.com \ --protocol mcp \ --endpoint agent.example.com \ --capability chat \ --capability code-review

Publish with transport and auth metadata (v0.10.0+)

dns-aid publish \ --name billing \ --domain example.com \ --protocol mcp \ --endpoint mcp.example.com \ --capability billing --capability invoicing \ --transport streamable-http \ --auth-type bearer

Publish with DNS-AID custom SVCB parameters (v0.4.8+)

dns-aid publish \ --name booking \ --domain example.com \ --protocol mcp \ --endpoint mcp.example.com \ --capability travel --capability booking \ --cap-uri https://mcp.example.com/.well-known/agent-cap.json \ --cap-sha256 dGVzdGhhc2g \ --bap "mcp/1,a2a/1" \