ai-agent.json

What is ai-agent.json?

ai-agent.json is a machine-readable manifest at /.well-known/ai-agent.json that describes a site’s capabilities for AI agents: what it can do, which endpoints are available, and how to interact with them.

The standard was developed by Aiia (AI Interoperability Alliance) and published in March 2026. Most sites do not yet support it — early adoption provides a first-mover advantage. Our scanner records absence as neutral (not fail): the standard is new.

The /.well-known/ path is the standard mechanism for publishing metadata per RFC 5785 (where openid-configuration, security.txt, and others also live).

Why does a site need ai-agent.json?

Before ai-agent.json, an AI agent had no single place to learn “what can this site do?” — it had to guess from URL structure or act blindly.

The manifest solves this declaratively:

• Capability discovery — the agent reads the file and immediately sees the list of capabilities: ["scan", "report", "contact"]
• Endpoint mapping — direct mapping of “capability → URL” without guesswork
• Planning context — an agent with the task “check AI-readiness of example.com” reads the scanner’s ai-agent.json and understands exactly how to trigger a scan
• Federated discovery — AI registries will be able to index sites by manifest to find the right tool

How to implement ai-agent.json?

Minimal ai-agent.json per the Aiia spec:

{
  "name": "Example Corp",
  "description": "SaaS platform for project management"
}

Recommended extended version:

{
  "name": "Agent Ready Scanner",
  "description": "Public scanner for AI agent-readiness across 23 open standards",
  "version": "1.0",
  "capabilities": [
    "scan",
    "report",
    "advise"
  ],
  "endpoints": {
    "scan": {
      "url": "/api/scan",
      "method": "POST",
      "description": "Submit URL for scanning",
      "parameters": {
        "url": "string — URL to scan"
      }
    }
  },
  "contacts": {
    "email": "hello@agentsready.io",
    "url": "/about"
  },
  "documentation": "/scanner",
  "terms": "/terms",
  "privacy": "/privacy"
}

Technical requirements:

• Path: /.well-known/ai-agent.json (strict)
• Content-Type: application/json
• Encoding: UTF-8
• Required fields: name (string), description (string)
• Recommended: capabilities (array), endpoints (object), contacts (object)

For static sites:

Create public/.well-known/ai-agent.json. Verify that the server does not block /.well-known/ — firewall or WAF rules sometimes block paths with a leading dot.

For Nginx:

location = /.well-known/ai-agent.json {
    add_header Content-Type application/json;
    alias /var/www/well-known/ai-agent.json;
}

Dynamic generation (if data changes):

// src/pages/.well-known/ai-agent.json.ts
export async function GET() {
  const manifest = {
    name: 'My App',
    description: 'Description',
    capabilities: ['feature1', 'feature2'],
  };
  return new Response(JSON.stringify(manifest, null, 2), {
    headers: { 'Content-Type': 'application/json' }
  });
}

How do we check ai-agent.json?

Our scanner performs GET /.well-known/ai-agent.json and verifies:

1. HTTP status — if 404, status neutral (standard is new; absence is not penalized)
2. HTTP 200 — the file exists
3. Valid JSON — parses without errors
4. Required fields — name and description are present and both are strings

If all conditions are met — pass. If the JSON is invalid or required fields are missing — fail (file exists but is incorrectly formed). HTTP 404 — neutral with the note “standard is new, add it for early-adopter advantage.”