The .well-known/agents.json Standard
A simple convention for websites to declare their AI agents — analogous to robots.txt for bots or sitemap.xml for pages.
What is it?
As AI agents proliferate, there is no standard way for a website to say “here are the agents that represent us.” The .well-known/agents.json standard proposes to fix this.
Place a agents.json file at the /.well-known/ path on your domain. Any agent, crawler, or directory (like AgentDNS) can discover your agents automatically by fetching this URL.
AgentDNS uses this standard to index agents. Crawlers that respect this standard will find your agents without you having to submit them to every directory manually.
Schema
{
"schema_version": "0.1.0",
"site": "https://your-site.com",
"agents": [
{
"name": "My Support Agent",
"slug": "my-support-agent",
"description": "Handles customer support inquiries",
"capabilities": ["customer-support", "faq", "ticket-routing"],
"protocols": ["a2a", "rest"],
"endpoints": {
"a2a": "https://your-site.com/.well-known/agent.json",
"rest": "https://api.your-site.com/support"
},
"authentication": {
"read": "none",
"write": "bearer"
}
}
]
}Fields
| Field | Type | Description |
|---|---|---|
| schema_version | string | Version of this spec (currently "0.1.0") |
| site | URL | Canonical URL of the declaring site |
| agents[].name | string | Human-readable agent name |
| agents[].slug | string | URL-safe identifier for the agent |
| agents[].description | string | What the agent does |
| agents[].capabilities | string[] | Capability tags (e.g. customer-support, code-generation) |
| agents[].protocols | string[] | Supported protocols: a2a, mcp, rest, graphql, websocket |
| agents[].endpoints | object | Protocol-keyed endpoint URLs |
| agents[].authentication | object | Auth requirements for read/write access |
How to Add Your Site
- 1
Create the file
Place
agents.jsonathttps://yourdomain.com/.well-known/agents.json - 2
Register on AgentDNS
Submit your agents to the AgentDNS registry via API or dashboard:
curl -X POST "https://agent-dns.tech/api/v1/agents" \ -H "Authorization: Bearer adns_k1_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "my-support-agent", "name": "My Support Agent", "capabilities": ["customer-support", "faq"], "protocols": ["a2a", "rest"], "a2a_endpoint": "https://your-site.com/.well-known/agent.json", "api_endpoint": "https://api.your-site.com/support" }' - 3
Validate your file
Use the validator below to check your agents.json is well-formed.
Validator
Enter your domain to validate your /.well-known/agents.json file:
Opens your /.well-known/agents.json in a new tab for inspection.
Eating Our Own Dog Food
AgentDNS publishes its own agents.json at the standard location: