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. 2 = début vérifié d’un agrégat complet (>1 Ko au total, ou ≥256 octets si la taille totale est inconnue) · 1 = agrégat court ou par section vérifié · 0 = recherche limitée sans résultat · erreur si le début du fichier ou une entrée requise n’a pas pu être observé.
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. 5 = copie Markdown pour chaque page désignée (trois au maximum) · 3 = deux sur trois · 1 = une sur deux ou trois · 0 = aucune. Les pages indisponibles restent dans l’échantillon.
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 · Date interprétable : dateModified ou Last-Modified
les métadonnées de date permettent aux clients de lire la date déclarée d’un document. Elles ne prouvent ni son actualité éditoriale ni la date réelle de modification du contenu.
Notation. 4 = date interprétable, hors date d’époque, dans une réponse exploitable · 0 = toutes les sources de métadonnées prévues ont été observées sans date valide · erreur si une source requise est indisponible.
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 chemin, schémas de réponse pour ≥30% des opérations) · 3 = spécification accessible trouvée mais non valide en 3.x (Swagger 2.0 inclus) · 0 = aucun contrat trouvé dans la recherche bornée achevée · erreur si les vérifications requises restent inconclusives.
Correction. Publiez OpenAPI 3.x à `/openapi.json` ou `/openapi.yaml`, ou liez directement le contrat depuis l’accueil de la documentation. Jusqu’à quatre liens visibles distincts sont vérifiés dans leur ordre : un guide ou Swagger UI ne masque pas le contrat suivant. Ajoutez les schémas de réponse. api-catalog reste diagnostique.
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. 7 = la majorité des pages échantillonnées classées `complete` par le modèle de ML · 4 = majorité `partial` (ou 2 complete + 1 absent) · 1 = majorité `absent` · 0 = aucune page candidate trouvée.
Correction. Décrivez les paramètres nommés avec types et explications sous Parameters, Request body ou Arguments. Tableaux, listes de définitions, listes et composants ou paragraphes sont pris en charge. Ajoutez méthode HTTP, chemin, requête et réponse JSON avec statut. Le modèle sous-évalue encore les pages compactes.
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 ou une section nommée de référence des erreurs fait la différence entre une correction en 5 minutes et un débogage d'une demi-heure.
Notation. 5 = page ou section nommée d’erreurs (≥3 codes distincts expliqués) · 2 = codes documentés au fil du texte · 0 = aucun.
Correction. Publiez `/errors` (ou `/reference/errors`) ou une section nommée 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. 4 = ≥3 définitions structurées dans un glossaire · 3 = ≥3 groupes de termes répétés et ≥20 occurrences, avec une graphie dominante à ≥80 % dans ≥75 % des groupes · 1 = glossaire déclaré dont la page est confirmée mais peu fournie · 0 = recherche négative terminée ; des entrées indisponibles empêchent une évaluation complète.
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 statique observé par AgentFitBot
les agents ont besoin du contenu de la documentation dans la réponse statique. Ce contrôle mesure ce qu’AgentFitBot reçoit réellement ; une réponse indisponible ou une page courte ne prouve pas à elle seule que JavaScript est nécessaire.
Notation. 6 = page d’accueil statique exploitable et deux sous-pages distinctes exploitables · 3 = page d’accueil exploitable avec moins de sous-pages répondant au critère · 0 = contenu statique mesuré insuffisant · erreur = entrée prévue indisponible.
Correction. Servez du HTML prérendu à des URL statiques. Avec Next.js, Nuxt ou SvelteKit, activez SSG ou SSR pour la documentation. Un contenu statique court et un échec de récupération sont signalés séparément ; aucun ne prouve à lui seul que JavaScript est nécessaire.
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 vers l’URL désignée pour au moins une des deux variantes au maximum · 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 · Vérification de 5 liens internes → documents accessibles
Cinq liens choisis selon une règle fixe vérifient la navigation depuis la page d’accueil. Un refus ou une réponse incomplète reste non observé et ne prouve pas un lien cassé.
Notation. 4 = cinq liens valides · 2 = quatre · 0 = au plus trois. Les cinq résultats doivent être observés ; moins de cinq liens admissibles rend le contrôle non applicable.
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. 3 = document de conditions d’utilisation confirmé de >1000 caractères Unicode contenant des mots-clés IA/ML · 2 = page de destination confirmée ou lien déclaré vers les conditions · 0 = recherche négative terminée ; un contenu illisible laisse les niveaux inférieurs partiellement inobservés.
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