Grille de compatibilité agent — 28 critères
AgentFit note chaque site audité selon 28 critères répartis en six catégories totalisant 100 points. Chaque critère possède une spécification explicite : ce que l'audit vérifie, comment les paliers de notation se traduisent en points, et une piste en une ligne pour combler l'écart. La spécification est déterministe et entièrement reproduite en code Go. Lisez l'article de méthodologie pour le contexte.
Au-delà des 28 critères notés, AgentFit met aussi en évidence des signaux émergents comme la prise en charge de WebMCP et la détection de serveurs MCP. WebMCP · MCP.
Sur cette page
Ce que signifie vraiment la compatibilité agent
Un agent lit votre documentation en HTTP, pas dans un navigateur avec un humain derrière. Il n’exécute pas votre JavaScript, ne fait pas défiler la page, ne survole pas un onglet pour révéler la liste des endpoints et ne demande pas à un collègue quelle est la limite de débit. Il récupère, analyse, et soit il trouve un contrat exploitable, soit il abandonne et devine. La compatibilité agent, c’est la part de ce chemin qu’une machine parcourt sans aide.
Elle est mesurable parce que chaque étape de ce chemin est un fait HTTP observable. /llms.txt existe-t-il et s’analyse-t-il. La page porte-t-elle une URL canonique absolue. Le document OpenAPI est-il valide et décrit-il ses schémas de réponse. La méthode, le chemin et un exemple fonctionnel figurent-ils dans le HTML brut qui arrive avant l’exécution du moindre script. Rien de tout cela n’exige de juger la qualité de la prose. AgentFit vérifie 28 faits de ce type et rapporte pour chacun ce qu’il a vu, avec l’URL récupérée et l’extrait qui sert de preuve.
Comment la note est calculée
Chacun des 28 critères possède une échelle de paliers entiers et une pondération. Un critère renvoie un statut — présent, partiel, absent, non applicable ou erreur — et une note comprise entre zéro et sa pondération. Les 28 notes se regroupent en six catégories dont la somme fait exactement 100. « Non applicable » et « erreur » valent tous deux zéro, mais sont étiquetés séparément à dessein : « nous n’avons pas pu mesurer » n’est pas la même affirmation que « ce n’est pas là », et les confondre laisserait une requête bloquée se faire passer pour un constat.
Les pondérations ne relèvent pas du goût éditorial. Chacune découle d’une règle écrite avant que les chiffres ne soient calculés : un critère gagne du poids lorsqu’il sépare des sites par ailleurs à égalité sur le reste de la grille, et en perd lorsque sa note dépend surtout de la plateforme de documentation utilisée. Un point obtenu pour avoir choisi tel hébergeur de docs est un point sur votre hébergement, pas sur votre documentation. La règle, la métrique et le vecteur final de pondérations ont été versionnés dans le dépôt avant la campagne de calibration ; l’ordre des commits fait office de piste d’audit, et cette même procédure a déjà rejeté l’hypothèse de son propre auteur.
L’audit est déterministe : le même site récupéré deux fois produit un JSON identique octet pour octet. Aucun modèle de langage ne tourne pendant la notation — deux petits classifieurs, pour le réalisme des exemples et la complétude des endpoints, sont compilés dans le binaire et versionnés avec lui, si bien qu’un réentraînement ne peut pas déplacer votre note en silence. Quand la règle de mesure change, la version de la grille est incrémentée et inscrite sur l’exécution, et comparer deux exécutions notées sous des versions différentes est refusé plutôt que présenté comme une évolution de votre site.
Pondération des catégories. La troisième colonne indique la question à laquelle la catégorie répond pour vous.
| Catégorie | Poids | Question traitée |
|---|---|---|
| A — Découverte | 14 | Un agent peut-il trouver votre documentation à des URL prévisibles ? |
| B — Éléments de page | 21 | Un parseur peut-il ingérer directement le contenu de chaque page ? |
| C — Contrat d'API | 17 | Le contrat de l'API est-il publié sous forme de spécification lisible par une machine ? |
| D — Contenu | 23 | Chaque page d'endpoint fournit-elle assez de contexte pour être exploitée ? |
| E — Rendu et hygiène | 21 | Le site est-il stable et utilisable sans JavaScript ? |
| F — Capacités d'agent | 4 | Le site expose-t-il des surfaces nativement orientées agents (llms.txt, WebMCP, MCP, accessibilité) ? |
A — Découverte · 14/100
Un agent peut-il trouver votre documentation à des URL prévisibles ?
La découvrabilité couvre tout ce qu’un agent trouve avant même de lire une page de documentation : un index /llms.txt à la racine du domaine, un agrégat plein texte /llms-full.txt, un robots.txt qui prend position explicitement sur les robots d’IA, un sitemap qui liste de vraies pages plutôt que des archives de tags, et des balises en page d’accueil pointant vers un jumeau markdown. C’est la catégorie la moins coûteuse — chaque artefact y est un fichier statique produit au build — et c’est celle qu’on laisse le plus souvent vide.
A1 · Un llms.txt à la racine du domaine conforme à la spec llmstxt.org
les agents (comme les humains qui découvrent un site) ont besoin d'un index unique et prévisible indiquant où se trouve la documentation. /llms.txt est la convention proposée par Anthropic et la communauté llmstxt.org : un seul fichier Markdown à la racine du domaine, contenant la carte de la documentation.
Notation. 2 = un H1 + ≥1 H2 + ≥3 liens + tous aboutissent · 1 = tout fichier comportant un H1 (rétrogradé depuis le niveau 2 si les liens n'aboutissent pas) · 0 = absent ou coquille HTML.
Correction. Publiez /llms.txt à la racine du domaine avec un titre `# H1`, des en-têtes de section `## H2`, et au moins trois liens Markdown à puces pointant vers des pages de documentation concrètes. Voir https://llmstxt.org pour la spec.
A2 · Présence d'un llms-full.txt ou d'agrégats LLM par section
/llms-full.txt est l'export en texte intégral de votre documentation en un seul endroit — les agents fondés sur de grands modèles de langage le préfèrent à l'exploration de 200 pages HTML. Les variantes par section (/llms-api.txt, etc.) conviennent aussi.
Notation. 3 = /llms-full.txt à la racine du domaine, >1 Ko · 2 = agrégat par section trouvé via llms.txt · 0 = ni l'un ni l'autre, ou coquille SPA à /llms-full.txt.
Correction. Générez /llms-full.txt au moment du build (des plugins mkdocs/docusaurus existent) et servez-le en text/plain. Gardez-le sous 100 Mo pour que les agents puissent le récupérer sans streaming.
A3 · robots.txt déclare une politique pour les bots d'IA et un Sitemap absolu
tout crawler d'IA (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot) lit /robots.txt avant d'explorer. Une directive Allow/Disallow explicite par UA, plus une directive `Sitemap:` absolue, lèvent toute ambiguïté sur l'indexation et sur ce qu'il faut indexer.
Notation. 3 = directive UA explicite pour un bot d'IA ET ligne Sitemap: absolue · 2 = directive bot d'IA seule · 1 = Sitemap absolu seul · 0 = ni l'un ni l'autre, ou 404.
Correction. Ajoutez `User-agent: GPTBot\nAllow: /` (ou Disallow selon votre politique) pour chaque grand bot LLM, plus une ligne `Sitemap: https://example.com/sitemap.xml`. La directive `Content-Signal:` de Cloudflare compte également.
A4 · sitemap.xml : bien formé, URL absolues, faible bruit de taxonomie
les sitemaps indiquent aux crawlers quoi indexer et à quelle fréquence cela change. Un `<urlset>` bien formé avec des URL `<loc>` absolues réparties sur de nombreuses pages distinctes signale une vraie couverture ; un stub avec une seule URL (ou un sitemap composé à 70 % et plus de bruit /tag/ /category/) n'apporte aucun signal.
Notation. 3 = bien formé + ≥3 chemins distincts + <30 % de bruit de taxonomie · 2 = maigre (<3 chemins) ou 30-70 % de bruit · 1 = bien formé seulement · 0 = 404 ou erreur d'analyse.
Correction. Générez /sitemap.xml au moment du build, incluez chaque page de documentation avec un `<loc>` en URL absolue, et excluez les variantes /tag/, /category/, /author/, /page=. Référencez-le depuis robots.txt avec une ligne `Sitemap:` absolue.
A5 · Balises de découverte en page d'accueil : alternative markdown + OpenGraph
les balises de découverte permettent aux agents de trouver la version markdown d'une page sans requête supplémentaire, et OpenGraph transforme les liens de documentation partagés en aperçus enrichis sur Slack/Discord/Twitter. Les deux témoignent d'une prise en compte des consommateurs machine.
Notation. 2 = `<link rel=alternate type=text/markdown>` + ≥3 propriétés `og:` distinctes · 1 = alternative markdown seule OU OpenGraph seul · 0 = ni l'un ni l'autre.
Correction. Ajoutez `<link rel="alternate" type="text/markdown" href="/page.md">` à côté de votre lien canonical, et assurez-vous que `og:title`, `og:description`, `og:image` (au minimum 3 propriétés) sont définis sur la page d'accueil.
B — Éléments de page · 21/100
Un parseur peut-il ingérer directement le contenu de chaque page ?
Les éléments de page déterminent si une page isolée peut être ingérée sans deviner : un compagnon markdown propre servi en .md ou via Accept: text/markdown, un JSON-LD qui s’analyse et déclare un type, une URL canonique absolue, une date de modification lisible par machine, et un élément main ou article qui marque où finit le contenu et où commence la navigation. Les agents dédoublonnent sur les canoniques et décident quoi recharger d’après les dates ; sans ces signaux, votre page n’est qu’un mur de div indifférencié.
B1 · Le compagnon .md des pages de documentation renvoie un markdown propre
parcourir 200 pages HTML pour lire votre documentation convient aux humains ; pour les agents, c'est un coût de tokenisation d'un ordre de grandeur supérieur. Un jumeau markdown par page permet aux agents de n'extraire que le texte.
Notation. 7 = 3/3 des pages échantillonnées ont un jumeau .md fonctionnel · 4 = 2/3 · 2 = 1/3 · 0 = 0/3.
Correction. Servez `{page}.md` (ou `{page}/index.md`) à côté de chaque page HTML, OU prenez en charge la négociation de contenu `Accept: text/markdown` renvoyant `Content-Type: text/markdown`. mkdocs-material et docusaurus disposent tous deux de plugins.
B2 · JSON-LD avec @type valide sur l'accueil et une page de documentation échantillon
le JSON-LD est la façon compatible schema.org de déclarer « cette page est un Article » / « ce produit est une SoftwareApplication ». Moteurs de recherche, agents et extracteurs de données structurées s'appuient tous dessus.
Notation. 4 = JSON-LD analysable avec `@type` à la fois sur l'accueil ET sur une page de documentation échantillon · 3 = l'un des deux · 0 = aucun.
Correction. Intégrez `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>` sur chaque page de documentation. Le type `WebApplication` convient bien à la page d'accueil.
B3 · Un <link rel=canonical> absolu sur l'accueil et une page échantillon
les liens canonical tranchent de manière déterministe la question « est-ce la version http ou https, avec ou sans slash final, avec ou sans paramètre de requête ? ». Sans eux, les agents peuvent indexer le même contenu sous plusieurs URL.
Notation. 3 = canonical absolu à la fois sur l'accueil ET sur une page échantillon · 2 = accueil seulement · 1 = présent mais relatif · 0 = absent.
Correction. Ajoutez `<link rel="canonical" href="https://example.com/page">` dans le `<head>` de chaque page. L'URL doit inclure le schéma et l'hôte (les canonical relatifs sont du HTML valide mais perdent leur intérêt pour les agents inter-hôtes).
B4 · Fraîcheur : dateModified (JSON-LD) ou en-tête Last-Modified
les agents (comme les moteurs de recherche) accordent moins de confiance à une documentation qui ne déclare pas sa dernière mise à jour. Une page de documentation de 2019 sans signal de fraîcheur est indiscernable d'une page mise à jour hier.
Notation. 2 = `dateModified` JSON-LD OU en-tête HTTP `Last-Modified` présent · 0 = ni l'un ni l'autre.
Correction. Incluez soit `"dateModified": "2026-05-28"` dans votre bloc JSON-LD, soit faites émettre un en-tête HTTP `Last-Modified` par votre CDN/serveur. Le templating au moment du build le fait gratuitement dans la plupart des générateurs de sites statiques.
B5 · Taxonomies lisibles par machine (mots-clés, tags, catégories)
une documentation taguée aide les agents à filtrer (« montre-moi les pages liées à l'authentification ») sans analyser tout le texte. `<meta name="keywords">`, le `keywords` JSON-LD, ou des URL de type `/tags/` comptent tous.
Notation. 2 = au moins un signal de taxonomie présent (meta keywords, keywords JSON-LD, ou motifs de liens /tags|/categories|/topics/) · 0 = aucun.
Correction. Ajoutez `<meta name="keywords" content="api,auth,oauth">` à chaque page, OU incluez un tableau `keywords` dans votre JSON-LD, OU organisez le contenu sous des préfixes d'URL `/topics/` ou `/tags/`.
B6 · Un <main> ou <article> englobe le texte du contenu principal
les conteneurs sémantiques HTML5 permettent aux agents (et aux lecteurs d'écran) d'écarter navigation/pied de page/barres latérales pour ne lire que le texte de la documentation. Une page dont le corps n'est que `<div>` impose des conjectures.
Notation. 2 = texte de `<main>` >200 caractères ET texte d'`<article>` >100 caractères · 1 = `<main>` seul OU `<article>` seul · 0 = ni l'un ni l'autre.
Correction. Englobez le texte principal de votre page dans `<main>` (ou `<article>` pour les pages de documentation individuelles). Évitez d'utiliser ces balises pour les barres latérales ou la navigation — elles sont destinées au contenu réel.
C — Contrat d'API · 17/100
Le contrat de l'API est-il publié sous forme de spécification lisible par une machine ?
La catégorie du contrat d’API pose une seule question : existe-t-il une spécification qu’un agent puisse trouver et à laquelle il puisse se fier. C1 est le critère le plus lourd de la grille, avec 8 points, répartis entre « le document est trouvé à une URL découvrable » et « c’est un OpenAPI 3.x valide, avec info, chemins et schémas de réponse ». La séparation est volontaire : un fichier qui existe sans décrire ce qui revient n’est qu’un demi-contrat. Une spécification valide vaut plus que n’importe quelle page de prose, car on peut en générer un client, une suite de tests et des définitions d’outils sans lire la documentation.
C1 · Spéc OpenAPI / Swagger / AsyncAPI — trouvée et valide
la spéc OpenAPI est LE contrat machine-lisible d'une API REST : un agent qui trouve une spéc VALIDE génère clients, tests et docs sans lire le HTML. v3 fusionne découverte et validité en un critère.
Notation. 8 = OpenAPI 3.x valide (info, ≥1 path, schémas de réponse sur ≥30% des opérations) · 3 = spéc trouvée à une URL joignable mais non valide 3.x (Swagger 2.0 inclus) · 0 = rien · error si la page d'accueil n'a pu être récupérée.
Correction. Publiez la spéc sur `/openapi.json` ou `/openapi.yaml` à la racine (ou via un lien RFC 9727 api-catalog `service-doc`). Passez-la en OpenAPI 3.x et donnez à chaque opération un schéma `responses` — c'est ce qui vaut les 8 points.
C2 · Collection Postman ou SDK avec téléchargement/fork découvrable
une spec OpenAPI permet aux agents de générer un client ; une collection Postman soignée ou un SDK prêt à l'emploi permet aux HUMAINS d'essayer l'API en 30 secondes. Les deux témoignent d'un investissement dans l'expérience développeur.
Notation. 4 = lien de collection Postman ET ≥1 lien vers un registre de SDK · 3 = Postman OU ≥2 liens de SDK · 2 = 1 lien de SDK · 0 = rien.
Correction. Publiez un bouton « Run in Postman » pointant vers god.gw.postman.com/run-collection, et liez au moins un SDK officiel depuis npm/PyPI/RubyGems/etc. directement depuis la page d'accueil de votre documentation.
C3 · Les pages d'endpoint montrent méthode, URL, types, champs requis, exemples
une page de documentation qui se contente de dire « appelez /users » est inutile sans la méthode, les types de paramètres, les champs requis et un exemple de requête/réponse. Les agents (comme les humains) ont besoin de ces cinq éléments pour faire un appel qui fonctionne.
Notation. 5 = la majorité des pages échantillonnées classées `complete` par le modèle de ML · 3 = majorité `partial` (ou 2 complete + 1 absent) · 1 = majorité `absent` · 0 = aucune page candidate trouvée.
Correction. Sur chaque page d'endpoint, incluez : méthode HTTP + chemin, un tableau de paramètres avec types et indicateurs « requis », un exemple curl, et un exemple de réponse JSON avec code de statut. Les tableaux de paramètres en style Markdown et les blocs JSON `<pre>` se classent proprement.
D — Contenu · 23/100
Chaque page d'endpoint fournit-elle assez de contexte pour être exploitée ?
Le contenu est la catégorie la plus lourde, et la seule qu’aucun fichier de configuration ne répare. On y vérifie si les pages d’endpoint portent des exemples exécutables dans plus d’un langage, si ces exemples emploient des valeurs qui ressemblent à de vraies données plutôt qu’à foo et example.com, si les erreurs sont cataloguées avec codes et causes, si l’authentification et les limites de débit sont documentées, et si un même concept porte partout le même nom. Les agents ancrent leurs réponses dans vos exemples ; un extrait bourré de valeurs bidon est recopié tel quel dans le code généré.
D1 · Les exemples de code incluent curl ET un SDK pour au moins un langage
les exemples curl sont testables universellement ; les exemples SDK montrent un usage idiomatique. Ensemble, ils répondent au besoin « puis-je essayer ça rapidement ? » et au besoin « comment intégrer ? ».
Notation. 4 = curl ET un bloc de code SDK dans un langage sur ≥1 page · 2 = curl seul · 1 = SDK seul · 0 = ni l'un ni l'autre.
Correction. Ajoutez un bloc de code à onglets par endpoint, avec au moins curl + le langage de SDK le plus utilisé (Python ou JavaScript). Utilisez `<code class="language-python">` ou `language-bash` pour que les outils de coloration syntaxique et notre classifieur le repèrent tous deux.
D2 · Exemples réalistes (pas de foo/bar/example.com)
`/users/{id}` avec `id = 1` et `email = [email protected]` oblige le lecteur à imaginer à quoi ressemblent de vraies données. Des placeholders réalistes (`[email protected]`, `org_2N5x...`) réduisent la friction et évitent les accidents de copier-coller depuis la documentation.
Notation. 4 = le modèle de ML estime que <20 % des blocs de code sont saturés de placeholders · 3 = 20-40 % · 2 = 40-60 % · 1 = 60-80 % · 0 = >80 % ou aucun bloc de code.
Correction. Remplacez `foo`/`bar`/`example.com`/`your_api_key`/`<string>` par des valeurs d'allure réaliste (le `pk_test_51N5...` de Stripe, le `+14155552671` de Twilio). N'utilisez pas de vraies données client — mais imitez-en la forme.
D3 · Catalogue d'erreurs avec codes HTTP + raisons
quand une intégration casse à 3 h du matin, le développeur a besoin de savoir ce que `403 - resource_not_owned` signifie réellement sans ouvrir un ticket. Une page de référence des erreurs dédiée fait la différence entre une correction en 5 minutes et un débogage d'une demi-heure.
Notation. 3 = page d'erreurs dédiée (≥3 codes avec explications) · 1 = codes d'erreur documentés au fil des pages · 0 = aucun.
Correction. Publiez `/errors` (ou `/reference/errors`) listant chaque statut HTTP que vous renvoyez + les codes d'erreur applicatifs + une cause en une phrase pour chacun. Les tableaux fonctionnent bien ; les listes de définitions `<dl>` aussi.
D4 · Authentification ET limites de débit documentées
l'authentification est un prérequis ; les limites de débit indiquent au développeur si son intégration survivra à la charge de production. Les deux ont leur place sur une page de documentation de premier niveau, découvrable depuis l'accueil.
Notation. 3 = authentification et limites de débit documentées · 2 = authentification seule · 1 = limites de débit seules · 0 = ni l'une ni l'autre.
Correction. Ajoutez des pages `/authentication` (flux bearer / clé API / OAuth) et `/rate-limits` (req/min, en-têtes comme `X-RateLimit-Remaining`, sémantique de réessai 429). Chacune doit comporter au moins 200 caractères de contexte — pas seulement un extrait de code.
D5 · Glossaire OU terminologie cohérente d'une page à l'autre
est-ce un « workspace », une « team » ou une « organisation » ? Choisir un terme et s'y tenir dans toute la documentation évite une catégorie de tickets de support « que veut dire X ici ? ». Un glossaire dédié est l'idéal ; un usage cohérent est acceptable.
Notation. 3 = un /glossary dédié avec ≥3 paires terme/définition structurées · 2 = pas de glossaire mais terminologie cohérente entre les pages (≥80 % de variante dominante) · 1 = lien de glossaire présent mais contenu maigre · 0 = ni l'un ni l'autre.
Correction. Publiez `/glossary` sous forme de `<dl>` avec des paires `<dt>terme</dt><dd>définition</dd>` (ou un tableau à 2 colonnes avec des définitions de ≥50 caractères). Utilisez la même casse/orthographe pour chaque terme sur toutes les pages.
D6 · Endpoints dépréciés / bêta signalés en clair
un développeur qui colle votre exemple de code de 2022 dans un projet de 2026 ne devrait pas découvrir à l'exécution que l'endpoint est déprécié. Des marqueurs `deprecated` / `beta` / `sunset` explicites dans la documentation épargnent bien des migrations douloureuses.
Notation. 2 = `deprecated` dans la spec OpenAPI OU dans ≥2 pages échantillons près des titres d'endpoint · 1 = mots-clés beta/experimental trouvés mais aucune dépréciation · 0 = aucun.
Correction. Marquez chaque endpoint déprécié avec `deprecated: true` dans OpenAPI ET un badge ou un encart visible dans la documentation HTML (le `<Warning>` de Mintlify, la syntaxe d'encart de Docusaurus, etc.). Idem pour les endpoints bêta — visibles dans le texte, pas seulement dans la spec.
E — Rendu et hygiène · 21/100
Le site est-il stable et utilisable sans JavaScript ?
Le rendu et l’hygiène décident si tout ce qui précède survit au contact d’un simple client HTTP. E1 est le critère verrou : si le contenu n’est pas dans le HTML qui arrive avant l’exécution du JavaScript, l’agent ne voit qu’une coquille d’application vide, aussi bonne la documentation soit-elle. Le reste de la catégorie couvre la stabilité des URL lors des déplacements, une version d’API explicite, des liens internes qui aboutissent vraiment, des conditions d’utilisation énoncées, et des contrôles portant des noms accessibles qu’un agent peut viser lorsqu’il actionne la page au lieu de la lire.
E1 · Contenu visible en HTML brut sans JavaScript (critère bloquant)
c'est le critère BLOQUANT. Si votre documentation ne s'affiche qu'après exécution de JavaScript (coquille de single-page-app), les agents qui récupèrent le HTML brut ne voient rien. Les web crawlers, les scrapers, curl et la plupart des récupérateurs d'IA n'exécutent pas le JS.
Notation. 6 = texte du corps >500 caractères sur au moins l'une des pages parmi l'accueil ou 2 sous-pages, dans les différents modes UA · 3 = l'accueil passe mais les sous-pages sont en SPA · 0 = coquille SPA partout, ou piège de coquille uniforme (3 URL et plus renvoient un corps identique).
Correction. Servez du HTML pré-rendu à des URL statiques. Si vous utilisez Next.js/Nuxt/SvelteKit, activez le SSG ou le SSR pour la section documentation. Les coquilles de single-page-app (SPA React, SPA Vue sans SSR) échouent à ce critère et font chuter en cascade beaucoup d'autres critères à zéro.
E2 · URL stables : les redirections 301 préservent les anciens chemins
quand vous réorganisez la documentation, les anciens liens ne devraient pas renvoyer 404 — ils devraient faire une 301 vers la nouvelle URL. Des URL stables permettent aux liens internes provenant de blogs, de Stack Overflow et de favoris de survivre à votre refonte.
Notation. 2 = redirection 301/308 stable sur ≥1 des 2 variantes d'URL échantillonnées · 1 = motif canonical-alias (200 avec `<link rel=canonical>`) · 0 = 302 (non permanente), 404, ou aucune redirection.
Correction. Quand vous changez l'URL d'une page de documentation, ajoutez une redirection 301 de l'ancien chemin vers le nouveau. Les générateurs de sites statiques gèrent cela via `_redirects` (Netlify) ou les `redirects:` de `vercel.json` (Vercel).
E3 · Version d'API explicite dans le chemin d'URL, un titre ou la spec OpenAPI
`/v1/users` contre `/v2/users` est la manière économique de versionner une API ET de la rendre évidente pour les agents. Une métadonnée de version uniquement présente dans un en-tête (et ni dans le chemin ni dans un titre de documentation) est invisible pour les crawlers.
Notation. 2 = version dans la structure d'URL propre à la doc (URL du sitemap ou de la spec OpenAPI : `/v1/`, `/2024-01-15/`) · 1 = version dans l'URL d'un endpoint documenté (exemples curl/code), dans `info.version` OpenAPI, ou dans un titre `<h1>`/`<h2>`/pied de page · 0 = aucune.
Correction. Préfixez vos chemins d'API par `/v1/`, `/v2/` et affichez-les dans vos exemples curl/code ; ou définissez un `info.version` non vide dans votre spec OpenAPI. Les API versionnées par date (`/2024-01-15/users`) comptent également.
E4 · Contrôle ponctuel de 5 liens internes → tous renvoient 200
les liens internes pourris sont le mode de défaillance le plus courant des documentations après des années de remaniements. Un contrôle ponctuel de 5 liens attrape les pires cas (4xx/5xx sur des liens présents en page d'accueil) sans tenter d'explorer chaque lien.
Notation. 2 = 5/5 des liens échantillonnés du même hôte renvoient 200 · 1 = 4/5 · 0 = ≤3/5, OU moins de 5 liens distincts du même hôte trouvés sur l'accueil.
Correction. Lancez un vérificateur de liens dans votre CI (lychee, htmltest, linkinator). Pour les liens les plus fréquentés de l'accueil, corrigez les 404 avant de livrer. Cinq liens fonctionnels depuis la page d'accueil est le strict minimum.
E5 · Conditions d'utilisation : CGU / licence / politique d'IA explicites
sans CGU ni politique d'usage par l'IA explicites, chaque scraper de LLM doit deviner votre position. Ajouter une page `/terms` ou `/license` substantielle — surtout une contenant des mots-clés IA/ML — rend la politique lisible par machine.
Notation. 2 = page de CGU trouvée ET contenant des mots-clés de politique IA/ML dans le contenu principal · 1 = CGU trouvées (substantielles mais sans mots-clés IA, ou lien présent mais page 404/maigre) · 0 = aucun lien de CGU.
Correction. Publiez `/terms` (ou `/legal`, `/license`) avec au moins 1000 caractères de texte de politique. Incluez un libellé explicite sur le scraping par l'IA, l'entraînement de modèles et l'accès automatisé — même si vous autorisez tout, le dire est déjà le signal.
E6 · Accessibilité agent : noms statiques + validité ARIA
un agent IA pilote une page via son arbre d'accessibilité : chaque bouton, lien, champ et image doit porter un nom ciblable. v3 replace ce critère de la catégorie F vers E à côté d'E1, car il évalue la page rendue, pas une surface de découverte.
Notation. 4 = 0 violation (et ≥1 élément à vérifier) · 2 = 1–2 · 1 = 3–5 · 0 = ≥6 · not_applicable si rien à nommer · error si la page n'a pu être scannée. Heuristique statique (sans axe-core/headless).
Correction. Donnez à chaque `<button>`/`<a>`/icône un nom accessible ; associez les `<label>` aux champs ; ajoutez `alt` aux images et `<title>` aux SVG inline ; supprimez les `tabindex` positifs ; corrigez les `aria-*` et rôles erronés.
F — Capacités d'agent · 4/100
Le site expose-t-il des surfaces nativement orientées agents (llms.txt, WebMCP, MCP, accessibilité) ?
Les capacités agent recensent les surfaces explicitement destinées aux agents : une surface d’outils WebMCP dans la page, déclarative ou scriptée, et un serveur MCP annoncé dont les métadonnées OAuth respectent les RFC 9728 et RFC 8414. La catégorie est délibérément petite — quatre points sur cent. Les deux spécifications sont jeunes et encore mouvantes, l’adoption hors d’une poignée de plateformes de documentation se compte en pourcentages à un chiffre, et taxer chaque site pour ne pas avoir livré un standard expérimental en dirait plus sur notre enthousiasme que sur leur documentation. Le poids augmentera quand l’adoption augmentera.
F2 · Surface d'outils WebMCP exposée aux agents du navigateur
WebMCP permet à une page d'exposer des outils appelables à un agent IA s'exécutant dans l'onglet — via un balisage déclaratif `<form toolname tooldescription>`, l'API impérative `navigator.modelContext`, ou un polyfill. F2 récompense toute surface détectée ; la vérification de schéma des formulaires déclaratifs alimente les diagnostics et ne change pas le point.
Notation. 1 = WebMCP détecté, 0 erreur de schéma + 0 avertissement · 1 = détecté avec des problèmes de schéma (erreurs ou avertissements) · 0 = non détecté · error si la page d'accueil n'a pas pu être analysée.
Correction. Ajoutez une surface d'outils WebMCP. La forme déclarative est la seule qu'un auditeur externe puisse vérifier depuis le HTML statique : annotez un `<form>` avec `toolname` + `tooldescription`, et donnez à chaque champ `name` + `toolparamdescription`. Corrigez d'abord les erreurs toolname manquant / paramètre requis sans name : ce sont les échecs durs.
F3 · Serveur MCP annoncé (OAuth RFC 9728 / 8414)
un serveur MCP permet aux agents d'appeler votre API comme des outils encadrés. F3 récompense l'annonce d'un endpoint MCP découvrable et protégé par OAuth via les métadonnées standard `.well-known`, pour qu'un agent puisse s'authentifier et se connecter sans configuration sur mesure.
Notation. 3 = oauth-mcp complet (protected-resource RFC 9728 + métadonnées de serveur d'autorisation RFC 8414 + PKCE S256) · 2 = partiel · 1 = endpoint seul · 0 = aucun · error si le site était injoignable.
Correction. Servez `/.well-known/oauth-protected-resource` pointant vers votre endpoint MCP, ainsi qu'un document de métadonnées de serveur d'autorisation RFC 8414 sur le même hôte, annonçant le PKCE `S256`.
Par où commencer
Sur les 5 827 sites du corpus public d’AgentFit, la note médiane est de 22 sur 100, un quart des sites reste sous 11 et seuls 19 % dépassent 40. Les points se perdent aux quatre mêmes endroits, classés ici par points gagnés par heure de travail :
- Pas de /llms.txt à la racine du domaine — 75,0 % des sites ont zéro sur A1, qui vaut 3 points. Un fichier généré, une étape de build. 57 % du corpus n’a ni llms.txt, ni llms-full.txt, ni politique pour les robots d’IA dans robots.txt : aucun point d’entrée déclaré pour un agent.
- robots.txt ne nomme aucun robot d’IA et ne porte aucune ligne Sitemap absolue — 65,8 % ont zéro sur A3, qui vaut 3 points. Cinq lignes de texte, dans le fichier que tout robot lit en premier.
- Pas de compagnon markdown pour les pages de documentation — 77,9 % des sites où la vérification a pu être menée ont zéro sur B1, qui vaut 5 points. La plupart des générateurs de sites statiques détiennent déjà le markdown source : le travail est du routage, pas de la rédaction.
- Pas de spécification valide et découvrable — 96,4 % ont zéro sur C1, qui vaut 8 points. La plus grosse perte du tableau, et la seule des quatre qui relève d’un vrai travail d’ingénierie plutôt que de configuration.
L’ordre compte plus que la liste. Neuf critères — llms.txt, llms-full.txt, robots, sitemap, balises de découverte en page d’accueil, JSON-LD, canonique, date de modification, taxonomies — pèsent 27 points à eux seuls et n’exigent de réécrire aucune ligne de documentation ; le site moyen n’en récolte que 8,5, soit dix-huit points laissés sur la table. C1 et le catalogue d’erreurs en D représentent des semaines de travail : cela se planifie, cela ne se glisse pas entre deux tâches. Une mise en garde sur la causalité : les sites dotés d’un llms.txt ont une médiane de 41 contre 18 pour les autres, mais le fichier ne rapporte pas 23 points. La flèche va plutôt dans l’autre sens : les équipes qui entretiennent leur documentation sont celles qui ajoutent le fichier. Le balisage est un moyen bon marché de récolter des points, pas un moyen de rendre la documentation bonne.
Tous les chiffres de cette section sont un instantané figé : 5 827 domaines disposant d’une exécution valide sous la grille v3, relevé le 27 juillet 2026, une exécution par domaine, hors domaines appartenant à AgentFit. Les graphiques plus haut sur cette page proviennent du corpus vivant sous la grille ACTUELLE, repondérée depuis cet instantané — les deux séries de chiffres n’ont pas à concorder, et là où elles diffèrent, ce sont les graphiques qui font foi. Ce sont des URL soumises par les internautes eux-mêmes, et non une liste choisie de documentations d’API : la médiane décrit donc ce qui a été soumis, pas le marché.
Questions fréquentes
Qu’est-ce que llms.txt, et m’en faut-il vraiment un ?
C’est un fichier Markdown à la racine de votre domaine qui indexe votre documentation : un titre H1, des en-têtes de section et des liens vers les pages qui comptent, au format proposé sur llmstxt.org. Aucun robot n’est tenu de le lire, et AgentFit ne prétend pas qu’il s’agit d’un standard. S’il est noté, c’est parce qu’il coûte une étape de build et qu’il est le seul endroit où c’est vous, et non les heuristiques d’un robot, qui décidez de ce qui constitue votre documentation. Son compagnon /llms-full.txt applique la même idée au texte intégral.
Faut-il un serveur MCP pour obtenir une bonne note ?
Non. Toute la catégorie des capacités agent pèse 4 points sur 100 : un site sans serveur MCP ni WebMCP peut dépasser 90. La catégorie existe pour enregistrer qui construit des surfaces destinées aux agents, pas pour pénaliser qui n’en construit pas. Si vous exploitez un serveur MCP, F3 vérifie qu’il s’annonce comme la spécification l’attend : métadonnées de ressource protégée selon la RFC 9728, document de serveur d’autorisation selon la RFC 8414, et PKCE en S256.
En quoi est-ce différent de Lighthouse ou d’un audit SEO ?
Le lecteur n’est pas le même. Lighthouse mesure l’expérience d’un humain dans un navigateur : temps de peinture, décalages de mise en page, accessibilité de la page rendue. Un audit SEO mesure l’adéquation à un index de recherche et à ses signaux de classement. AgentFit mesure si un programme qui n’exécute pas votre JavaScript et ne fait pas défiler la page peut récupérer le contrat de votre API. Les recoupements sont réels — rendu sans JS, URL canoniques, données structurées apparaissent dans les trois — mais les modes de défaillance divergent, et un score Lighthouse parfait est parfaitement compatible avec une documentation qu’un agent ne peut pas exploiter.
Pourquoi aucun modèle de langage n’intervient dans la notation ?
Parce qu’une note qu’on ne peut pas reproduire n’est pas une mesure. Chaque vérification est une requête HTTP plus un analyseur ou une règle : le même site obtient deux fois le même résultat, et chaque point s’accompagne d’une URL et d’un extrait que vous pouvez vérifier vous-même. Deux petits classifieurs assistent deux critères ; ils sont compilés dans le binaire et versionnés avec lui, de sorte que le réentraînement de quelqu’un d’autre ne déplacera pas votre note du jour au lendemain. Conséquences pratiques : un audit complet prend une trentaine de secondes, ne coûte rien à lancer et peut être vérifié par un sceptique.
À quelle fréquence relancer l’audit ?
Après tout changement dans la façon dont la documentation est construite ou servie, et une fois par mois le reste du temps. Une note ne bouge que si un fait bouge : des exécutions quotidiennes mesureraient surtout le bruit de votre CDN. Comparez deux exécutions dans la vue diff ; si la version de la grille a changé entre les deux, la comparaison est refusée plutôt que de faire passer notre changement d’étalon pour votre régression.
Ma note est basse. Qu’est-ce que cela m’apprend ?
En général, pas que la documentation soit mauvaise pour les humains. La forme la plus courante d’une note basse, c’est un site bien écrit livré comme une application JavaScript sans aucune surface machine : l’agent reçoit une coquille vide, pas de jumeau markdown, pas de spécification, et tout le reste s’effondre avec. Lisez le rapport en partant de la liste de correctifs : elle est classée par points gagnés par unité d’effort, et chaque entrée nomme l’URL récupérée, de sorte que vous pouvez reproduire le constat avant de planifier le travail.
Une bonne note fera-t-elle citer ma documentation par ChatGPT ?
Personne ne peut le promettre, et cet outil ne le promet pas. Ce qu’une bonne note signifie est plus étroit et vérifiable : un agent qui atteint votre site peut le récupérer, l’analyser et le citer sans navigateur. Qu’un moteur de réponse vous cite ensuite dépend aussi de la politique de son robot, de la fréquence des questions sur votre produit et de mécanismes de classement qu’aucun fournisseur ne publie. AgentFit mesure la part qui dépend de vous.
Puis-je appliquer la grille moi-même ?
Oui — à la main. La spécification complète est sur cette page, critère par critère ; le même contenu est servi en Markdown à cette URL avec l’en-tête Accept: text/markdown, et le schéma du rapport figure dans le document OpenAPI public. Ce que vous ne pouvez pas faire, c’est exécuter notre implémentation : les sources sont privées et nous ne publions aucune compilation. Ce que vous pouvez faire en revanche, c’est nous demander des comptes — /reproducibility publie trois rapports bruts et les commandes exactes pour les comparer, champ par champ, à une exécution en direct du même site. Tous les sites déjà audités sont consultables : vous pouvez donc vous comparer à un pair avant de commencer.
Auditer votre documentation · Parcourir les sites audités · Vérifier un serveur MCP