DNS-AID核心

Install all workspace packages (requires uv)

uv sync

Install

```bash

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/infobloxopen/dns-aid-core.git" ```

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

Route 53 Setup

1. Configure AWS credentials:

   export AWS_ACCESS_KEY_ID="your-access-key"
   export AWS_SECRET_ACCESS_KEY="your-secret-key"
   export AWS_DEFAULT_REGION="us-east-1"  # Optional
   

Or use AWS CLI profiles:

   aws configure
   # Or use a named profile
   export AWS_PROFILE="my-profile"
   

2. Verify zone access:

   dns-aid zones
   

3. Publish your agent:

   dns-aid publish -n my-agent -d myzone.com -p mcp -e mcp.myzone.com
   

Infoblox UDDI Setup

Infoblox UDDI (Universal DDI) is Infoblox's cloud-native DDI platform. DNS-AID supports creating SVCB and TXT records via the Infoblox API.

Environment Variables

Step-by-Step Setup

1. Get your API key from Infoblox Cloud Portal: - Navigate to Administration → API Keys - Create a new API key with DNS permissions - Copy the key (shown only once)

2. Configure environment variables:

   export INFOBLOX_API_KEY="your-api-key"
   export INFOBLOX_DNS_VIEW="default"  # Or your specific view name
   

3. Identify your zone and view: - In Infoblox Portal, go to DNS → Authoritative Zones - Note the zone name (e.g., example.com) and which view it belongs to

4. Use in Python:

   from dns_aid.backends.infoblox import InfobloxBloxOneBackend
   from dns_aid.core.publisher import set_default_backend
   from dns_aid import publish

   # Initialize backend (reads from environment variables)
   backend = InfobloxBloxOneBackend()

   # Or with explicit configuration
   backend = InfobloxBloxOneBackend(
       api_key="your-api-key",
       dns_view="default",  # Your DNS view name
   )

   set_default_backend(backend)

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

Infoblox UDDI Limitations & DNS-AID Compliance

⚠️ Important: Infoblox UDDI SVCB records only support "alias mode" (priority 0) and do not support SVC parameters (alpn, port, mandatory). This means Infoblox UDDI is not fully compliant with the DNS-AID draft. The draft requires ServiceMode SVCB records (priority > 0) with mandatory alpn and port parameters. Infoblox UDDI's limitation is a platform constraint, not a DNS-AID limitation.

For full DNS-AID compliance, use Route 53 or another RFC 9460-compliant DNS provider.

DNS-AID stores alpn and port in TXT records as a fallback for Infoblox UDDI, but this is a workaround and not standard-compliant for agent discovery.

Verify Records via API

Since Infoblox UDDI zones may not be publicly resolvable, verify records via the API:

async with InfobloxBloxOneBackend() as backend:
    async for record in backend.list_records("example.com", name_pattern="my-agent"):
        print(f"{record['type']}: {record['fqdn']}")

DDNS Setup (RFC 2136)

DDNS (Dynamic DNS) is a universal backend that works with any DNS server supporting RFC 2136, including BIND9, Windows DNS, PowerDNS, and Knot DNS. This is ideal for on-premise DNS infrastructure without vendor-specific APIs.

Environment Variables

Step-by-Step Setup

1. Create a TSIG key on your DNS server (BIND example):

   tsig-keygen -a hmac-sha256 dns-aid-key > /etc/bind/dns-aid-key.conf
   

2. Configure your zone to allow updates with the key:

   zone "example.com" {
       type master;
       file "/var/lib/bind/example.com.zone";
       allow-update { key "dns-aid-key"; };
   };
   

3. Configure DNS-AID:

   export DDNS_SERVER="ns1.example.com"
   export DDNS_KEY_NAME="dns-aid-key"
   export DDNS_KEY_SECRET="your-base64-secret"
   

4. Use in Python:

   from dns_aid.backends.ddns import DDNSBackend
   from dns_aid import publish

   backend = DDNSBackend()
   # Or with explicit configuration
   backend = DDNSBackend(
       server="ns1.example.com",
       key_name="dns-aid-key",
       key_secret="base64secret==",
       key_algorithm="hmac-sha256"
   )

   await publish(
       name="my-agent",
       domain="example.com",
       protocol="mcp",
       endpoint="agent.example.com",
       backend=backend
   )
   

DDNS Advantages

• Universal: Works with BIND, Windows DNS, PowerDNS, Knot, and any RFC 2136 server
• No vendor lock-in: Standard protocol, no proprietary APIs
• On-premise friendly: Perfect for enterprise internal DNS
• Full DNS-AID compliance: Supports ServiceMode SVCB with all parameters

Cloudflare Setup

Cloudflare DNS is ideal for demos, workshops, and quick prototyping thanks to its free tier and excellent API support. DNS-AID fully supports Cloudflare's SVCB record implementation.

Environment Variables

Step-by-Step Setup

1. Create an API token in Cloudflare Dashboard: - Go to My Profile → API Tokens → Create Token - Use the "Edit zone DNS" template or create custom with: - Permissions: Zone → DNS → Edit - Zone Resources: Include → Specific zone → your-domain.com - Copy the token (shown only once)

2. Configure environment variables:

   export CLOUDFLARE_API_TOKEN="your-api-token"
   # Optional: specify zone ID (otherwise auto-discovered from domain)
   export CLOUDFLARE_ZONE_ID="your-zone-id"
   

3. Publish your first agent:

   dns-aid publish \
       --name my-agent \
       --domain your-domain.com \
       --protocol mcp \
       --endpoint agent.your-domain.com \
       --backend cloudflare
   

4. Use in Python:

   from dns_aid.backends.cloudflare import CloudflareBackend
   from dns_aid import publish

   # Initialize backend (reads from environment variables)
   backend = CloudflareBackend()

   # Or with explicit configuration
   backend = CloudflareBackend(
       api_token="your-api-token",
       zone_id="optional-zone-id",  # Auto-discovered if not provided
   )

   await publish(
       name="my-agent",
       domain="your-domain.com",
       protocol="mcp",
       endpoint="agent.your-domain.com",
       backend=backend
   )
   

Cloudflare Advantages

• Free tier: DNS hosting is free for unlimited domains
• SVCB support: Full RFC 9460 compliance with SVCB Type 64 records
• Global anycast: Fast DNS resolution worldwide
• Simple API: Well-documented REST API v4
• Full DNS-AID compliance: Supports ServiceMode SVCB with all parameters

Quick Start

CLI Usage

```bash

Examples

See the examples/ directory:

• demo_route53.py - Basic Route 53 publish/discover
• demo_full.py - Complete end-to-end demonstration

```bash

Run the full demo

export DNS_AID_TEST_ZONE="your-zone.com" python examples/demo_full.py ```

directory_api_url can also be set via DNS_AID_SDK_DIRECTORY_API_URL env var.

config = SDKConfig(directory_api_url="https://api.example.com")

async with AgentClient(config=config) as client: response = await client.search( q="payment processing", protocol="mcp", capabilities=["payment-processing"], min_security_score=70, verified_only=True, ) for r in response.results: print(f"{r.score:.2f} {r.agent.fqdn} T{r.trust.trust_tier}")

**Zero-trust composition**: Path B → Path A re-verify before invoking. Directory is
opt-in convenience; DNS substrate is the authoritative trust gate.

Cross-domain search via configured directory backend (v0.19.0+)

export DNS_AID_SDK_DIRECTORY_API_URL=https://api.example.com dns-aid search "payment processing" --protocol mcp --min-security-score 70

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

```python import dns_aid

Fetch community-wide rankings from the directory API (v0.19.0+)

from dns_aid.sdk import AgentClient, SDKConfig

config = SDKConfig(directory_api_url="https://api.example.com") async with AgentClient(config) as client: rankings = await client.fetch_rankings(limit=10) for r in rankings: print(f"{r['agent_fqdn']}: {r['composite_score']}")

**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](docs/integrations/opentelemetry.md).

For advanced usage (connection reuse, OTEL export):

config = SDKConfig( otel_enabled=True, # Export to OpenTelemetry caller_id="my-app", http_push_url="https://api.example.com/v1/telemetry/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 local telemetry signals ```

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 with HTTP index

dns-aid discover example.com --use-http-index

Choosing the Right Interface

DNS-AID provides three interfaces. Choose based on your use case:

CLI Tool

Best for: Operators, DevOps, and quick manual operations.

dns-aid discover example.com --protocol mcp

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dns-aid": {
      "command": "dns-aid-mcp"
    }
  }
}

Then Claude can discover and connect to AI agents:

"Find available agents at example.com" "Publish my chat agent to DNS at mycompany.com" "Discover agents at example.com and search for flights from SFO to JFK"

Live Demo

Try the live demo with Claude Desktop:

{
  "mcpServers": {
    "dns-aid": {
      "command": "python",
      "args": ["-m", "dns_aid.mcp.server"]
    }
  }
}

Then ask Claude to discover and use the booking agent:

"Discover agents at example.com using HTTP index, find a booking agent, and search for flights from SFO to JFK on March 15th 2026"

Claude will: 1. Call discover_agents_via_dns → finds booking-agent at https://booking.example.com/mcp 2. Call list_agent_tools → sees search_flights, get_flight_details, check_availability, create_reservation 3. Call call_agent_tool → searches for flights and returns results

Server-Side: Agent Directory Pipeline

┌──────────────────────────────────────────────────────────────────────────┐
│                    AGENT DIRECTORY PIPELINE                              │
│                                                                          │
│  ┌──────────┐   ┌───────────────┐   ┌──────────────┐   ┌────────────┐  │
│  │ CRAWLING │──▶│   CURATION    │──▶│   INDEXING   │──▶│  SERVING   │  │
│  │          │   │               │   │              │   │            │  │
│  │ DNS SVCB │   │ trust_score   │   │ TSVECTOR     │   │ REST API   │  │
│  │ HTTP Idx │   │ security_score│   │ full-text    │   │ Search     │  │
│  │ .well-   │   │ telemetry     │   │ search       │   │ Rankings   │  │
│  │ known/   │   │ scoring       │   │              │   │            │  │
│  │ agent.json   │               │   │              │   │            │  │
│  └──────────┘   └───────────────┘   └──────────────┘   └────────────┘  │
│       │                                                                  │
│       ▼                                                                  │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │             METADATA ENRICHMENT (Phase 5.5)                      │   │
│  │                                                                  │   │
│  │  GET /.well-known/agent.json                                     │   │
│  │    ├─ "aid_version" present? → Parse as DNS-AID AgentMetadata    │   │
│  │    └─ No? → Try A2A Agent Card → Transform to metadata fields    │   │
│  │                                                                  │   │
│  │  Extracts: transport, auth, capabilities (intent/semantics),     │   │
│  │            lifecycle (deprecated, sunset_date, successor)        │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Run tests for a specific package

uv run pytest packages/dns-aid-directory/tests/ uv run pytest packages/dns-aid-crawlers/tests/ uv run pytest packages/dns-aid-k8s/tests/

Background and Comparison

For background on how DNS-AID compares to other agent-discovery approaches (ANS, Google A2A+UCP, .agent gTLD, AgentDNS, NANDA, Web3, ai.txt) and "The Sovereignty Question", see docs/positioning.md. That content is non-normative — protocol positioning is determined at the IETF.