C'est une série de 10 parties partageant 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 à l'article qui vous intéresse :
| Titre | Focus | |
|---|---|---|
| 1 | Nous Avons Construit 126 MCP Tools. Mais Ce N'est Pas la Meilleure Solution pour les Agents | Découverte du problème |
| 2 | Pourquoi Nous Avons Développé un Apidog CLI Entièrement Nouveau | Développement de l'architecture |
| 3 | La Règle d'Or : CLI Produit des Facts, le Model Agit sur les Facts | Philosophie centrale |
| 4 | agentHints : Apprendre aux CLIs à Communiquer avec les Agents |
Output structuré |
| 5 | SKILL : Livrer l'Expérience Opérationnelle comme Code | Expérience opérationnelle |
| 6 | Les Chiffres Ne Mentent Pas : 30% Moins de Tool Calls, 25% Moins de Tokens | Résultats quantitatifs |
| 7 | Du PRD au Loop de Test : Un Workflow Agent Complet avec Apidog CLI | Tutoriel pratique |
| 8 | Pourquoi la Compatibilité CI/CD Est Incontournable pour les Agent Tools | Perspective DevOps |
| 9 | AI Branch : Changements de Projet Plus Sécurisés avec les AI Agents | Couche de sécurité |
| 10 | Spec-First C'était Hier. Bienvenue au Skill-First. | Vision et futur |
Nous Avons Construit 126 MCP Tools. Puis Nous Avons Découvert que Ce n'est pas la Meilleure Solution pour Travailler sur le Développement d'API avec des Agents.
Quand MCP (Model Context Protocol) a become le hotspot de l'industrie au début de 2025, la question que chaque produit API faced était simple : "Avez-vous MCP ?"
Pour Apidog, nous avons répondu oui. Nous avons construit un MCP Server complet—pas juste une simple demo. Le MCP client aurait initialisé une session, le server aurait généré un sessionId, et saved le state de session via Redis. C'était un système de session au niveau protocol. Nous avons divisé les tools en catégories : tools natifs du projet, tools de domaine built-in, et 126 tools générés automatiquement convertis depuis des définitions d'endpoints OpenAPI.
Apidog MCP continue à fonctionner et à servir les users qui ont besoin d'intégration MCP. Il fournit des connexions de tools standardisées suivant le protocol MCP, ce qui est valuable pour l'ecosystem.
Mais quand nous avons entré dans des tasks réelles impliquant des workflows R&D complexes, nous avons découvert des limitations. Quand un user dit "aide-moi à ajouter un test pour cet endpoint et run la verification", l'Agent faced un mur de tools random—deciding lequel utiliser, dans quel sequence, avec quel validation.
Nous avons realized : MCP excelle à connecter les tools, mais les tasks R&D complexes ont besoin de plus que tool connection—elles ont besoin de processes d'engineering executables.
Cette insight nous a led à développer Apidog CLI comme une better approach—one qui handle les workflows de développement mieux.
Qu'est-ce que Apidog CLI ?
Apidog CLI est un outil en ligne de commande pour le test d'API qui vous permet de run des scenarios de test, manage la documentation d'API, et automate les workflows de test directement depuis votre terminal ou pipelines CI/CD. Built spécifiquement pour que les agents IA manage les resources d'API, il va au-delà du CLI traditionnel pour le test d'API—fournissant un output structuré, une validation de schema, et un guidance de next steps que les agents ont besoin pour execute des workflows complexes en sécurité. Que vous soyez running des tests d'API automatisés dans GitHub Actions, generating des cases de test depuis code avec Claude Code, ou maintaining des scenarios de test across projets, Apidog CLI sert comme le bridge entre les agents IA et votre infrastructure de test d'API.
Quick Start : Essayez Apidog CLI + SKILL
Si vous voulez essayer l'approche décrite dans cette série, voici comment commencer :
# Install Apidog CLI
npm install -g apidog-cli@latest
# Install companion SKILL for AI Agents
apidog skill install
# Check version (need 2.2.5+ for new capabilities)
apidog -v
# Authenticate
Or demandez à votre AI Agent de l'installer :
Read the instructions and help me install Apidog CLI:
Votre Première Task avec l'Agent
Après l'installation, givez à votre Agent une task petite et low-risk :
Use Apidog CLI to help me create my first API endpoint in Apidog.
First, check my Apidog CLI setup and list the projects I can access.
Ask me which project to use. After I confirm, create a simple GET /health
endpoint named Health Check with a 200 response example. Validate any
structured input before writing, then read the endpoint back and summarize
Cela vous donne un starting point concret : l'Agent check le setup, asks avant writing, crée une small API definition, validates avant writing, et confirms le saved result.
L'Architecture Centrale
| Layer | Responsabilité |
|---|---|
| Apidog | Manage les assets d'API et de test (docs, schemas, mocks, tests, reports) |
| CLI | Fournit une execution deterministic (read, validate, write, run) |
| SKILL | Fournit un judgment de task et des operation paths (8 Skills companions) |
| AI Branch | Isole les changes pour human review avant merge |
| Agents | Comprennent les goals, call des commands, adjust basés sur feedback |
Le Loop Plus Sécurisé pour le Test Agent-Driven
With AI Branch comme la couche de sécurité outer, le workflow complet ressemble à ceci :
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (Couche de Sécurité) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Read Assets │────▶│ Generate │────▶│ Validate │ │
│ │ (CLI get) │ │ (Agent) │ │ (cli-schema)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Run Tests │◀────│ Read Back │◀────│ Write │ │
│ │ (apidog run)│ │ (CLI get) │ │ (to AI Br.) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Human Review & Merge │ │
│ │ (User confirms before main branch) │ │
│ └──────────────────────────────────────┘ │
Ce loop matters parce que beaucoup de resources Apidog sont structurées. Les cases de test et scenarios de test incluent des data de request, des assertions, de la variable extraction, des pre/post processors, un step order, et des environment references. Si un Agent guesses la structure, des small mistakes causent des failed writes, un display incomplete, ou des tests qui ne se comportent pas comme expected.
Laissez l'Agent generate, laissez le CLI validate, et laissez AI Branch isoler les changes jusqu'à human review.
Overview du Journey Apidog CLI
Cette série documents comment nous avons développé Apidog CLI comme une better strategy pour les workflows R&D d'API.
Apidog MCP continue à fournir des connexions de tools standardisées—c'est valuable et nous le maintainons. Mais pour les tasks impliquant des workflows multi-step, des validation gates, et une execution structurée, nous avons found que CLI + SKILL offre une better experience.
Nous n'avons pas juste ajouté des commands au old CLI, où les users run des tests d'API automatiques integrating avec leur CI/CD. Nous avons systématiquement introduit les core capabilities d'Apidog dans CLI, le making un workflow layer pour developers, scripts, et AI Agents.
La key différence est où la complexity lives :
- MCP route : Complexity dans le model context et le stage de tool selection—great pour les tool calls simples
- CLI + SKILL route : Complexity distributed dans le engineering system—better pour les workflows plus avancés
Le résultat : des agent workflows plus sécurity pour les tasks complexes, fewer tool calls, less token waste, et une better error recovery—while MCP remains available pour les users qui préfèrent cette approach.
La Map du Journey Apidog CLI
┌─────────────────────────────────────────────────────────────────┐
│ THE APIDOG CLI + SKILL JOURNEY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Problem Discovery] │
│ │ │
│ ┌───┐ │
│ │ 1 │ We Built 126 MCP Tools. Then We Found │
│ └───┘ a Better Approach for Workflows. │
│ │ │
│ ▼ │
│ [Architecture Development] │
│ ┌───┐ │
│ │ 2 │ Why We Developed a Brand-new Apidog CLI │
│ └───┘ │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ [Core Philosophy] [Technical Design] │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ 3 │ CLI Produces │ 4 │ agentHints: │ 5 │ SKILL: Shipping │
│ └───┘ Facts └───┘ Teaching └───┘ Operational │
│ │ │ CLIs │ Experience │
│ │ │ │ │
│ └──────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ [Validation & Practice] │
│ ┌───┐ ┌───┐ │
│ │ 6 │───────│ 7 │ │
│ └───┘ Numbers│ PRD to Testing │
│ │ │ Loop │
│ ▼ ▼ │
│ [Foundation] [Security Layer] │
│ ┌───┐ ┌───┐ │
│ │ 8 │───────│ 9 │ │
│ └───┘ CI/CD │ AI Branch │
│ │ │ │
│ └────────┘ │
│ │ │
│ ▼ │
│ [Vision] │
│ ┌────┐ │
│ │ 10 │ Spec-First → Skill-First │
│ └────┘ │
│ │
Navigation Rapide du Journey
Partie 1 : Découverte du Problème
MCP fournit des connexions de tools standardisées—mais pour les workflows R&D complexes, nous avons découvert des limitations. Les Agents faced un mur de tools random quand les tasks impliquaient des processes multi-step. Ce post explore quatre challenges structurels et pourquoi CLI + SKILL sont better pour les tasks avec des workflows heavy.
Partie 2 : Développement de l'Architecture
2. Pourquoi Nous Avons Développé un Apidog CLI Entièrement Nouveau
Nous n'avons pas abandoned MCP—nous avons built CLI + SKILL pour handle ce que MCP n'optimize pas : workflows complexes avec des validation gates et une execution structurée. Ce post compare des chains d'execution et explique comment CLI + SKILL distribute la complexity dans le engineering system while MCP continue à servir son purpose.
Partie 3 : Philosophie Centrale
3. La Règle d'Or : CLI Produit des Facts, le Model Agit sur les Facts
Le principle core : ne makez pas le model memorize toutes les rules—let les rules être executed aux bons places. Ce post introduit `cli-schema validate`, le quality gate qui catche les field errors, les enums wrong, et les problems structurels avant qu'ils deviennent des failed writes.
Parties 4-5 : Design Technique
4. agentHints : Apprendre aux CLIs à Communiquer avec les Agents
L'output CLI traditionnel est pour les humans. Les Agents ont besoin de results structurés, de failure reasons, et de suggestions de next steps. `agentHints` turne l'expérience produit en guidance machine-readable—appearing exactement où les Agents ont besoin de make des decisions.
5. SKILL : Livrer l'Expérience Opérationnelle comme Code
Un SKILL n'est pas juste un command reference. C'est un operating guide pour les AI Agents : quand utiliser un command, lequel vient first, quels fields ne doivent pas être guessed, quand validate, quand read back. SKILL package le knowledge de workflow dans des guides versionable, evolvable.
Parties 6-7 : Validation et Pratique
6. Les Chiffres Ne Mentent Pas : 30% Moins de Tool Calls, 25% Moins de Tokens
Nous avons comparé MCP vs. CLI + SKILL across des tasks typiques. Les steps de tool calls ont decreased ~30%. La consommation de tokens depuis des descriptions invalid et des retries a decreased ~25%. Les retries de structural errors ont decreased ~40%. Ce post breakdown où les savings viennent.
7. Du PRD au Loop de Test : Un Workflow Agent Complet avec Apidog CLI
Walk through un example real : une team a un Order Refund PRD et codebase. Seez comment un Agent use CLI + SKILL pour generate OpenAPI, créer des test cases, validate des structures, build des test scenarios, et run verification—end to end.
Parties 8-9 : Foundation et Sécurité
8. Pourquoi la Compatibilité CI/CD Est Incontournable pour les Agent Tools
L'agent-friendliness doit être built sur CI/CD-friendliness. `apidog run` sert both : CI cares about les exit codes, les report files, les stable parameters ; Agents care about les results structurés, les failure reasons, les next-step suggestions. Un command, multiple consumers.
9. AI Branch : Changements de Projet Plus Sécurisés avec les AI Agents
Quand les Agents modify des project resources, la security matters. AI Branch fournit un editing isolated—les changes stay dans une separate branch jusqu'à human review. Cela prevents les automated changes d'affecter directement la main branch. Créez, review, puis merge avec confidence.
Partie 10 : Vision et Futur
10. Spec-First C'était Hier. Bienvenue au Skill-First.
Le développement d'API change avec les AI Agents joining le workflow. Spec-First était pour la collaboration human. Skill-First package les specs, tests, et scenarios dans des skills executable, verifiable—complementing les approaches existantes pour l'agent era. Ce post outline le futur et fournit des getting-started steps concrets.
Key Takeaways (TL;DR)
| Insight | Ce Que Cela Signifie |
|---|---|
| MCP et CLI + SKILL servent des needs différents | MCP connecte les tools ; CLI + SKILL execute les workflows—usez ce qui fit votre task |
| La complexity belongs dans l'engineering, pas le context | 126 tools × 500 tokens = 50,000 tokens de burden pour les workflows complexes |
| `cli-schema validate` est le quality gate | Catche les errors locally, pas via des failed writes |
| `agentHints` guide les next steps | Prévient les Agents de writing basé sur "imagination" |
| SKILL package l'expérience opérationnelle | Pas juste des commands—workflow wisdom pour les Agents |
| CI/CD remains la foundation | Agent features added on top, pas replacing CI |
| AI Branch fournit une couche de security | Editing isolated + human review avant merge |
Commencez à Lire
Ready à dive in ? Commencez avec Post 1 : Nous Avons Construit 126 MCP Tools. Puis Nous Avons Découvert une Better Solution pour les Workflows.
Download Apidog pour design, mock, test, et document les APIs dans un workspace. Learn more sur Apidog CLI pour le test d'API en ligne de commande, l'automatisation CI et les workflows AI Agent.