Ceci est 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-les 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é la toute nouvelle 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 fondamentale |
| 4 | agentHints : Enseigner aux CLI comment parler aux Agents |
Sortie structurée |
| 5 | SKILL : Livrer l'expérience opérationnelle sous forme de code | Expérience opérationnelle |
| 6 | Les chiffres ne mentent pas : 30 % d'appels d'outils en moins, 25 % de tokens en moins | Résultats quantitatifs |
| 7 | Du PRD à la boucle de test : un workflow Agent complet 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 à Skill-First. | Vision et futur |
Ne laissez pas le modèle mémoriser toutes les règles — laissez les règles être exécutées aux bons endroits. cli-schema validate transforme le Schéma de connaissance en une barrière de qualité.
Le principe fondamental : Laissez les règles être exécutées aux bons endroits.
Nous avons tiré un principe fondamental de notre expérience :
Ne laissez pas le modèle mémoriser toutes les règles. Laissez les règles être exécutées aux bons endroits.
C'est similaire à une leçon tirée de l'évaluation des Agents :
| Type d'indicateur | Où il appartient |
|---|---|
| Indicateurs déterministes | Scripts, code, vérifications automatisées |
| Jugements sémantiques | LLMs, raisonnement du modèle |
Dans Apidog CLI + SKILL :
| Quoi | Où |
|---|---|
| Validation de structure déterministe | CLI (cli-schema) |
| Jugement et génération de tâches | Agents |
Laissez la CLI valider la structure. Laissez les Agents générer le contenu.
Le problème avec la mémoire du modèle
Lorsqu'un Agent IA aide à créer ou à mettre à jour des ressources Apidog, la partie risquée ne se limite pas à la génération de contenu.
La partie risquée est d'écrire le contenu généré dans un projet réel sans suffisamment de structure ou de vérification.
Les ressources Apidog sont structurées. Considérez ce qu'un cas de test ou un scénario de test inclut :
| Composant | Complexité |
|---|---|
| Données de requête | Méthode, URL, en-têtes, corps, authentification |
| Assertions | Comparateur, sujet, valeur cible, conditions |
| Extraction de variable | Nom de variable, type, chemin d'extraction |
| Pré-processeurs | Scripts avant la requête |
| Post-processeurs | Scripts après la réponse |
| Ordre des étapes | Séquence, dépendances |
| Références d'environnement | ID d'environnement, surcharges de variables |
Si un Agent devine la structure :
- Nom de champ incorrect → Échec de l'écriture
- Valeur d'énumération invalide → Rejet du serveur
- Champ requis manquant → Ressource incomplète
- Type incorrect → Problèmes d'affichage de l'interface utilisateur
- Imbrication incorrecte → Les tests ne se comportent pas comme prévu
cli-schema validate : La barrière de qualité
L'incarnation la plus directe de notre principe est cli-schema validate.
apidog cli-schema validate test-scenario-update --file ./scenario-update.jsonLorsqu'un Agent veut écrire ou mettre à jour un scénario de test, la génération de structures d'étapes complexes par l'IA est très sujette aux erreurs.
La commande validate :
- Confirme les noms de champs
- Vérifie la validité structurelle
- Vérifie l'efficacité des valeurs d'énumération
- Valide les contraintes de type
Tout cela avant d'initier la requête d'écriture.
Erreurs courantes que cli-schema détecte
Voici des exemples réels d'erreurs que les Agents commettent couramment — et que cli-schema validate détecte :
| Valeur incorrecte | Valeur correcte | Contexte |
|---|---|---|
global |
globals |
Type de portée de variable |
contains |
include |
Comparateur d'assertion |
responseBody |
responseJson |
Sujet du corps de réponse |
"500" (chaîne) |
500 (nombre) |
Délai en millisecondes |
equals |
equal |
Comparateur d'assertion |
header |
headers |
Champ des en-têtes de requête |
Ce ne sont pas des théories. Nous les avons découvertes grâce à de réelles interactions avec les Agents.
Chaque erreur entraînerait :
- Un échec de la requête d'écriture
- Une erreur de réponse de l'API
- Une confusion de l'Agent sur ce qui n'a pas fonctionné
- Plusieurs tentatives de réessai
- Un gaspillage de tokens sur des appels répétés
Avec cli-schema validate, ces erreurs sont détectées localement, avant l'appel réseau.
La philosophie de conception
Considérons les alternatives :
Alternative 1 : Écrire les règles dans le prompt
Si nous écrivions toutes les règles de champ dans le prompt de l'Agent :
- Chaque nom de champ documenté
- Chaque valeur d'énumération listée
- Chaque contrainte de type expliquée
- Chaque structure imbriquée décrite
Résultat : Une charge contextuelle massive.
Un schéma de scénario de test complet pourrait facilement nécessiter plus de 5 000 tokens de description. C'est un contexte que le modèle doit transporter pour chaque tâche, même lorsque la plupart des règles ne sont pas pertinentes.
Alternative 2 : Compter sur la mémoire du modèle
Si nous comptons sur le modèle pour "connaître" la structure correcte :
- Modèle entraîné sur certains modèles d'API
- Mais pas spécifiquement sur les schémas Apidog
- Les noms de champs varient d'un produit à l'autre
- Les valeurs d'énumération sont spécifiques au produit
Résultat : Taux d'erreur élevés.
Le modèle n'a pas une mémoire parfaite des conventions spécifiques à Apidog. Il devinera — et les suppositions seront fausses.
Meilleure approche : Valider localement
Laissez l'Agent générer des brouillons. Laissez la CLI exécuter la validation avant l'écriture.
# L'Agent génère du JSON
# (L'Agent n'a pas besoin de mémoriser toutes les règles)
# La CLI valide
apidog cli-schema validate test-case-create --file ./test-case-create.json
# La CLI affiche les erreurs spécifiques s'il y en a
# L'Agent s'adapte en fonction des erreurs
# Seules les écritures valides sont effectuées
apidog test-case create --project <projectId> --file ./test-case-create.jsonTransformation de schéma
cli-schema validate transforme ce que signifie un Schéma :
| Avant | Après |
|---|---|
| Schéma = connaissance que le modèle doit mémoriser | Schéma = barrière de qualité qui doit être franchie |
| Erreurs découvertes par des écritures échouées | Erreurs découvertes par validation locale |
| Réessai via des appels réseau | Correction via ajustement local |
| Charge contextuelle | Barrière d'exécution |
Les problèmes ne sont pas consommés dans des requêtes réseau inutiles.
Les contrôles de qualité sont effectués via des commandes locales.
Exemple pratique
Examinons un workflow réel :
# L'Agent lit le point de terminaison
apidog endpoint get <endpointId> --project <projectId>
# L'Agent génère le JSON du cas de test
# (Crée ./test-case-create.json)
# Valider avant d'écrire
apidog cli-schema validate test-case-create --file ./test-case-create.jsonSi la validation réussit :
apidog test-case create --project <projectId> --file ./test-case-create.jsonSi la validation échoue :
Erreur : Le champ "assertions[0].comparator" a une valeur invalide "contains"
Valeurs valides : equal, not_equal, greater, less, include, not_include, exists, not_exists
Erreur : Le champ "extractors[0].type" a une valeur invalide "global"
Valeurs valides : globals, environment, collection, local
Suggestion : Corrigez ces champs et revalidez avant d'écrire.L'Agent :
- Lit les erreurs spécifiques
- Comprend exactement ce qui ne va pas
- Ajuste le fichier JSON
- Relance la validation
- Procède uniquement lorsque c'est valide
Pas d'écritures échouées. Pas de réessais confus. Pas de tokens gaspillés.
La leçon plus large
Ce principe s'étend au-delà de la validation.
| Type de règle | Où elle appartient |
|---|---|
| Règles de nom de champ | cli-schema |
| Règles de valeur d'énumération | cli-schema |
| Contraintes de type | cli-schema |
| Séquence de workflow | SKILL |
| Guidage pour la prochaine étape | agentHints |
| Décomposition de tâche | Agent |
Règles déterministes → Système d'ingénierie
Jugement sémantique → Agent
Et ensuite ?
Maintenant que nous avons établi le principe de validation, la question suivante est :
Après la validation, comment la CLI guide-t-elle l'Agent vers l'étape suivante ?
Dans la partie 4, agentHints : Enseigner aux CLI comment parler aux Agents, nous explorerons comment la sortie structurée avec des suggestions d'étapes suivantes transforme la CLI d'un exécutant de commandes en un navigateur de workflow.
Points clés à retenir
- Principe fondamental : les règles appartiennent à l'exécution, pas au contexte
- cli-schema validate est la barrière de qualité avant l'écriture
- Erreurs courantes : noms de champs incorrects, énumérations invalides, types incorrects
- La validation détecte les erreurs localement, évitant les allers-retours réseau
- Le schéma passe de "connaissance à mémoriser" à "porte à franchir"
- Règles déterministes → ingénierie ; jugement sémantique → Agent
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 workflows des Agents IA.