Présentation

L’API Agents d’OpenAI regroupe plusieurs modèles d’inférence et des primitives de contrôle de flux. La page d’accueil indique que l’index complet des documents se trouve dans le fichier llms.txt. Ce fichier liste les points d’entrée, les versions de modèle et les paramètres acceptés. L’existence d’un index texte unique simplifie la recherche automatisée via scripts, mais ne fournit aucune description détaillée des endpoints.

Accès à la documentation

OpenAI expose chaque page de la documentation sous forme de fichier Markdown. La règle décrite est simple : ajouter l’extension .md à l’URL d’une page HTML renvoie le même contenu au format texte brut. Par exemple :

https://developers.openai.com/api/docs/agents-api/overview.md

Cette conversion permet aux outils de parsing de récupérer directement les sections, les blocs de code et les tables sans passer par le rendu HTML. Le format Markdown conserve les balises de code, les titres et les listes, ce qui facilite l’intégration dans les IDE ou les générateurs de SDK.

Structure des fichiers

Le fichier llms.txt se présente comme une liste linéaire d’URL, chacune pointant vers un endpoint ou un guide. Chaque ligne suit le schéma https://developers.openai.com/api/docs/…. Aucun métadonnées supplémentaires (date, version) ne sont incluses, ce qui oblige les développeurs à croiser les informations avec les en‑têtes HTTP ou les balises <meta> des pages HTML. Le format texte brut ne supporte pas la hiérarchie explicite des sections, ce qui peut compliquer la génération d’une table des matières automatisée.

Considérations pour les développeurs

Le double format (HTML + Markdown) offre une flexibilité d’accès mais impose une double maintenance. Toute mise à jour du contenu doit être répercutée dans les deux représentations, sinon les versions peuvent diverger. De plus, l’absence de versionnage explicite dans llms.txt rend difficile la détection de changements de contrat d’API. Les équipes doivent implémenter un mécanisme de comparaison de hachage ou de date de modification HTTP pour garantir la cohérence.

En pratique, les pipelines CI/CD qui génèrent des clients SDK peuvent récupérer le fichier llms.txt, télécharger chaque .md, extraire les signatures de fonction et produire du code typé. Cette approche repose sur la stabilité du format Markdown : les blocs de code doivent rester entourés de triples backticks, les paramètres doivent être listés sous forme de tableaux. Toute rupture du format entraînera des erreurs de génération.

Enfin, la disponibilité du fichier texte unique facilite l’audit de conformité. Les équipes de sécurité peuvent scanner llms.txt à la recherche de points d’accès non documentés ou de paramètres sensibles. Cependant, sans métadonnées de version, l’audit doit être répété à chaque déploiement de la documentation pour rester fiable.