agent-vitals.json — a manifest for agent-readiness

A proposal to standardise on a /.well-known/agent-vitals.json file so a site can declare how well an AI agent can recover, understand, and act on the page — and any agent can read, and independently verify, that readiness before it spends a full crawl.

The gap

AI agents now read the web for your users — to answer a question or take an action. robots.txt says who may crawl, llms.txt says what to read, agents.json says what an agent can do. Nothing lets a page declare how well an agent can actually consume it, or lets an agent read that readiness cheaply before crawling. A page can look perfect to a person and be nearly useless to an agent — content injected by JavaScript a crawler never runs, entities undeclared, meaning buried under a token budget of boilerplate. This manifest is the missing quality-and-truth layer.

The file

A single JSON file at /.well-known/agent-vitals.json. It declares a page's Core Agent Vitals scores, its quality-gate results, its token decomposition, and — the part no existing standard covers — its perception delta: what the site claims to be versus what an agent actually recovers.

{
  "standard": "agent-vitals.json",
  "spec": "CAV-RFC-001",
  "created_by": { "name": "Rafael Lopes", "id": "https://r-lopes.com/#rafael-lopes", "role": "creator" },
  "framework": { "name": "Core Agent Vitals", "abbreviation": "CAV" },
  "site": "https://example.com",
  "measurement": {
    "aqs": 82,
    "scores": { "crr": 0.87, "ssd": 0.72, "tc": 1842, "ttfut_ms": 340 },
    "gates": { "cloaking": "pass", "thin_content": "pass", "dri_gaming": "pass" },
    "perception": {
      "claimed_name": "Acme Corp",
      "recovered_name": "Home | Menu | Shop",
      "delta_fields": ["name", "category"]
    }
  },
  "signature": { "method": "independent-remeasure", "verifiable_at": "https://agentvitals.dev/results?url=https%3A%2F%2Fexample.com" }
}

The perception block is the point. recovered_name: "Home | Menu | Shop" is what an agent extracts when a site's title is a navigation menu and its structured data is absent — the business an AI would describe to a user. Declaring that delta, and letting it be verified, is a signal that has no equivalent today.

Where it sits

A quality-and-truth layer beside the access and format standards already in use — it replaces none of them.

Verification

A self-reported score would be worth little. The signature.verifiable_at field points to an independent verifier: an agent reads the declared manifest cheaply, then — if it chooses — asks the analyzer to re-measure and compare. A large gap between declared and measured is itself a signal that the page is gaming its scores. This is how Core Web Vitals stays honest: sites can't fabricate their field data because Google measures it independently.

The vitals it declares

The scores block carries Core Agent Vitals (CAV) — the framework I named and defined (spec CAV-RFC-001) for how well an AI agent consumes a page, the machine-consumer equivalent of Core Web Vitals. Six metrics:

CAV also defines deterministic gates — a cloaked page, a soft-blocked shell, or declared-versus-rendered gaming can never score as “ready.” The analyzer at agentvitals.dev scores any URL against this today.