agentsready
Discoverability Easy

ai-agent.json: your site's business card for AI agents

What ai-agent.json is, why agents need a machine-readable site manifest, a minimal example, right vs wrong, mistakes, and how to verify.

Updated:

What it is

ai-agent.json is a machine-readable JSON manifest of your site for AI agents, placed at a well-known path (/.well-known/ai-agent.json). It’s a “business card”: who you are, what you offer, how to interact, and where to reach you. The convention is still emerging, so the exact field set depends on your capabilities — but a base minimum is stable.

Why it matters for AI agents

An agent that arrives to perform a task needs to quickly grasp: what this service is, whether there’s an API, what the terms are. Parsing all the HTML for that is expensive and unreliable. One predictable JSON at a known address gives the agent solid ground without guessing, and raises the chance it represents you correctly in an answer or workflow.

Minimal working example

{
  "name": "Example Inc.",
  "description": "Analytics platform for e-commerce.",
  "url": "https://example.com",
  "contact": "agents@example.com",
  "capabilities": ["search", "pricing"],
  "endpoints": {
    "api": "https://example.com/.well-known/api-catalog"
  }
}

Add fields beyond the minimum as you actually offer more to agents.

Right vs wrong

RightWrong
Served at /.well-known/ai-agent.json, application/jsonAn arbitrary path the agent won’t find
Valid JSON, absolute URLsBroken JSON or relative links
Fields reflect real capabilitiesDeclared endpoints that don’t exist
A short, clear descriptionMarketing fluff with no substance

Common mistakes

  • Invalid JSON — the agent discards the whole file.
  • Wrong path — not under /.well-known/, so the agent can’t find it.
  • Declared endpoints/capabilities that don’t exist — erodes trust.
  • Served as HTML (SPA) instead of application/json.
  • Manifest version confusion — keep one canonical file.

How to verify

A scan checks for the manifest and its validity. Manually:

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

jq should parse the file without errors — meaning the JSON is valid.

Sources