Content Negotiation voor AI Agents: Waarom Sentry Markdown Serveert in Plaats van HTML

David Cramer, medeoprichter en CPO van Sentry, publiceerde onlangs een praktische gids voor het optimaliseren van content voor AI agents . Zijn argument is simpel: "je moet content optimaliseren voor agents, net zoals je dingen optimaliseert voor mensen." Niet met nieuwe protocollen of complexe infrastructuur — met HTTP content negotiation, een standaard die sinds 1999 in de specificatie staat.

De techniek is eenvoudig. Wanneer een verzoek Accept: text/markdown bevat, stuurt de server schone markdown terug in plaats van een volledige HTML-pagina. Navigatie, JavaScript, sidebar-widgets — alles gestript. Alleen de content die de agent daadwerkelijk nodig heeft.

Wat is Content Negotiation?

Content negotiation is een HTTP-mechanisme waarbij een client aan de server vertelt welk formaat de voorkeur heeft, en de server dienovereenkomstig levert. Het is gedefinieerd in RFC 9110 en maakt sinds HTTP/1.1 deel uit van het web. Browsers hebben het altijd al gebruikt — wanneer je browser Accept: text/html stuurt, weet de server dat HTML teruggegeven moet worden.

Het inzicht is dat AI agents hetzelfde mechanisme kunnen gebruiken. Wanneer een agent Accept: text/markdown stuurt, kan de server een gestripte markdown-versie van de pagina teruggeven. Dezelfde URL, dezelfde content, andere representatie. Geen aparte API, geen speciale endpoints, geen nieuwe protocollen nodig.

GET /docs/getting-started HTTP/1.1
Host: docs.example.com
Accept: text/markdown, text/html;q=0.9

---

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept

# Getting Started

Install the SDK with your package manager:

```bash
npm install @example/sdk
```

De Drie Optimalisatiegebieden

Cramer identificeert drie gebieden waar contentoptimalisatie het meest uitmaakt voor agents. Dit zijn geen theoretische overwegingen — ze zijn gebaseerd op hoe frontier-modellen daadwerkelijk webcontent verwerken:

Samen verklaren deze waarom het serveren van HTML aan een agent verspilling is. Een typische documentatiepagina kan 15.000 tokens zijn als HTML, maar slechts 3.000 tokens als markdown. De agent krijgt dezelfde informatie — koppen, alinea's, codeblokken, links — zonder de structurele overhead.

Hoe Sentry Content Negotiation Implementeert

Sentry's aanpak heeft drie lagen, die elk een ander probleem oplossen:

1. Documentatie: Echte Markdown Serveren

Wanneer een agent Sentry's documentatie opvraagt met Accept: text/markdown, stuurt de server de ruwe MDX-bron terug — dezelfde content die de HTML-pagina genereert, maar zonder de gerenderde navigatie, JavaScript-bundels of UI-chrome. De linkhiërarchie wordt herstructureerd zodat agents gerelateerde pagina's kunnen ontdekken via een platte sitemap in plaats van geneste navigatiebomen te crawlen.

Dit is het meest breed toepasbare patroon. Elke site met documentatie, helpartikelen of gestructureerde content kan dezelfde aanpak implementeren: detecteer de Accept-header en stuur een gestripte representatie terug.

2. Beveiligde Pagina's: Doorverwijzen naar Programmatische Alternatieven

Wanneer een agent een beveiligde pagina in de Sentry web-UI bereikt — een dashboard, issue-detail of projectinstellingen — stuurt Sentry niet gewoon een inlogscherm. In plaats daarvan verwijst het de agent door naar programmatische alternatieven: de MCP-server, de CLI-tool of de REST API. De agent wordt gewezen op waar hij wel toegang heeft tot de data, in plaats van vast te lopen op een pagina die hij niet kan bereiken.

3. Bootstrap Discovery: Agents Zichzelf Laten Configureren

Voor Sentry's CLI-tools en integraties kunnen agents een markdown-document ophalen dat het doel, de mogelijkheden en de snelstartinstructies van de tool beschrijft. Dit laat een agent zichzelf bootstrappen — begrijpen wat een tool doet en hoe het te gebruiken — zonder HTML-documentatiepagina's te parsen.

Dit is hetzelfde principe achter llms.txt — het bieden van een gecureerd, machine-leesbaar startpunt. Content negotiation is de transportlaag; de gecureerde content is de waardelaag.

Wie Doet Dit Al?

Sentry staat niet alleen. Content negotiation voor agents wordt een patroon in het hele developer tools-ecosysteem:

Het patroon tekent zich af aan beide kanten: contentaanbieders beginnen markdown te serveren, en AI agents beginnen erom te vragen. Vroege adopters hebben een samengesteld voordeel — agents die betere resultaten krijgen van je content zullen vaker terugkomen.

Hoe Content Negotiation te Implementeren

De implementatie is eenvoudiger dan je misschien denkt. Hier is een praktische aanpak:

Stap 1: Agent-Verzoeken Detecteren

Controleer de Accept-header op text/markdown. De meeste webframeworks maken dit eenvoudig:

defmodule MyAppWeb.Plugs.ContentNegotiation do
  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    accepts = get_req_header(conn, "accept")

    if Enum.any?(accepts, &String.contains?(&1, "text/markdown")) do
      assign(conn, :prefer_markdown, true)
    else
      assign(conn, :prefer_markdown, false)
    end
  end
end

function contentNegotiation(req, res, next) {
  req.prefersMarkdown = req.accepts(['text/markdown', 'text/html'])
    === 'text/markdown';
  next();
}

app.get('/docs/:slug', contentNegotiation, (req, res) => {
  if (req.prefersMarkdown) {
    res.type('text/markdown').send(getMarkdownContent(req.params.slug));
  } else {
    res.render('docs', { slug: req.params.slug });
  }
});

Stap 2: Schone Markdown Serveren

Strip alles wat geen content is: navigatie, headers, footers, JavaScript, trackingpixels, cookiebanners. Wat overblijft moet dezelfde content zijn die op de gerenderde pagina verschijnt, maar als schone markdown met een correcte koppenstructuur.

• Wel opnemen: koppen, alinea's, codeblokken, links, lijsten, afbeeldingen met alt-tekst, tabellen
• Niet opnemen: navigatie-HTML, script-tags, style-blokken, trackingpixels, UI-framework markup
• Wel instellen: Content-Type: text/markdown en Vary: Accept headers

De Vary: Accept header is belangrijk — het vertelt caches en CDN's dat de response varieert op basis van de Accept-header, waardoor een gecachte markdown-response niet aan browsers wordt geserveerd.

Stap 3: Belangrijke Informatie Vooraan Plaatsen

Omdat agents sequentieel lezen en lange content kunnen afkappen, zet de belangrijkste informatie vooraan:

• Begin met een duidelijke titel en samenvatting van één alinea
• Zet installatie-/snelstartinstructies bovenaan
• Verplaats vereisten, achtergrondcontext en changelog naar onderaan
• Gebruik beschrijvende koppen die logisch zijn zonder de onderliggende content te lezen

Voorbij Developer Docs

Content negotiation begon bij developerdocumentatie, maar het patroon is toepasbaar op elke content-rijke website. Denk aan:

Naarmate AI agents zich uitbreiden voorbij coderen naar browsen, winkelen en onderzoekstaken, heeft elke website met waardevolle content er baat bij. De vraag is niet of agents je content zullen consumeren — het is of ze dat efficiënt of verspillend zullen doen.

Hoe Dit Past in AI Agent Readiness

Content negotiation is één onderdeel van een bredere agent readiness-strategie. Het werkt het beste in combinatie met de andere signalen waar agents naar zoeken:

De Conclusie

David Cramer's post snijdt door de ruis rond AI agent-optimalisatie. Je hebt geen nieuwe protocollen of complexe infrastructuur nodig. Je hebt content negotiation nodig — een 25 jaar oude HTTP-standaard — toegepast op een nieuw publiek.

De implementatie is simpel: detecteer Accept: text/markdown, stuur schone markdown terug, zet je belangrijkste content vooraan. Voor beveiligde pagina's, verwijs agents door naar API's en CLI's in plaats van inlogschermen. Voor discovery, bied een gecureerd startpunt via llms.txt .

De bedrijven die vandaag bouwen voor agents — Sentry, Vercel, Cloudflare — gebruiken geen exotische nieuwe technologie. Ze gebruiken standaarden die al bestaan. De kloof is niet technisch. Het is bewustzijn. En die kloof sluit snel.

Bronnen

• David Cramer: Optimizing Content for Agents — Het originele artikel over Sentry's content negotiation-aanpak
• RFC 9110: HTTP Semantics — Content Negotiation — De HTTP-specificatie voor content negotiation
• How Vercel Built AEO Tracking for Coding Agents — Vercel's aanpak voor het meten van agent-verkeer
• Cloudflare: Introducing Markdown for Agents — Platformniveau content negotiation en markdown-transformatie
• IsAgentReady: AI-Crawlers Negeren llms.txt — Maar AI-Agents Niet — Waarom llms.txt ertoe doet voor agents, niet voor crawlers
• Checkly: The Current State of Content Negotiation for AI Agents — Onderzoek naar welke coding agents daadwerkelijk Accept: text/markdown headers sturen
• Cloudflare: Introducing Markdown for Agents — Benchmark die 80% tokenreductie toont (16.180 HTML-tokens naar 3.150 markdown)
• llms.txt Specificatie — Het originele voorstel van Jeremy Howard