.well-known/agent.json

The standard agent discovery file, analogous to robots.txt but written specifically for AI agents.

What is agent.json?

The agent.json file lives at /.well-known/agent.json on your domain. It is the closest thing the AI ecosystem has to a formal discovery standard, and it describes your product, its capabilities, and how agents should interact with it.

The .well-known path is defined by RFC 8615 — the same path used by security.txt, openid-configuration, and other machine-discoverable metadata. Putting your agent manifest there tells crawlers exactly where to look.

Why does it matter?

Agent crawlers check a small number of well-known paths. If you do not have an agent.json, you are invisible to anything that treats it as the canonical entry point. And the cost of shipping one is trivial — a single static file.

It is also the primary place to advertise your /skill endpoint, your skill.md file, and any API capabilities. An agent that reads your agent.json gets a roadmap of everything else you have published for it.

What should it contain?

{
  "name": "acme-crm",
  "description": "Lightweight CRM for small sales teams.",
  "url": "https://acmecrm.com",
  "capabilities": [
    {
      "name": "website-check",
      "endpoint": "/api/check",
      "method": "POST",
      "content_type": "application/json"
    }
  ],
  "skill_file": "/skill.md",
  "contact": "hello@acmecrm.com"
}

How to serve it

Place the file at public/.well-known/agent.json (or the equivalent path in your framework). Serve it with Content-Type: application/json. That is the entire implementation.

If you use Next.js, the file under public/.well-known/agent.json will be served automatically. For Express, you can use express.static. For static sites hosted on S3 or Cloudflare Pages, just drop the file in the right folder.

Best practices