J'ai créé un Agent d'IA qui vous permet d'explorer les API en langage courant

Mon produit actuel possède des centaines d'APIs. Chaque fois que j'ai besoin de consulter la spécification de l'API, je dois naviguer vers le lien Swagger, faire défiler sans fin ou utiliser la recherche du navigateur pour trouver ce dont j'ai besoin—puis filtrer manuellement les résultats. C'est frustrant et douloureusement lent. Pire encore, chaque développeur qui doit intégrer l'API doit passer par la même expérience.

Cette frustration m'a amené à explorer comment l'IA pourrait améliorer ce processus. Cet article est une plongée profonde dans ce voyage et comment il a évolué vers quelque chose de simple, robuste et efficace.

Préparation

Documentation API riche

Comme première étape, j'ai examiné l'ensemble de la documentation de l'API pour m'assurer qu'elle contient des résumés clairs et des descriptions détaillées dans les documents Swagger. C'est une étape cruciale pour une meilleure découvrabilité dans les phases ultérieures. J'ai également veillé à ce que le résumé et la description soient uniques pour chaque API.

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Catégorisation des APIs

Avec des centaines d'APIs disponibles, il peut être difficile d'identifier celles qui sont liées. Catégoriser les APIs rend la gestion plus efficace et simplifie ultérieurement la sélection de la bonne API basée sur une entrée en langage naturel. Cette catégorisation a été mise en œuvre en utilisant le concept de balisage défini dans la spécification OpenAPI.

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Construction d'une recherche en langage naturel

Entrée utilisateur

Les utilisateurs saisiraient la question en langage naturel liée à l'API.

Exemple : Comment récupérer les détails d'un compte ?

Classifier la catégorie

À ce stade, la question et toutes les catégories disponibles sont envoyées au LLM. Le LLM est chargé de renvoyer la catégorie de haut niveau dans laquelle s'inscrit la question. Le résultat de cette étape est l'une des catégories.

Classifier l'API spécifique

Sur la base de la catégorie identifiée par le LLM, le système envoie une autre requête au modèle avec la même question — mais cette fois, il inclut tous les détails de l'API dans cette catégorie spécifique détectée à l'étape précédente.

C'est là que la préparation antérieure porte ses fruits : plus la documentation de l'API est descriptive et bien structurée, meilleurs sont les résultats. Des descriptions claires aident le LLM à déterminer avec précision quelle API l'utilisateur demande.

Le résultat de cette étape est une API unique et spécifique.

Enrichir les détails de réponse de l'API

La spécification OpenAPI de l'API est ensuite fournie au LLM pour générer une description détaillée et riche en contexte de l'API avec la question originale.

Par exemple, si l'utilisateur demande, "Comment puis-je récupérer les détails d'un compte en utilisant un ID de compte ?", la réponse inclura les détails de spécification pertinents de l'API de compte.

Extension

Avec la capacité améliorée du système à détecter avec précision l'API appropriée, les utilisateurs peuvent maintenant aller plus loin — générer des extraits de code pour interagir directement avec diverses APIs.

Par exemple :

• "Partagez du code Python pour appeler l'API Get Account Details pour un ID donné."

• "Fournissez une commande cURL pour récupérer les détails du compte par ID."

• "Générez un client Go pour récupérer les détails du compte pour un ID spécifique."

\

Leçons apprises et perspectives

• Une documentation riche est impérative pour une meilleure précision lors du travail avec des systèmes d'IA. Une documentation précise, claire et concise est essentielle pour la robustesse. Bonus : Nous avons également utilisé le LLM pour générer un résumé et une description pour chaque API, ce qui a énormément aidé.
• Catégoriser d'abord
• Pourquoi : Avec des centaines d'APIs, la catégorisation réduit la charge cognitive et améliore la récupération.
• Comment : Regroupez les APIs connexes dans un petit ensemble de catégories claires. Les systèmes d'IA fonctionnent mieux lorsque l'espace d'étiquettes est limité.
• Conseil d'échelle : Si le catalogue est très grand, ajoutez des sous-catégories pour un routage plus fin.
• Construire de manière itérative
• Commencer petit : Prenez un sous-ensemble de la spécification et entraînez/validez un routeur qui peut sélectionner de manière fiable l'API correcte.
• Élargir progressivement : Ajoutez plus d'APIs au fil du temps, mesurez la précision et priorisez les zones avec des classifications erronées.
• Focus : Optimisez la précision/rappel plutôt que l'étendue au départ.
• Fermer la boucle avec les utilisateurs
• Recueillir des commentaires : Capturez les cas où le système a choisi la mauvaise API.
• Agir sur les signaux : Affinez les descriptions, résumés et balises des APIs mal identifiées ; clarifiez les chevauchements de portée.
• Répéter : Réévaluez après chaque changement pour confirmer que la précision s'améliore et que les régressions sont évitées.

Conclusion

À mesure que le nombre d'APIs disponibles continue de croître, leur exploration et leur gestion nécessitent une nouvelle approche. Avec l'essor des Agents d'IA alimentés par des modèles de langage de grande taille (LLMs), les développeurs disposent désormais d'un moyen plus intuitif et efficace de découvrir et d'interagir avec les APIs—économisant d'innombrables heures auparavant consacrées à la recherche des bons points de terminaison.

Le potentiel ne s'arrête pas là. Ce concept peut évoluer vers un produit autonome capable d'ingérer de manière transparente les spécifications OpenAPI au moment de l'exécution et de les exposer via une interface en langage naturel—offrant aux utilisateurs une solution prête à l'emploi pour l'exploration des APIs.

J'espère que cet article a illustré comment exploiter efficacement les LLMs et comment une documentation d'API bien structurée peut créer une expérience de découverte plus fluide et plus intelligente.

\n \n

\n \n