agentlookup.dev

.well-known/agents.json spec

What is it?

A JSON file at /.well-known/agents.json on any domain that declares which AI agents operate from that domain and where to look them up.

Think of it like robots.txt for AI agents. Instead of telling crawlers what to avoid, it tells other agents what's available and how to find it.

Any agent crawling a domain can check /.well-known/agents.json to discover agents, then look up their full details in the registry.

Schema

// example.com/.well-known/agents.json

{
  "schema": "agentlookup-v1",
  "registry": "https://agentlookup.dev",
  "agents": [
    {
      "agent_id": "ag_acme-scheduler_7kx2m",
      "name": "acme-scheduler",
      "capabilities": ["scheduling", "calendar-write"],
      "endpoint": "https://example.com/agents/scheduler"
    }
  ]
}

Field	Required	Description
schema	yes	Always "agentlookup-v1"
registry	yes	Registry URL, e.g. https://agentlookup.dev
agents	yes	Array of agent objects
agents[].agent_id	yes	The agent's ID in the registry
agents[].name	no	Human-readable agent name
agents[].capabilities	no	Array of capability strings
agents[].endpoint	no	Agent's endpoint URL

Multiple agents

A domain can declare any number of agents. List them all in the same file.

{
  "schema": "agentlookup-v1",
  "registry": "https://agentlookup.dev",
  "agents": [
    {
      "agent_id": "ag_acme-scheduler_7kx2m",
      "name": "acme-scheduler",
      "capabilities": ["scheduling", "calendar-write"]
    },
    {
      "agent_id": "ag_acme-support_3fn8k",
      "name": "acme-support",
      "capabilities": ["customer-support", "ticket-triage"]
    }
  ]
}

How it works

Register your agent at agentlookup.dev to get an agent_id
Create a file at yourdomain.com/.well-known/agents.json
List your agent IDs in the file
Done. Other agents can now discover your agents by fetching the file, then looking up full details from the registry.

Verify

Check that the file is reachable:

curl -s https://example.com/.well-known/agents.json | jq .

Look up full agent details from the registry:

# For each agent_id in the file:
curl https://agentlookup.dev/api/a/ag_acme-scheduler_7kx2m

Design principles

Static file. No server logic needed. Host it on any CDN, S3 bucket, or static site.
Pointer, not payload. The file points to the registry. Full agent details (capabilities, status, protocols) live in the registry and stay up to date.
Domain-scoped trust. An agents.json file at example.com means the domain owner is claiming those agents. It's a signal, not a guarantee.
Additive. The file doesn't replace registration. Agents must still be registered in the registry. The file just helps discovery.