Il s'agit d'une série en 10 parties expliquant comment Apidog a développé Apidog CLI, un outil en ligne de commande pour les tests d'API et la gestion du cycle de vie des API. Lisez dans l'ordre ou accédez à n'importe quel article qui vous intéresse :
| Titre | Objectif | |
|---|---|---|
| 1 | Nous avons construit 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 : le CLI produit des faits, le modèle agit sur les faits | Philosophie fondamentale |
| 4 | agentHints : Apprendre aux CLI à parler aux Agents |
Sortie structurée |
| 5 | SKILL : 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 modifications de projet plus sûres avec les agents IA | Couche de sécurité |
| 10 | La spécification d'abord, c'était hier. Bienvenue à la compétence d'abord. | Vision & avenir |
Une COMPÉTENCE (SKILL) n'est pas seulement une référence de commande. C'est un guide d'utilisation pour les Agents IA : quand utiliser une commande, quelle vient en premier, quels champs ne doivent pas être devinés, quand valider, quand relire.
Le CLI seul ne suffit pas
Les commandes CLI confèrent à un Agent un pouvoir d'exécution.
Mais le pouvoir sans discernement entraîne des problèmes :
| Pouvoir du CLI | Risque sans discernement |
|---|---|
| Créer un cas de test | Crée dans le mauvais projet |
| Mettre à jour le scénario de test | Met à jour sans relire |
| Importer des étapes | Importe sans vérifier la structure existante |
| Exécuter des tests | Exécute sans valider les modifications |
Les Agents ont besoin de plus que de commandes. Ils ont besoin de jugement opérationnel.
Qu'est-ce qu'une COMPÉTENCE (SKILL) ?
Une COMPÉTENCE (SKILL) est un guide d'utilisation écrit pour les Agents IA.
Ce n'est pas :
- Une simple liste de commandes
- Un manuel de référence
- Une page d'aide
C'est :
| Contenu de la COMPÉTENCE (SKILL) | Objectif |
|---|---|
| Quand utiliser une commande | Mappage type de tâche → commande |
| Quelle commande vient en premier | Guidage de séquence |
| Quels champs ne doivent pas être devinés | Limites de sécurité |
| Quand valider | Placement des portes de qualité |
| Quand relire | Moment de vérification |
| Quand exécuter des tests | Flux de travail de confirmation |
La COMPÉTENCE (SKILL) donne aux Agents un jugement opérationnel.
Installation
La COMPÉTENCE (SKILL) est un compagnon d'Apidog CLI :
# Install SKILL for your AI Agent
apidog skill installCeci installe 8 COMPÉTENCES (Skills) complémentaires qui aident les Agents à comprendre :
- La sémantique des commandes CLI
- Les structures de ressources
- Les flux de travail des tâches
- La gestion des erreurs
- Les schémas de vérification
Pourquoi la COMPÉTENCE (SKILL) est importante : les flux de travail cachés
L'Agent doit toujours savoir comment les tâches doivent être décomposées en flux d'exécution inter-métiers.
Cette expérience ne peut pas être :
- Intégralement écrite dans les descriptions d'outils (consommerait trop de contexte)
- Dispersée dans le contexte du chat (serait perdue entre les sessions)
- Mémorisée par le modèle (spécifique au produit, pas de connaissance générale)
Les flux de travail cachés et les "pièges commerciaux" nécessitent une orientation explicite.
Exemple : Maintenance de scénario de test
Considérons la maintenance d'un scénario de test complexe.
Approche incorrecte (l'Agent écrit à la main à partir de zéro) :
Agent: "I'll create the test scenario structure manually"
Agent: Writes complete steps array with assertions, extractors, processors
Result: Field errors, wrong comparators, missing required fields
CLI: Rejects write or creates incomplete scenarioApproche correcte (encodée dans la COMPÉTENCE (SKILL)) :
| Étape | Pourquoi |
|---|---|
| 1. Importer les étapes existantes depuis les endpoints ou les cas de test | Ne pas écrire à la main des structures complexes |
| 2. Relire la structure complète | Voir le format importé réel |
| 3. Apporter des modifications locales | Travailler avec une base précise |
| 4. Valider avant la mise à jour | Détecter les erreurs localement |
| 5. Exécuter le scénario | Vérifier le comportement |
La COMPÉTENCE (SKILL) ne dit pas seulement "il y a une commande test-scenario update."
Elle dit :
"Les scénarios complexes ne sont pas adaptés à l'écriture manuelle de structures complètes à partir de zéro. Un chemin plus stable consiste à importer d'abord les étapes d'endpoint ou de cas existantes, puis à relire la structure complète, et enfin à effectuer des modifications locales."
Les commandes derrière le guidage de la COMPÉTENCE (SKILL)
Voici les commandes réelles que la COMPÉTENCE (SKILL) guide les Agents à utiliser :
# Step 1: Import steps from endpoints
apidog test-scenario import-steps <scenarioId> --project <projectId> \
--source endpoint --ids <endpointIds> --sync manual
# Step 2: Read back with full detail
apidog test-scenario get <scenarioId> --project <projectId> \
--with-case-detail
# Step 3: Update specific parts (Agent generates update JSON)
# Step 4: Validate before update
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# Step 5: Execute update
apidog test-scenario update <scenarioId> --project <projectId> \
--file ./scenario-update.json
# Step 6: Run verification
apidog run --project <projectId> --test-scenario <scenarioId>La COMPÉTENCE (SKILL) indique à l'Agent quand utiliser chaque commande et pourquoi.
Insight clé : get--with-case-detail
La COMPÉTENCE (SKILL) souligne :
"Utilisez get--with-case-detail pour obtenir la structure réelle, et non pour imaginer le cas à l'intérieur des étapes."Pourquoi cela est important :
Sans get--with-case-detail |
Avec get--with-case-detail |
|---|---|
| Les étapes n'affichent que les ID | Les étapes affichent les structures complètes des cas |
| L'Agent ne connaît pas le format interne | L'Agent voit le format réel d'assertion/extracteur |
| L'Agent devine les noms de champs | L'Agent travaille à partir d'exemples réels |
Obtenir la structure réelle empêche les mises à jour basées sur l'imagination.
Évolutivité : la COMPÉTENCE (SKILL) peut changer
Apidog SKILL est une expérience opérationnelle évolutive et versionnable.
Pourquoi c'est important
| Défi | Solution SKILL |
|---|---|
| Les commandes CLI changent | La COMPÉTENCE (SKILL) peut être mise à jour en conséquence |
| Les utilisateurs ont des flux de travail personnalisés | La COMPÉTENCE (SKILL) peut être personnalisée |
| Nouvelles fonctionnalités produit | La COMPÉTENCE (SKILL) peut être étendue |
| Améliorations des flux de travail | La COMPÉTENCE (SKILL) peut être affinée |
Comment ça marche
Les Agents se voient accorder des autorisations d'écriture pour la COMPÉTENCE (SKILL).
Si la COMPÉTENCE (SKILL) prend du retard ou devient difficile à utiliser :
- L'Agent peut la modifier
- L'Agent peut suggérer des améliorations
- La COMPÉTENCE (SKILL) évolue par l'usage
La COMPÉTENCE (SKILL) n'est pas une documentation figée. C'est du code opérationnel vivant.
La couche de compatibilité
Nous l'avons appris grâce à de vrais bugs :
Problème découvert :
Certaines étapes de scénario, lors de mises à jour secondaires, avaient des étapes externes mises à jour avec succès, mais les cas HTTP internes n'étaient pas correctement mis à jour.
Cause principale :
- Les marqueurs de mise à jour des cas internes nécessitaient un traitement spécial
- Les Agents ne connaissaient pas ces marqueurs
- La sémantique du produit exigeait des drapeaux spécifiques
Solution :
- Logique de compatibilité intégrée au CLI
- Le CLI gère automatiquement les marqueurs internes
- Les utilisateurs et les Agents n'ont pas besoin de connaître les détails internes
La signification des contraintes est intégrée dans la COMPÉTENCE (SKILL) :
La COMPÉTENCE (SKILL) indique à l'Agent d'utiliser les bonnes commandes. Le CLI gère la sémantique du produit derrière ces commandes. L'Agent n'a pas besoin de comprendre les marqueurs internes.
Chargement à la demande
La COMPÉTENCE (SKILL) suit le même principe que cli-schema :
La complexité doit être absorbée par l'exécution et la documentation, et non entièrement exposée au modèle.
| Alternative | Problème |
|---|---|
| Charger toute la COMPÉTENCE (SKILL) dans le contexte | Charge de jetons |
Mettre toutes les règles dans --help |
Rivalise pour l'attention |
| Écrire dans le prompt | Ne peut pas être mis à jour |
Approche SKILL :
- L'Agent "préchauffe" la COMPÉTENCE (SKILL) à la demande
- La COMPÉTENCE (SKILL) est chargée lorsque le type de tâche est identifié
- Seules les directives de flux de travail pertinentes entrent dans le contexte
COMPÉTENCE (SKILL) vs. Documentation
| Documentation | COMPÉTENCE (SKILL) |
|---|---|
| Pour les humains à lire | Pour les Agents à exécuter |
| Explique ce que font les commandes | Explique quand les utiliser |
| Référence statique | Flux de travail dynamique |
| Compréhensive | Axée sur la tâche |
| Externe à l'Agent | Intégrée à l'Agent |
Les 8 COMPÉTENCES (Skills) complémentaires
Apidog fournit 8 COMPÉTENCES (Skills) complémentaires :
| COMPÉTENCE (SKILL) | Couverture |
|---|---|
| Gestion de projet | Projets, métadonnées, ressources |
| Conception d'API | Endpoints, schémas, définitions |
| Gestion de l'environnement | Environnements, variables |
| Création de cas de test | Tests de point de terminaison unique, assertions |
| Gestion de scénario de test | Tests multi-étapes, importation, mise à jour |
| Organisation de suite de tests | Regroupement, exécution |
| Flux de travail d'import/export | Migration de données, sauvegarde |
| Intégration CI/CD | Commandes de pipeline, rapports |
Chaque COMPÉTENCE (SKILL) contient :
- Identification du type de tâche
- Guidage de la séquence de commandes
- Limites de sécurité des champs
- Points de contrôle de validation
- Schémas de vérification
Et ensuite ?
Maintenant que nous avons établi les trois composants principaux :
- cli-schema validate — Porte de qualité
- agentHints — Navigation à l'étape suivante
- SKILL — Jugement de flux de travail
La question suivante est :
Est-ce que cela fonctionne réellement ? Quels sont les chiffres ?
Dans la Partie 6, Les chiffres ne mentent pas : 30 % d'appels d'outils en moins, 25 % de jetons en moins, nous partagerons les résultats quantitatifs de nos comparaisons internes — et expliquerons d'où proviennent les économies.
Points clés à retenir
- Le CLI donne le pouvoir d'exécution ; la COMPÉTENCE (SKILL) donne le jugement opérationnel
- La COMPÉTENCE (SKILL) est un guide d'utilisation, pas une référence de commande
- Les flux de travail cachés nécessitent une orientation explicite
- Importer les étapes → relire → mettre à jour localement est plus sûr que l'écriture manuelle
--with-case-detailempêche les mises à jour basées sur l'imagination- La COMPÉTENCE (SKILL) est évolutive — les Agents peuvent la modifier
- Le CLI absorbe la sémantique du produit, la COMPÉTENCE (SKILL) guide le flux de travail
- Le chargement à la demande prévient la surcharge de contexte
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 les tests d'API en ligne de commande, l'automatisation CI et les flux de travail d'Agents IA.