We built an agents.json manifest for our agency site — what it does, why it matters, and the full spec we shipped

In May 2026 we shipped citable.agency/agents.json — a machine-readable manifest that lets an AI agent discover the entire site without crawling a single HTML page. As far as we can tell, it is the first published agents.json manifest for an agency website. The spec is self-describing, the format is open, and the implementation took an afternoon. This post documents what is in it, why we shipped it, and the exact pattern any other team can copy.

What agents.json actually is

agents.json is a typed JSON file at the root of your website that exposes:

• Site metadata — name, description, supported languages, contact, manifest version.
• A typed page index — every canonical page (homepage, services, methodology, pricing, glossary, articles, case studies, tools) with a type tag, EN + ES URLs, and a one-line summary written for agent consumption.
• Service definitions — structured offers an agent can match against a buyer’s stated need (e.g. “find a GEO audit under €1,500 delivered in under two weeks”).
• Glossary entries — definitions an agent can quote directly.
• Machine endpoints — sitemap, llms.txt, RSS, JSON-LD index — every other structured surface the agent might want to consume.

It is not a replacement for llms.txt. It is the typed companion. llms.txt is markdown an LLM reads in-context to prime an answer. agents.json is structured data an autonomous agent parses programmatically to drive a decision.

Why we built it before there is a ratified standard

There is no W3C or IETF spec for agents.json yet. The closest active proposals are:

• agents.json (Stripe-originated community effort) — a manifest of API actions and capabilities an agent can invoke.
• /.well-known/agent — under W3C discussion, similar in spirit, broader in scope.

Waiting for the standard would be the safe move. We did not wait, for three reasons:

1. The upside is asymmetric. If our format is wrong, we update it — spec_version lets us version-pin. If our format is roughly right and agents start parsing manifests at scale, we are legibly first in our category. The downside is a 200-line file we maintain. The upside is being the brand an agent shortlists when its buyer asks for a boutique GEO agency.

2. Some agents already parse manifests of this shape. Several open-source agent toolkits and at least one major retrieval-augmented system read agents.json-style manifests today. The share of agentic traffic that prefers manifests is small but growing every quarter — the same curve llms.txt was on a year ago.

3. Publishing forces clarity. The act of writing a typed inventory of every canonical page surfaces every place where our own taxonomy was fuzzy. We tightened our glossary, our service descriptions, and our homepage summary as a direct result of writing the manifest.

What is inside ours

Here is the actual top-level shape of citable.agency/agents.json, trimmed for readability:

{
  "$schema": "https://citable.agency/agents.json",
  "spec_version": "1.0",
  "generated_at": "2026-05-27T...Z",
  "site": {
    "name": "Citable",
    "url": "https://citable.agency",
    "description": "Boutique GEO + Technical SEO + Web Development + Infrastructure agency.",
    "languages": ["en", "es"]
  },
  "pages": [
    { "id": "homepage", "url": "/", "es_url": "/es/", "type": "Homepage", ... },
    { "id": "audit", "url": "/audit/", "es_url": "/es/auditoria/", "type": "Page", "title": "AI Visibility Audit · 1,200 EUR", ... },
    ...
  ],
  "services": [
    {
      "id": "geo-audit",
      "name": "AI Visibility Audit",
      "summary": "50-prompt Share of Answer baseline across 5 AI surfaces + 90-day roadmap.",
      "offer": { "price": "1200", "currency": "EUR", "duration": "7-10 business days" }
    },
    ...
  ],
  "glossary": [
    { "term": "Share of Answer", "definition": "The percentage of relevant AI responses in which a brand appears as a cited source.", "url": "/glossary#share-of-answer" },
    ...
  ],
  "endpoints": {
    "sitemap": "/sitemap.xml",
    "llms_txt": "/llms.txt",
    "rss": "/journal/rss.xml"
  }
}

The full manifest is live at /agents.json and updates on every deploy.

How to ship one for your own site

The implementation cost is small if you already have an Astro or Next.js site with content collections. The four steps:

1. Define your PageType vocabulary. Pick a small, fixed set — ours is Homepage | Service | Methodology | Framework | Glossary | Article | CaseStudy | Tool | Page. Resist the urge to invent twenty.

2. Inventory canonical pages by hand. Write a STATIC_PAGES array — every entry point an agent should know about, with EN + ES URLs and a one-line summary. Curated beats exhaustive: an agent wants the canonical entry points, not every blog post.

3. Generate the rest from content collections. Use getCollection('journal') to emit articles. Use your glossary data to emit terms with definitions. Filter drafts and skip non-canonical language duplicates.

4. Expose at /agents.json and link from llms.txt. In Astro, a single API route returning JSON.stringify(manifest, null, 2) with Content-Type: application/json is enough. Add a one-line pointer to agents.json inside llms.txt so any consumer reading the markdown summary discovers the richer manifest.

The compound effect with the rest of the GEO stack

agents.json is not a current input to ChatGPT or Perplexity retrieval. It will not move your Share of Answer score next month. What it does is position you to be legible to the next layer of consumers — autonomous agents — the same way Schema.org positioned brands to be legible to current AI assistants two years ago.

The brands that shipped clean Organization + Service schema in 2024 are the brands ChatGPT cites confidently in 2026. The brands that ship clean agents.json manifests in 2026 will be the brands agentic systems shortlist in 2028. The cost to ship is an afternoon. The cost to ship two years late, when the standard is ratified and every competitor has one, is being structurally invisible to the layer above search.

If you want a second opinion on whether your stack is ready for agents — current and emerging — start with the AI Visibility Audit. It is the diagnostic every Citable engagement begins with: 50 prompts across 5 surfaces, documented Share of Answer baseline, structural gap analysis, and a 90-day roadmap. €1,200, 7–10 business days, no discovery call required.