The Problem: AI Agents Can't Find Each Other

Imagine you've built an AI agent that's great at writing code. Your colleague has one that's great at reviewing code. Wouldn't it be great if they could work together?

Right now, connecting them means hardcoding URLs, sharing API keys over Slack, and hoping nothing changes. It's like having to memorize everyone's phone number instead of looking them up in a directory.

The Solution: A Contact Card in DNS

DNS-AID publishes a rich "contact card" for each AI agent into DNS. Here's what it looks like:

This uses a DNS record type called SVCB — a modern record type designed to carry rich connection information in a single lookup.

Three Things You Can Do

See It in Code

Here's the entire workflow in Python — six lines of code:

import dns_aid

# Publish your agent to DNS
await dns_aid.publish(
    name="my-agent",
    domain="example.com",
    protocol="mcp",
    endpoint="agent.example.com"
)

# Discover agents at a domain
agents = await dns_aid.discover("example.com")

# Verify trust
result = await dns_aid.verify(agents[0].fqdn)

Check Your Understanding

The Main Characters

Think of DNS-AID as a talent agency for AI agents. Different departments handle different jobs:

How the Code Is Organized

The AgentRecord: The Star of the Show

Every agent in the system is represented by an AgentRecord — the data structure that holds all the information from its DNS contact card.

class AgentRecord(BaseModel):
    name: str
    domain: str
    protocol: Protocol
    target_host: str
    port: int = 443
    capabilities: list[str]
    cap_uri: str | None
    policy_uri: str | None

The DNS Name Formula

Every agent gets a structured DNS name built from three pieces:

_chat._mcp._agents.example.com

Check Your Understanding

Publishing: From Python to DNS Records

When you call dns_aid.publish(), here's the journey your data takes — like dropping a letter into a mailbox and watching it get sorted, stamped, and delivered.

The Backend Factory: A Clever Pattern

DNS-AID supports 7 different DNS providers. Instead of a giant if/else chain, it uses a factory pattern:

_BACKEND_CLASSES = {
    "route53":    ("dns_aid.backends.route53",    "Route53Backend"),
    "cloudflare": ("dns_aid.backends.cloudflare", "CloudflareBackend"),
    "ddns":       ("dns_aid.backends.ddns",       "DDNSBackend"),
    "mock":       ("dns_aid.backends.mock",       "MockBackend"),
}

def create_backend(name):
    module_path, class_name = _BACKEND_CLASSES[name]
    module = importlib.import_module(module_path)
    return getattr(module, class_name)()

Discovery: From DNS Query to Agent List

Now the reverse — how an agent finds other agents. Like a traveler arriving in a new city and looking up the local directory.

Invocation: One Agent Calls Another

After discovery, the AgentClient handles the actual call. Here's the pipeline:

Check Your Understanding

One Interface, Many Providers

Every backend must implement the same set of operations. This is the abstract base class:

The Custom Parameter Problem

DNS-AID adds custom fields to SVCB records (like key65400 for capability URIs). But here's the catch:

The solution? Parameter demotion. The base class automatically splits params:

The Discoverer knows to check both SVCB and TXT when reading an agent's details. Everything round-trips cleanly.

The DDNS Backend: Talk to BIND9 Directly

For local development, DNS-AID can talk to a BIND9 server using RFC 2136 dynamic updates:

class DDNSBackend(DNSBackend):
    def __init__(self, server, key_name,
                 key_secret, key_algorithm):
        self._keyring = dns.tsigkeyring.from_text(
            {self.key_name: self.key_secret}
        )

Check Your Understanding

Three Layers of Trust

DNS-AID uses a layered security model — like airport security with multiple checkpoints, each catching different threats:

The Auth Registry: Plug-and-Play Security

Auth handlers are registered in a dictionary — like a toolkit where each tool handles a different type of lock:

_REGISTRY = {
    "none":         _build_noop,
    "api_key":      _build_api_key,
    "bearer":       _build_bearer,
    "oauth2":       _build_oauth2,
    "http_msg_sig": _build_http_msg_sig,
    "sigv4":        _build_sigv4,
}

def resolve_auth_handler(auth_type,
                        auth_config,
                        credentials):
    factory = _REGISTRY[auth_type]
    return factory(auth_config, credentials)

The Security Score

The Validator computes a 0–100 security score by checking five things:

@property
def security_score(self) -> int:
    score = 0
    if self.record_exists:     score += 20
    if self.svcb_valid:        score += 20
    if self.dnssec_valid:      score += 30
    if self.dane_valid:        score += 15
    if self.endpoint_reachable: score += 15
    return score

Policy Rules: 16 Built-In Types

Policy documents are JSON files served at the agent's policy_uri. They can enforce rules like:

Check Your Understanding

The Debugging Map

When an agent call fails, the error usually lives in one of these layers. Think of it like a medical triage — the symptoms tell you which system to examine:

The Doctor Is In

DNS-AID includes a built-in diagnostic tool. Like a doctor's checkup, it examines your environment and reports what's healthy and what needs attention:

Check Your Understanding

The Two-Tier Architecture

DNS-AID is split into two distinct tiers — like a library with a front desk and a delivery service:

Agent Ranking: Who's the Best?

When you discover multiple agents that can do the same thing, the Signal Collector helps you pick the best one. The ranking formula:

Three Interfaces, One System

DNS-AID can be used three ways — same engine, different steering wheels:

The Internet Standard

DNS-AID isn't just a library — it's the reference implementation for IETF draft-mozleywilliams-dnsop-dnsaid-01, a proposed internet standard. The naming convention:

Final Check

You Did It!

You now understand how DNS-AID works — from the DNS naming convention to the backend factory pattern to the three-layer security model.

Built from the dns-aid-core codebase.