Esta serie de 10 partes explica cómo Apidog desarrolló Apidog CLI, una herramienta de línea de comandos para pruebas de API y gestión del ciclo de vida de las API. Puedes leerla en orden o ir directamente a la parte que necesites.
| # | Título | Enfoque |
|---|---|---|
| 1 | Construimos 126 Herramientas MCP. Pero no es la Mejor Solución para el Agente | Descubrimiento del problema |
| 2 | Por Qué Desarrollamos un Apidog CLI Completamente Nuevo | Desarrollo de arquitectura |
| 3 | La Regla de Oro: CLI Produce Hechos, el Modelo Actúa sobre los Hechos | Filosofía central |
| 4 | agentHints: Enseñando a los CLI a Hablar con los Agentes |
Salida estructurada |
| 5 | HABILIDAD: Enviando Experiencia Operacional como Código | Experiencia operacional |
| 6 | Los Números no Mienten: 30% Menos Llamadas a Herramientas, 25% Menos Tokens | Resultados cuantitativos |
| 7 | De PRD al Bucle de Pruebas: Un Flujo de Trabajo Completo del Agente con Apidog CLI | Tutorial práctico |
| 8 | Por Qué la Compatibilidad CI/CD es Innegociable para las Herramientas del Agente | Perspectiva DevOps |
| 9 | Rama de IA: Cambios de Proyecto Más Seguros con Agentes de IA | Capa de seguridad |
| 10 | Spec-First Fue Ayer. Bienvenido a Skill-First. | Visión y futuro |
Construimos CLI + SKILL para cubrir lo que MCP no optimiza: flujos de trabajo complejos con validación, ejecución estructurada y verificación.
MCP sigue cumpliendo su propósito
Primero, una aclaración importante: Apidog MCP sigue disponible y mantenido.
MCP es útil cuando necesitas conectar herramientas a agentes mediante un protocolo estandarizado. Funciona bien para:
- Operaciones simples y bien definidas.
- Usuarios que ya trabajan con flujos basados en MCP.
- Integraciones con clientes compatibles con MCP.
No reemplazamos MCP. Construimos CLI + SKILL para complementarlo.
La diferencia práctica está en el tipo de tarea. MCP destaca en la conexión de herramientas. CLI + SKILL está diseñado para procesos ejecutables de ingeniería, especialmente cuando hay múltiples pasos, validación, lectura de datos y verificación.
| Tipo de tarea | Enfoque recomendado |
|---|---|
| Llamada simple a herramienta, por ejemplo obtener un endpoint | MCP o CLI |
| Flujo de varios pasos, por ejemplo crear prueba, validar y ejecutar | CLI + SKILL |
| Integración CI/CD | CLI |
| Integración con ecosistema MCP | MCP |
El antiguo CLI: ejecutar pruebas al final
Apidog CLI ya permitía ejecutar pruebas de API desde la terminal:
apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>
Ese caso de uso sigue siendo clave para equipos que necesitan:
- Ejecutar pruebas de API desde scripts.
- Generar informes dentro de pipelines CI.
- Mantener puertas de calidad en flujos automatizados.
Pero el CLI anterior se usaba principalmente al final del proceso:
Diseño → Documento → Mock → Depurar → Probar → [CLI ejecuta pruebas]
En otras palabras, el CLI ejecutaba pruebas cuando todo lo demás ya estaba preparado.
El nuevo requisito: los agentes necesitan operar antes
El desarrollo de API ya no termina en “ejecutar pruebas”. Los agentes de IA ahora participan en etapas anteriores del ciclo de vida:
| Etapa | Actividad del agente |
|---|---|
| Diseño de API | Generar definiciones de endpoints a partir de PRD |
| Generación de pruebas | Crear casos de prueba desde especificaciones de API |
| Depuración | Analizar fallos y sugerir correcciones |
| Migración | Mover APIs entre proyectos |
| Mantenimiento | Actualizar pruebas cuando cambian las APIs |
Para estos flujos, el CLI no puede limitarse a ejecutar pruebas existentes. También debe permitir que un agente pueda:
- Leer activos de API: endpoints, esquemas y entornos.
- Crear o actualizar activos de prueba.
- Validar cambios antes de escribirlos.
- Escribir cambios en el proyecto.
- Verificar el resultado.
Expansión sistemática, no comandos aislados
El nuevo Apidog CLI no consiste solo en añadir algunos comandos al CLI anterior.
El objetivo es llevar capacidades centrales de Apidog a la línea de comandos para que desarrolladores, scripts y agentes puedan trabajar sobre una capa estable de flujo de trabajo.
| Antiguo CLI | Nuevo CLI |
|---|---|
| “¿Cómo ejecuto pruebas de Apidog externamente?” | “¿Cómo pueden los agentes de IA usar Apidog de forma estable?” |
Ese cambio modifica los límites de la arquitectura: el CLI pasa de ser un ejecutor final a ser una interfaz operativa para leer, validar, escribir y verificar.
MCP vs CLI + SKILL: cadena de ejecución
Comparemos cómo se ejecutan flujos complejos con cada enfoque.
Ruta MCP: buena para conectar herramientas
Inicializar sesión MCP
↓
Cargar lista de herramientas + descripciones
↓
El agente selecciona la herramienta
↓
Buscar más herramientas: listOpenApiEndpoints
↓
Obtener esquema: getOpenApiDetails
↓
Ejecutar llamada HTTP: executeOpenApi
Fortaleza de MCP: protocolo estandarizado para conectar herramientas a agentes.
Dónde queda la complejidad: en el contexto del modelo y en la selección de herramientas. El agente debe entender:
- Listas de herramientas.
- Descripciones.
- Esquemas de entrada.
- Secuencias de llamadas.
- Estructuras de retorno.
Esto funciona bien cuando hay una relación clara entre tarea y herramienta. Se vuelve más difícil cuando el agente debe orquestar varias herramientas, validar datos y entender semántica del producto.
Ruta CLI + SKILL: mejor para flujos complejos
SKILL identifica el tipo de tarea
↓
CLI ejecuta comandos semánticos de producto
↓
cli-schema valida la estructura
↓
agentHints sugiere el siguiente paso
↓
Bucle de verificación: lectura o apidog run
Fortaleza de CLI + SKILL: distribuye la complejidad en el sistema de ingeniería.
La responsabilidad se divide así:
- SKILL: guía metodológica y flujo de trabajo.
- CLI: ejecución semántica sobre recursos de Apidog.
- cli-schema: validación antes de escribir.
- agentHints: orientación después de ejecutar un comando.
Este enfoque encaja mejor con flujos de varios pasos, operaciones con validación y pruebas impulsadas por agentes.
La diferencia clave: dónde vive la complejidad
| Enfoque | Dónde reside la complejidad | Mejor para |
|---|---|---|
| MCP | Contexto del modelo + selección de herramienta | Llamadas simples, ecosistema MCP |
| CLI + SKILL | Sistema de ingeniería: SKILL, CLI, validación y sugerencias | Flujos complejos y operaciones de varios pasos |
En MCP, el modelo debe decidir:
- Qué herramienta usar.
- Qué significa cada descripción.
- Qué campos son obligatorios.
- Qué secuencia seguir.
- Cómo interpretar la respuesta.
En CLI + SKILL, el sistema aporta más estructura:
- SKILL identifica el tipo de tarea.
- CLI ejecuta comandos concretos.
-
cli-schemavalida la estructura. -
agentHintsindica próximos pasos.
Para flujos con puertas de validación, lectura previa y verificación, esta distribución reduce la carga de razonamiento del modelo.
Ejemplo práctico: leer, validar y verificar
Un flujo CLI + SKILL típico puede verse así:
# Paso 1: leer hechos del proyecto
apidog endpoint get <endpointId> --project <projectId>
# Paso 2: validar antes de escribir
apidog cli-schema validate test-case-create --file ./test-case-create.json
# Paso 3: ejecutar verificación
apidog run --project <projectId> --out-dir ./apidog-reports
Cada comando cumple una función de ingeniería:
| Comando | Acción |
|---|---|
endpoint get |
Leer hechos del proyecto |
cli-schema validate |
Validar estructura antes de escribir |
apidog run |
Ejecutar verificación |
El patrón recomendado es:
Leer hechos → Generar cambios → Validar estructura → Escribir → Verificar
Esto evita que el agente escriba cambios sin contexto o con una estructura inválida.
Ruta del agente para flujos complejos
Con MCP
Seleccionar herramientas → Entender esquemas → Orquestar secuencia → Manejar errores
El agente debe:
- Elegir las herramientas adecuadas entre varias opciones.
- Interpretar descripciones y esquemas.
- Ordenar correctamente las llamadas.
- Gestionar errores y reintentos.
Puede funcionar, pero exige razonamiento del modelo en cada punto de decisión.
Con CLI + SKILL
Leer hechos → Generar cambios → Validar estructura → Escribir → Ejecutar verificación
El agente sigue un flujo más operativo:
- Lee los datos existentes.
- Genera cambios basados en esos datos.
- Valida localmente con
cli-schema. - Escribe en el proyecto.
- Ejecuta verificación con
apidog runo vuelve a leer el recurso.
Ambas rutas pueden completar la tarea. La diferencia es que CLI + SKILL mueve parte de la complejidad desde el contexto del modelo hacia una capa ejecutable y validable.
Lo que ahora cubre Apidog CLI
Con la actualización, el CLI cubre más recursos centrales de Apidog:
| Recurso | Capacidad del CLI |
|---|---|
| Proyectos y metadatos | Listar, leer |
| APIs y definiciones de API | Obtener, crear, actualizar |
| Entornos y variables | Listar, gestionar |
| Casos de prueba | Crear, actualizar, validar |
| Escenarios de prueba | Crear, actualizar, importar pasos, obtener con detalle |
| Suites de prueba | Gestionar |
| Informes | Generar desde apidog run
|
| Importar/exportar | Exportar proyecto, importar archivos |
Esto cambia el papel del CLI.
Ya no es solo una forma de ejecutar pruebas al final. Ahora puede participar antes en el ciclo de desarrollo, cuando un agente necesita:
- Comprender el proyecto.
- Generar o actualizar activos de prueba.
- Validar cambios.
- Ejecutar verificaciones.
Resumen de arquitectura
| Dimensión | MCP | CLI + SKILL |
|---|---|---|
| Fortaleza principal | Conexión de herramientas | Ejecución de flujos de trabajo |
| Ubicación de la complejidad | Contexto del modelo | Sistema de ingeniería |
| Ruta del agente para tareas complejas | Seleccionar, orquestar, reintentar | Leer, validar, escribir, verificar |
| Cobertura | 126 herramientas generadas + herramientas nativas | Gestión de recursos + validación |
| Mejor ajuste | Operaciones simples, ecosistema MCP | Flujos complejos, CI/CD |
Ambos enfoques están disponibles. Elige según la tarea.
Qué sigue
Ahora que vimos cómo CLI + SKILL complementa a MCP, la siguiente pregunta es:
¿Cuál es el principio fundamental que hace que CLI + SKILL funcione bien para flujos complejos?
En la Parte 3, La Regla de Oro: CLI Produce Hechos, el Modelo Actúa sobre los Hechos, veremos la filosofía de diseño detrás de CLI + SKILL, empezando por cli-schema validate: la puerta de calidad que detecta errores antes de que se conviertan en escrituras fallidas.
Puntos clave
- MCP sigue disponible y es útil para operaciones simples e integración con el ecosistema MCP.
- CLI + SKILL complementa a MCP para flujos complejos con validación.
- La diferencia principal está en dónde vive la complejidad: contexto del modelo o sistema de ingeniería.
- CLI + SKILL reduce la carga del modelo mediante validación, guía y verificación.
- El CLI ahora cubre proyectos, APIs, entornos, casos de prueba, escenarios y más.
- Usa MCP o CLI + SKILL según la complejidad de la tarea.
Descarga Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtén más información sobre Apidog CLI para pruebas de API por línea de comandos, automatización CI y flujos de trabajo de agentes de IA.
Top comments (0)