Protocol › Zone Files
$ cat zone-files.md
The zone file is a JSON document that declares all the agent capabilities for a domain.
// location
Zone file location
Host your zone file at the well-known path on your domain:
https://<domain>/.well-known/agentroot.json
The URL in your DNS TXT record must point to this file. HTTPS is required. The domain field inside the JSON must match the domain from the DNS query.
// required_fields
Required fields
A zone file has two required top-level fields:
| Field | Type | Description |
|---|
| domain | string | The domain this zone describes. Must match the DNS record's domain. |
| records | array | Array of record objects. Each declares an agent, MCP server, skill, or A2A endpoint. |
Each record in the array requires:
| Field | Type | Description |
|---|
| type | string | agent, mcp, skill, a2a, or any custom string |
| id | string | Unique within the zone. Lowercase, hyphens allowed. |
| name | string | Display name |
| description | string | What it does. One or two sentences. |
// full_example
Full example zone file
{
"domain": "example.com",
"version": "2025-04-02",
"contact": "hello@example.com",
"records": [
{
"type": "agent",
"id": "assistant",
"name": "My Assistant",
"description": "A research assistant that can search and analyze documents",
"endpoint": "https://example.com/agent",
"protocol": "a2a",
"capabilities": ["research", "analysis", "summarization"]
},
{
"type": "mcp",
"id": "db-tools",
"name": "DataTools",
"description": "Database query and visualization tools",
"endpoint": "https://example.com/mcp",
"transport": "sse",
"tools": [
{ "name": "query_database", "description": "Execute SQL queries" },
{ "name": "visualize_data", "description": "Generate charts from data" }
]
},
{
"type": "skill",
"id": "coding-helpers",
"name": "Coding Helpers",
"description": "Skills for linting, testing, and deployment workflows",
"index": "https://example.com/.agents/skills/index.json"
},
{
"type": "a2a",
"id": "task-runner",
"name": "Task Runner",
"description": "Executes long-running background tasks with progress reporting",
"endpoint": "https://example.com/.well-known/agent.json",
"capabilities": ["long-running-tasks", "file-processing"]
}
],
"subdomains": ["api", "chat"]
}
// subdomains
Subdomain references
A parent zone can list its subdomains as a discovery hint:
{
"domain": "example.com",
"records": [ ... ],
"subdomains": ["api", "chat"]
}
Each subdomain has its own _agentroot TXT record and its own zone file. The parent's subdomains array is a hint for discovery — the subdomain's DNS record is the source of truth.
# Subdomain gets its own DNS record
_agentroot.api.example.com TXT "v=ar1 zone=https://api.example.com/.well-known/agentroot.json"
// inline_vs_zone
Inline mode vs zone file mode
You have two choices for declaring records:
| Mode | When to Use | DNS Record |
|---|
| Zone file |
Multiple records, or you want full JSON flexibility |
v=ar1 zone=https://... |
| Inline |
Single record, quick setup, no hosting needed |
v=ar1 type=agent name=... |
Zone file mode — your DNS record points to a JSON file:
_agentroot.example.com TXT "v=ar1 zone=https://example.com/.well-known/agentroot.json"
Inline mode — the record lives directly in DNS:
# Agent
_agentroot.example.com TXT "v=ar1 type=agent name=MyBot endpoint=https://example.com/api"
# MCP server
_agentroot.example.com TXT "v=ar1 type=mcp name=Tools transport=sse endpoint=https://example.com/mcp"
# Skill
_agentroot.example.com TXT "v=ar1 type=skill index=https://example.com/.agents/skills/index.json"
Use inline for quick single-record setups. Use a zone file when you have multiple records or want richer metadata.
// extensibility
Optional and custom fields
The zone file is JSON. You can add any fields you want. Fields the protocol doesn't recognize are preserved but ignored. This is how extensibility works — no formal schema changes needed.
{
"domain": "example.com",
"version": "2025-04-02",
"contact": "hello@example.com",
"custom_field": "anything you want",
"records": [ ... ]
}
// security
Security requirements
When registries fetch zone files, the following rules apply:
| Rule | Details |
|---|
| HTTPS only | No HTTP zone file URLs. TLS required. |
| SSRF protection | Private IP ranges are blocked. |
| Timeout | 10-second fetch timeout. |
| Size limit | 1 MB maximum zone file size. |
| Domain match | The domain field must match the queried domain. |