Ceci est une série en 10 parties expliquant comment Apidog a développé Apidog CLI, un outil en ligne de commande pour le test d'API et la gestion du cycle de vie des API. Lisez dans l'ordre ou accédez directement à n'importe quel article qui vous intéresse :
| Titre | Mise au point | |
|---|---|---|
| 1 | Nous avons créé 126 outils MCP. Mais ce n'est pas la meilleure solution pour l'Agent | Découverte du problème |
| 2 | Pourquoi nous avons développé le tout nouveau Apidog CLI | Développement de l'architecture |
| 3 | La Règle d'Or : la CLI produit des faits, le modèle agit sur les faits | Philosophie de base |
| 4 | agentHints : Enseigner aux CLI à parler aux Agents |
Sortie structurée |
| 5 | COMPÉTENCE : Transformer l'expérience opérationnelle en code | Expérience opérationnelle |
| 6 | Les chiffres ne mentent pas : 30 % d'appels d'outils en moins, 25 % de jetons en moins | Résultats quantitatifs |
| 7 | Du PRD à la boucle de test : un flux de travail complet d'Agent avec Apidog CLI | Tutoriel pratique |
| 8 | Pourquoi la compatibilité CI/CD est non négociable pour les outils d'Agent | Perspective DevOps |
| 9 | Branche IA : des changements de projet plus sûrs avec les Agents IA | Couche de sécurité |
| 10 | Spec-First, c'était hier. Bienvenue au Skill-First. | Vision et avenir |
Nous avons comparé MCP et CLI + SKILL sur des tâches utilisateur typiques. Les résultats : moins d'appels d'outils, moins de gaspillage de jetons, une meilleure récupération d'erreurs — et les données expliquent pourquoi.
La question qui compte
Toute la philosophie et les principes de conception que nous avons partagés — fonctionnent-ils réellement ?
Nous avons comparé en interne de nombreuses tâches utilisateur typiques selon les deux approches :
| Type de tâche | Description |
|---|---|
| Ajouter un cas de test + vérification | Créer un cas de test pour un endpoint, exécuter les tests |
| Maintenir les scénarios de test | Mettre à jour des scénarios complexes en plusieurs étapes |
| Importer/vérifier les actifs du projet | Importer des données, confirmer la structure, exécuter les tests |
Les résultats n'étaient pas seulement des améliorations subjectives. C'étaient des réductions mesurables.
Tâche 1 : Ajouter un cas de test basé sur un endpoint
Requête utilisateur :
"Ajoutez un test pour ce endpoint et exécutez la vérification"
Parcours MCP
| Étape | Ce qui se passe |
|---|---|
| Découverte d'outil | L'Agent recherche dans la liste des outils |
| Sélection d'outil | Plusieurs cycles de sélection de l'outil correct |
| Découverte de champs | L'Agent lit le schéma de l'outil |
| Devinette de champs | L'Agent devine les champs requis |
| Tentative d'écriture | L'Agent appelle l'outil de création |
| Réponse d'erreur | Le serveur rejette (champ incorrect/manquant requis) |
| Réessai | L'Agent ajuste, essaie à nouveau |
| Plusieurs réessais | Répéter jusqu'à succès |
| Exécuter les tests | L'Agent trouve l'outil d'exécution, l'exécute |
Schéma typique :
Rechercher outils → Sélectionner outil → Lire schéma → Deviner champs → Écrire → Erreur → Réessayer → Écrire → Erreur → Réessayer → Succès → Trouver outil d'exécution → ExécuterParcours CLI + SKILL
| Étape | Ce qui se passe |
|---|---|
| Guidage SKILL | SKILL identifie le type de tâche, fournit le flux de travail |
| Lire le endpoint | La CLI lit les faits du endpoint |
| Générer un cas de test | L'Agent génère basé sur les données réelles du endpoint |
| Valider localement | cli-schema valide avant l'écriture |
| Écrire | La CLI crée le cas de test |
| Relire | La CLI retourne la structure créée + agentHints |
| Exécuter les tests | agentHints suggère l'exécution, l'Agent suit |
Schéma typique :
SKILL guide → Lire endpoint → Générer → Valider → Écrire → Relire → ExécuterRésultats
| Métrique | Parcours MCP | CLI + SKILL | Amélioration |
|---|---|---|---|
| Étapes d'appel d'outils | ~15-20 | ~10-12 | ↓ ~30% |
| Jetons des descriptions | ~50 000 chargés | ~2 000 chargés | ↓ ~96% |
| Jetons des réessais | ~5 000+ gaspillés | ~500 gaspillés | ↓ ~90% |
| Gaspillage total de jetons | ~55 000 | ~2 500 | ↓ ~25% |
Les étapes d'appel d'outils ont diminué d'environ 30 %. La consommation de jetons due aux descriptions d'outils invalides et aux réessais d'erreurs a diminué d'environ 25 %.
Tâche 2 : Écritures structurées (Processeur, Assertion, Extracteur)
Requête utilisateur :
"Ajoutez des assertions post-opération et une extraction de variable à ce cas de test"
Parcours MCP
| Étape | Ce qui se passe |
|---|---|
| Deviner les noms de champs | L'Agent ne connaît pas les noms exacts |
| Deviner les valeurs d'énumération | L'Agent devine le comparateur, le type |
| Tentative d'écriture | Le serveur rejette les valeurs incorrectes |
| Réessai réseau | Aller-retour pour chaque erreur |
| Tentatives multiples | 3-5 réessais courants |
Erreurs courantes :
| Mauvaise devinette | Valeur correcte | Compteur de réessais |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Chaque erreur = 1 aller-retour réseau + réponse + traitement Agent.
Parcours CLI + SKILL
| Étape | Ce qui se passe |
|---|---|
| Lire le cas de test | La CLI obtient la structure réelle |
| Générer des ajouts | L'Agent génère basé sur le format réel |
| Valider localement | cli-schema détecte les erreurs avant le réseau |
| Corriger localement | L'Agent ajuste basé sur le résultat de la validation |
| Re-valider | Confirmer la correction |
| Écrire | Seules les écritures valides vont au serveur |
Toutes les erreurs sont détectées localement. Aucun réessai réseau pour les erreurs de champs.
Résultats
| Métrique | Parcours MCP | CLI + SKILL | Amélioration |
|---|---|---|---|
| Réessais réseau dus aux erreurs structurelles | 3-5 | 0 | ↓ ~100% |
| Jetons des réponses d'erreur | ~2 000 | ~0 | ↓ ~100% |
| Total des appels répétés | ~5 | ~1 | ↓ ~40% |
Les appels répétés dus aux erreurs structurelles ont diminué d'environ 40 %.
Tâche 3 : Opérations continues après création
Requête utilisateur :
"Créer un scénario de test avec ces endpoints"
Parcours MCP
| Étape | Ce qui se passe |
|---|---|
| Créer un scénario | L'Agent appelle l'outil de création |
| Réponse de succès | L'Agent voit "créé" |
| Continuer à écrire | L'Agent met à jour/ajoute immédiatement d'autres éléments |
| Sauter la relecture | L'Agent ne lit pas la structure réelle |
| Écrire basé sur l'hypothèse | L'Agent écrit avec des IDs/une structure devinés |
| Erreur ou incomplet | Le résultat ne correspond pas aux attentes |
Problème : Inertie d'exécution.
Le modèle a tendance à continuer directement après le succès, en sautant l'étape de relecture.
Parcours CLI + SKILL
| Étape | Ce qui se passe |
|---|---|
| Créer un scénario | La CLI crée le scénario |
| Succès + agentHints | La CLI retourne le succès + des suggestions pour les prochaines étapes |
agentHints : "Relire d'abord" |
L'Agent voit la suggestion |
| Suivre la suggestion | L'Agent relit |
| Travailler avec une structure réelle | L'Agent procède avec des données précises |
agentHints suggère explicitement la relecture. L'Agent suit.
Résultats
| Métrique | Parcours MCP | CLI + SKILL | Amélioration |
|---|---|---|---|
| Proportion qui relit avant de continuer | ~20% | ~85% | ↑ ~425% |
| Réessais d'erreurs dus aux sauts directs | ~3-5 | ~0-1 | ↓ ~21% |
La proportion d'Agents relisant proactivement, validant et exécutant la vérification a considérablement augmenté. Les réessais d'erreurs dus au passage direct à l'étape suivante ont diminué d'environ 21 %.
Résumé : D'où proviennent les économies
| Source d'économies | Explication |
|---|---|
| Découverte d'outils | Les commandes CLI ont des noms clairs ; SKILL guide la sélection |
| Validation de schéma | La validation locale détecte les erreurs avant l'appel réseau |
| Récupération d'erreurs | agentHints fournit des suggestions concrètes, pas seulement "échec" |
| Guidage de relecture | Prévient les écritures basées sur des hypothèses |
| Séquence de flux de travail | SKILL réduit les points de décision |
L'analyse des coûts réels
Idée clé :
L'activation de produits par des Agents ne signifie pas que plus il y a d'outils, mieux c'est.
Ce que le modèle consomme vraiment :
| Type de coût | Charge MCP | Charge CLI + SKILL |
|---|---|---|
| Contexte | Descriptions d'outils, schémas | SKILL axé sur la tâche uniquement |
| Attention | Sélection parmi de nombreux outils | Suivi d'un flux de travail guidé |
| Sélection de chemin | Devinette de séquences | Séquence définie par SKILL |
| Coûts des jetons utilisateur | Réessais, appels échoués | Écritures validées, moins d'appels |
Après l'augmentation du nombre d'outils, ce que le modèle consomme vraiment, ce n'est pas la capacité d'appel d'API, mais des compromis entre le contexte, l'attention, la sélection de chemin et les coûts des jetons utilisateur.
Le principe d'ingénierie
Objectif :
Déplacer ces coûts hors du contexte du modèle et les réintégrer dans des positions que le système d'ingénierie peut supporter.
| Coût | Emplacement MCP | Emplacement CLI + SKILL |
|---|---|---|
| Découverte d'outils | Le modèle doit chercher | SKILL fournit |
| Validation de champ | Le modèle doit savoir | cli-schema valide |
| Guidage étape suivante | Le modèle doit décider | agentHints suggère |
| Sémantique produit | Le modèle doit comprendre | La CLI gère |
Le système d'ingénierie absorbe la complexité. Le modèle se concentre sur la génération et le jugement.
Ce que ces chiffres signifient
Les chiffres expliquent un problème plus spécifique :
| Insight | Implication |
|---|---|
| 30 % d'appels d'outils en moins | Complexité déplacée de la découverte vers le guidage |
| 25 % de jetons gaspillés en moins | Erreurs détectées avant le réseau |
| 40 % de réessais structurels en moins | La porte de validation fonctionne |
| 21 % d'erreurs de saut en moins | agentHints empêche la continuation aveugle |
CLI + SKILL n'est pas seulement une élégance architecturale. C'est une efficacité mesurable.
Et ensuite ?
Maintenant que nous avons validé l'approche avec des chiffres, voyons-la en action.
Dans la Partie 7, Du PRD à la boucle de test : un flux de travail complet d'Agent, nous passerons en revue un exemple concret — une équipe a un PRD "Remboursement de commande", et l'Agent utilise CLI + SKILL pour générer OpenAPI, créer des tests, valider et vérifier.
Points clés à retenir
- Les étapes d'appel d'outils ont diminué d'environ 30 %
- Le gaspillage de jetons des descriptions et des réessais a diminué d'environ 25 %
- Les réessais d'erreurs structurelles ont diminué d'environ 40 %
- Les erreurs de saut dues au fait d'ignorer la relecture ont diminué d'environ 21 %
- Les économies proviennent de : la découverte guidée, la validation locale, les conseils actionnables
- La complexité a été déplacée du contexte vers le système d'ingénierie
Téléchargez Apidog pour concevoir, simuler, tester et documenter les API dans un seul espace de travail. En savoir plus sur Apidog CLI pour le test d'API en ligne de commande, l'automatisation CI et les flux de travail d'Agent IA.