Protocol Overview — Docs

// how_it_works

Three layers

The AgentRoot protocol has three layers. DNS proves ownership. The zone file declares capabilities. The registry indexes everything for search and discovery.

Layer 1: DNS

_agentroot.example.com TXT
"v=ar1 zone=https://..."

→

Layer 2: Zone File

{
  "domain": "example.com",
  "records": [
    { "type": "agent", ... },
    { "type": "mcp", ... }
  ]
}

Layer 3: Registry (optional)

// Search, indexing, CLI, MCP server, A2A
// Convenience layer — protocol works without it

Step 1: Add a TXT record at _agentroot.<your-domain>. It points to a JSON file.
Step 2: The JSON file lists your agent capabilities — agents, MCP servers, skills, A2A endpoints.
Step 3: AgentRoot verifies the DNS record and indexes your zone.

// dns_record

The DNS record

Add a TXT record at _agentroot.<your-domain>:

# Zone URL mode — points to a JSON zone file
_agentroot.example.com  TXT  "v=ar1 zone=https://example.com/.well-known/agentroot.json"

Two fields. v=ar1 is the protocol version. zone=<url> points to your zone file. For single-record setups, you can skip the zone file entirely with inline mode.

# Inline mode — single record, no zone file needed
_agentroot.example.com  TXT  "v=ar1 type=agent name=MyBot endpoint=https://example.com/api"

Full DNS record docs →

// zone_file

The zone file

Host a JSON file at https://<domain>/.well-known/agentroot.json. It declares everything your domain offers.

{
  "domain": "example.com",
  "records": [
    {
      "type": "agent",
      "id": "assistant",
      "name": "My Assistant",
      "description": "A research assistant",
      "endpoint": "https://example.com/agent"
    },
    {
      "type": "mcp",
      "id": "db-tools",
      "name": "DataTools",
      "description": "Database query and visualization tools",
      "endpoint": "https://example.com/mcp",
      "transport": "sse"
    },
    {
      "type": "skill",
      "id": "coding-helpers",
      "name": "Coding Helpers",
      "description": "Skills for linting, testing, and deployment",
      "index": "https://example.com/.agents/skills/index.json"
    }
  ]
}

Full zone file docs →

// record_types

Record types

Four built-in types, plus any custom type you want.

Type	What It Is	Key Fields
agent	An AI agent that accepts tasks and returns results	`endpoint`, `protocol`, `capabilities`
mcp	A Model Context Protocol server exposing tools	`endpoint`, `transport`, `tools`
skill	A collection of SKILL.md instruction files	`index` or `skill_md`
a2a	An Agent-to-Agent protocol endpoint	`endpoint`, `capabilities`

Custom types (e.g., workflow, dataset) use the same base fields. Registries index them; they just won't have type-specific UI.

Full record type docs →

// verification

Verification model

Trust is built on DNS ownership. Only domain admins can set TXT records, so a valid DNS record proves the domain owner authorized the zone file.

State	Meaning
verified	DNS record found, zone file valid, domain field matches
pending	Submitted but not yet checked
failed	DNS record missing or zone file invalid

The registry re-verifies periodically. If DNS goes away, the records go away. URL-submitted records (no DNS) are marked as unverified and cannot override DNS-verified records.

// discovery