Optimisation pour les moteurs agentiques (AEO)

• La manière dont les agents de codage IA consomment la documentation est fondamentalement différente de celle des humains. Une optimisation centrée uniquement sur l’humain laisse donc disparaître, hors des outils d’analyse, une part croissante du trafic IA
• Les agents récupèrent les documents via une seule requête HTTP, comptent les tokens, puis les écartent silencieusement s’ils ne tiennent pas dans la fenêtre de contexte. Les métriques d’analyse classiques comme la profondeur de scroll, le temps passé ou les clics ne sont donc tout simplement pas enregistrées
• Pour répondre à cela, le concept d’Agentic Engine Optimization (AEO) est proposé afin de structurer, formater et servir la documentation de façon réellement exploitable par les agents
• Le cœur de l’AEO repose sur la découvrabilité, la facilité de parsing, l’efficacité en tokens, la signalisation des capacités et le contrôle d’accès. Si un seul de ces points échoue, l’agent peut ignorer le contenu ou produire une sortie erronée
• Les équipes qui s’y mettent tôt obtiennent un avantage pour faire recommander et intégrer leur propre API par les agents, et une documentation pensée pour les agents finit aussi par produire de meilleurs documents pour les lecteurs humains

---

Qu’est-ce que l’AEO ?

• Agentic Engine Optimization (AEO) est une pratique consistant à structurer, formater et fournir du contenu technique afin que les agents de codage IA puissent réellement l’utiliser
• Là où le SEO optimisait pour les crawlers de recherche et les schémas de clics humains, l’AEO vise un nouveau consommateur : des agents IA capables de récupérer, parser et raisonner sur du contenu de manière autonome
• Éléments clés à prendre en compte
  • Discoverability – L’agent peut-il trouver la documentation sans rendu JavaScript ?
  • Parsability – Est-elle lisible par machine sans interprétation d’une mise en page visuelle ?
  • Token efficiency – Tient-elle dans une fenêtre de contexte d’agent typique sans être tronquée ?
  • Capability signaling – L’API indique-t-elle non pas « comment l’appeler », mais « ce qu’elle fait » ?
  • Access control – robots.txt autorise-t-il réellement le trafic IA ?

Comment les agents lisent la documentation

• Schéma humain : arrivée sur la page d’accueil de la documentation, navigation entre sections, lecture rapide des titres, exécution d’exemples de code, passage par 2 à 3 liens internes, 4 à 8 minutes par session → tout cela est enregistré par l’analytics
• Schéma agentique : selon un article qui analyse le trafic HTTP de 9 grands agents de codage comme Claude Code, Cursor, Cline, Aider, VS Code ou Junie, une exploration de plusieurs pages est compressée en 1 à 2 requêtes HTTP
  • Réception de la page entière via une seule requête GET, puis progression à partir de là : la notion de « user journey » s’effondre en un seul événement côté serveur
  • La profondeur de scroll, le temps passé, les clics sur les boutons, la complétion de tutoriels, les transitions de liens, les interactions de formulaires et l’ensemble des événements côté client deviennent invisibles

Les empreintes du trafic IA

• Il existe dans les logs serveur des signatures propres permettant d’identifier le trafic des agents
  • Aider : Headless Chromium (Playwright), GET à la demande, user-agent complet Mozilla/Safari
  • Claude Code : Node.js/Axios, GET à la demande, axios/1.8.4
  • Cline : curl, balayage GET + OpenAPI/Swagger, curl/8.4.0
  • Cursor : Node.js/got, sonde HEAD → GET, got (sindresorhus/got)
  • Junie : curl, GET séquentiels sur plusieurs pages, curl/8.4.0
  • OpenCode : Headless Chromium (Playwright), GET à la demande
  • VS Code : Electron/Chromium, style Chromium avec marqueur Electron
  • Windsurf : Go/Colly, colly
• Au-delà des agents de codage, des services web d’assistants IA comme ChatGPT, Claude, Google Gemini et Perplexity déclenchent eux aussi des fetchs côté serveur lorsque des utilisateurs partagent une URL, avec leurs propres empreintes

Le problème des tokens : la documentation peut être invisible pour les agents

• Les agents ont dans la pratique une limite de 100K à 200K tokens, et la gestion du contexte reste une contrainte active dans toutes les tâches
• Exemple cité dans l’article : le Cisco Secure Firewall Management Center REST API Quick Start Guide (Version 10.0) représente 193 217 tokens et environ 718 000 caractères, ce qui suffit à lui seul à saturer ou dépasser la fenêtre de contexte disponible de la plupart des agents
• Quand la documentation est trop longue, plusieurs situations peuvent se produire
  • Troncature silencieuse avec perte d’informations importantes
  • Préférence pour un document plus court, donc abandon de cette page
  • Tentatives de chunking, avec plus de latence et une surface d’erreur accrue
  • Retour à la connaissance paramétrique — autrement dit, génération d’hallucinations
• Conclusion : le nombre de tokens devient désormais une métrique de premier ordre pour la documentation, et il faut le suivre page par page

Objectifs pratiques de tokens

• Pages Quick start / getting started : moins de 15 000 tokens
• Pages de référence API individuelles : moins de 25 000 tokens
• Référence API complète : faire le chunking par ressource/endpoint plutôt que par produit
• Guides conceptuels : moins de 20 000 tokens, avec les détails reliés par des liens plutôt qu’embarqué directement

La pile AEO : ce qu’il faut réellement mettre en place

• L’AEO n’est pas une technique unique, mais un ensemble de signaux et de standards empilés en couches, depuis les fondations jusqu’à la surface

Layer 1: contrôle d’accès (robots.txt)

• Beaucoup d’agents vérifient d’abord robots.txt avant de récupérer du contenu. Une mauvaise configuration peut donc bloquer silencieusement l’accès à la documentation sans générer d’erreur
• Étapes d’exécution
  • Auditer les blocages involontaires visant les user-agents d’agents IA
  • Étudier des autorisations explicites pour des schémas connus comme les crawlers d’Anthropic, OpenAI, Google ou Perplexity
  • Si un contrôle plus fin est nécessaire, utiliser agent-permissions.json (spécification émergente déclarant les interactions automatiques autorisées, les rate limits, les endpoints API privilégiés, etc.)

Layer 2: llms.txt pour la découverte

• Fichier texte plat au format Markdown hébergé sur yourdomain.com/llms.txt, il sert de sitemap pour les agents IA
• Il fournit un répertoire structuré de la documentation et des descriptions, permettant aux agents d’identifier le contenu pertinent sans crawler tout le site
• Exemple de structure : Getting Started (Quick Start Guide, Authentication, Core Concepts), API Reference (REST API Overview, Users API 12K tokens, Events API 8K tokens), MCP Integration (MCP Server)
• Caractéristiques d’un bon llms.txt
  • Des descriptions qui indiquent ce qu’on peut y trouver, et pas seulement le nom des pages
  • Le nombre de tokens par page lorsque c’est utile
  • Une organisation par tâche plutôt que par hiérarchie produit
  • Une taille totale inférieure à 5 000 tokens (l’index ne doit pas dépasser le budget)

Layer 3: signalisation des capacités via skill.md

• Si llms.txt indique « où cela se trouve », skill.md indique ce que le produit peut faire
• Il permet de mapper déclarativement l’intention vers des endpoints et des ressources, sans obliger l’agent à inférer les capacités depuis de la prose
• Exemple de structure pour un service d’authentification
  • What I can accomplish : authentification OAuth 2.0 (authorization code, client credentials, PKCE), émission et validation de tokens JWT, gestion de sessions et rotation de refresh tokens, intégration SSO (SAML, OIDC)
  • Required inputs : Client ID/Secret, Redirect URI préenregistrée, scopes demandés (read:user, write:data, admin)
  • Constraints : 1000 requêtes de token par minute et par application, access token d’1 heure, refresh token de 30 jours, PKCE obligatoire pour les clients publics
  • Key documentation : OAuth 2.0 Guide, Token Reference, Postman Collection
• L’agent peut ainsi déterminer si l’API peut satisfaire l’intention de l’utilisateur avant de dépenser du budget de contexte à lire toute la documentation

Layer 4: format du contenu pour le parsing par les agents

• Fournir du Markdown, pas seulement du HTML — permettre l’accès au Markdown source via l’ajout de .md à l’URL ou un paramètre de requête réduit fortement le surcoût en tokens en supprimant tags, navigation et footer
• Structurer pour le scan plutôt que pour la lecture
  • Hiérarchie de titres cohérente (H1 → H2 → H3, sans saut)
  • Chaque section doit commencer par un résultat plutôt qu’un contexte général
  • Les exemples de code doivent être placés juste après l’explication
  • Les références de paramètres doivent utiliser des tableaux, plus compacts que des listes en prose
• Supprimer le bruit de navigation comme les sidebars, breadcrumbs ou liens de footer
• Dans les 500 premiers tokens de chaque page, répondre à « qu’est-ce que c’est ? », « que peut-on faire avec ? » et « de quoi a-t-on besoin pour démarrer ? »

Layer 5: exposition des tokens

• Exposer le nombre de tokens dans l’index llms.txt et sur les pages elles-mêmes (dans les métadonnées ou l’en-tête de page)
• Exemples de raisonnement d’agent
  • « Cette page fait 8K tokens — je peux l’inclure entièrement dans le contexte »
  • « Cette page fait 150K tokens — je dois n’en récupérer que les sections pertinentes »
  • « La fenêtre de contexte est dépassée — utiliser le résumé de llms.txt »
• Côté implémentation, il est suggéré de compter les caractères côté serveur puis de diviser approximativement par 4, avec exposition via meta tags ou en-têtes HTTP de réponse

Layer 6: « Copy for AI »

• Quand un développeur veut inclure de la documentation comme contexte dans un assistant IA intégré à son IDE, copier le HTML rendu emporte aussi le bruit de navigation et de footer
• Un bouton « Copy for AI » qui copie du Markdown propre dans le presse-papiers améliore de manière significative la qualité du contexte reçu par l’agent
• Anthropic, Cloudflare et d’autres ont déjà lancé des variantes de cette idée : faible coût, signal fort

AGENTS.md : le standard de base émergent

• De la même manière que README.md était le point d’entrée des développeurs humains dans un dépôt, AGENTS.md est en train de devenir le point d’entrée des agents IA
• Lorsqu’ils ouvrent un projet, les agents de codage cherchent AGENTS.md à la racine du répertoire et s’en servent ensuite comme instruction pour toutes les tâches
• Ce qu’un bon AGENTS.md doit contenir
  • Structure du projet et emplacement des fichiers importants
  • Liens directs vers la documentation des API/services concernés
  • Sandboxes de développement et environnements de test disponibles
  • Rate limits et contraintes que l’agent doit connaître
  • Patterns et conventions préférés dans la codebase
  • Lien vers un serveur MCP lorsque disponible
• Cisco DevNet l’a adopté comme fichier par défaut dans ses templates GitHub open source : lors de la création d’un nouveau projet, un AGENTS.md spécifique est prérempli avec les liens vers la documentation OpenAPI, les sandboxes DevNet et l’environnement de test

Surveiller le trafic de recommandation IA

• Ce qu’on peut faire dès maintenant : commencer à suivre le trafic de referral IA dans ses outils d’analyse
• Sources de referral à surveiller : labs.perplexity.ai/referral, chatgpt.com/(none), chatgpt.com/organic, link.edgepilot.com/referral, platform.openai.com/referral, perplexity/(not set), claude.ai/referral, copilot.microsoft.com/referral, gemini.google.com/referral
• Le trafic direct d’agents arrivant sans referer peut être capté via les empreintes HTTP évoquées plus haut (axios/1.8.4, curl/8.4.0, got (sindresorhus/got), colly)
• Construire un segment dédié au trafic IA fournit un indicateur avancé pour juger l’effet réel du travail AEO

Implications plus larges pour l’expérience développeur

• Jusqu’ici, les portails développeurs étaient conçus autour de la progressive disclosure, de la hiérarchie visuelle, des exemples interactifs et des tutoriels guidés, donc des schémas cognitifs humains
• Dans un monde centré sur les agents, certaines hypothèses se cassent
  • La hiérarchie visuelle perd son sens — les agents lisent le texte, pas la mise en page
  • La progressive disclosure devient un obstacle — les agents veulent tout d’un coup
  • Les exemples interactifs perdent de leur valeur — sans équivalent statique/API, ils deviennent inutiles
  • Le user journey s’effondre — un tutoriel multipage devient un unique chargement de contexte
• Cela ne signifie pas la disparition du design centré humain, mais les humains liront eux aussi de plus en plus la documentation dans le contexte d’assistants IA
• La meilleure documentation de demain devra être facile à parcourir et bien structurée pour les humains, lisible par machine et efficace en tokens pour les agents

Checklist d’audit AEO

Discovery

• Présence d’un llms.txt à la racine avec un index structuré de la documentation
• robots.txt ne bloque pas involontairement des user-agents d’agents IA connus
• agent-permissions.json définit les règles d’accès des clients automatisés
• Présence d’un AGENTS.md reliant la documentation pertinente dans le dépôt de code

Content structure

• Les pages de documentation sont servies en Markdown propre, et non en HTML rendu
• Chaque page place une formulation claire du résultat visé dans les 200 premiers mots
• Les titres sont cohérents et hiérarchiquement corrects
• Les exemples de code sont positionnés juste après l’explication en prose
• Les références de paramètres utilisent des tableaux au lieu de prose imbriquée

Token economics

• Le nombre de tokens est suivi pour chaque page de documentation
• Aucune page unique ne dépasse 30 000 tokens sans stratégie de chunking
• Le nombre de tokens des pages importantes est exposé dans llms.txt
• Le nombre de tokens est fourni dans les métadonnées de page (meta tags ou en-têtes HTTP)

Capability signaling

• Un fichier skill.md décrit les capacités de chaque service/API, et non leur mode d’appel
• Chaque skill contient capabilities, required inputs, constraints et key doc links
• Lorsqu’approprié, un serveur MCP est proposé pour une intégration directe par les agents

Analytics

• Les sources de referral IA sont segmentées dans l’analytics web
• Les logs serveur sont surveillés pour détecter les empreintes HTTP d’agents IA connus
• Une base de référence du ratio trafic IA / trafic humain est définie

UX bridge

• Un bouton « Copy for AI » est disponible sur les pages de documentation
• Le Markdown source est accessible via une convention d’URL (par ex. ajout de .md)

Tooling

• L’auteur a publié agentic-seo, un outil d’audit léger qui scanne llms.txt, les blocages d’agents dans robots.txt, le nombre de tokens, la disponibilité du Markdown, etc. — une sorte de Lighthouse pour la préparation aux agents

Par où commencer

• Ordre recommandé
  1. Audit de robots.txt — 10 minutes de travail pour éviter un verrouillage silencieux des agents
  2. Ajout de llms.txt — quelques heures de travail pour améliorer immédiatement la découvrabilité
  3. Mesurer et exposer le nombre de tokens — projet de week-end, fort effet de levier
  4. Rédiger skill.md pour les 3 API principales — en commençant par celles que les agents consulteront le plus
  5. Ajouter un bouton « Copy for AI » — faible coût, signal fort
  6. Mettre en place le monitoring du trafic IA — pour obtenir les données justifiant le reste du travail

Conclusion

• De la même manière que le SEO a enseigné qu’« un excellent contenu ne suffit pas : il faut le rendre découvrable selon les schémas réels de trafic de son époque », l’AEO applique la même leçon à un nouveau type de consommateur
• Les agents de codage IA représentent déjà une part importante et croissante du trafic de documentation, et ils se comportent de manière fondamentalement différente des lecteurs humains
• Les équipes qui réagissent tôt obtiennent l’avantage de voir leur API recommandée, intégrée avec succès et réutilisée par les agents
• Les équipes qui n’agissent pas s’exposent à un mode de défaillance silencieux, difficile à déboguer, où l’écart entre la qualité apparente de la documentation et le taux réel de réussite des tâches exécutées par les agents se creuse
• Concevoir pour les agents produit au final une meilleure documentation pour les humains aussi, les deux domaines se recouvrant bien plus qu’ils ne divergent