# 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:

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

Recommended extended version:

```json
{
  "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:**

```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):**

```typescript
// 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."

[← All glossary terms](/en/glossary)