Esta es una serie de 10 partes que comparte 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. Lee en orden o salta a cualquier publicación que te interese:
| 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 manejar lo que MCP no optimiza: flujos de trabajo complejos con puertas de validación y ejecución estructurada.
MCP Continúa Cumpliendo su Propósito
Antes de sumergirnos en CLI + SKILL, aclaremos: Apidog MCP sigue disponible y mantenido.
MCP proporciona conexiones de herramientas estandarizadas siguiendo el protocolo, lo cual es valioso para:
- Operaciones simples y bien definidas
- Usuarios que prefieren flujos de trabajo basados en MCP
- Integración del ecosistema con clientes compatibles con MCP
No reemplazamos MCP. Construimos CLI + SKILL para complementarlo.
Lo que descubrimos fue que MCP sobresale en la conexión de herramientas, pero para flujos de trabajo complejos de I+D (procesos de varios pasos con validación, lectura y verificación), los Agentes se benefician de procesos de ingeniería ejecutables. Ahí es donde encaja CLI + SKILL.
Piénsalo de esta manera:
| Tipo de Tarea | Enfoque Recomendado |
|---|---|
| Llamada simple a herramienta (ej., obtener endpoint) | MCP o CLI — ambos funcionan |
| Flujo de trabajo de varios pasos (ej., crear prueba, validar, ejecutar) | CLI + SKILL — mejor experiencia |
| Integración CI/CD | CLI — ajuste nativo |
| Integración del ecosistema MCP | MCP — estándar de protocolo |
El Antiguo CLI: Ejecutando Pruebas al Final
Apidog CLI ha sido durante mucho tiempo el punto de entrada de línea de comandos para ejecutar pruebas de API.
apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>Esa base sigue siendo importante. Los equipos necesitan una forma fiable de:
- Ejecutar pruebas de API desde la terminal
- Generar informes en pipelines de CI
- Mantener puertas de calidad dentro de los flujos de trabajo de automatización
Pero el antiguo CLI se centraba principalmente en la ejecución de pruebas. Aparecía cerca del final del flujo de trabajo:
Diseño → Documento → Mock → Depurar → Probar → [CLI ejecuta pruebas]El CLI era el último paso, después de que todo lo demás estuviera hecho.
El Nuevo Requisito: Los Agentes Necesitan Más
El desarrollo de API está cambiando.
Los Agentes de IA ahora participan en:
| Etapa | Actividad del Agente |
|---|---|
| Diseño de API | Generando definiciones de endpoint a partir de PRD |
| Generación de pruebas | Creando casos de prueba a partir de especificaciones de API |
| Depuración | Analizando fallos, sugiriendo correcciones |
| Migración | Moviendo APIs entre proyectos |
| Mantenimiento | Actualizando pruebas cuando las APIs cambian |
Para estos flujos de trabajo, un CLI no puede ser solo el último paso que ejecuta las pruebas existentes.
También necesita proporcionar a los Agentes una forma estable de:
- Leer activos de API (endpoints, esquemas, entornos)
- Crear o actualizar activos de prueba (casos de prueba, escenarios de prueba)
- Validar cambios estructurados antes de escribir
- Escribirlos de vuelta al proyecto
- Verificar el resultado
Expansión Sistemática, No Adición Incremental
El nuevo Apidog CLI no se trata solo de añadir algunos comandos al antiguo CLI.
Está introduciendo sistemáticamente las capacidades centrales de Apidog en el CLI, convirtiéndolo en una capa de flujo de trabajo para desarrolladores, scripts y Agentes de IA.
| Pregunta del Antiguo CLI | Pregunta del Nuevo CLI |
|---|---|
| "¿Cómo ejecuto las pruebas de Apidog externamente?" | "¿Cómo pueden los Agentes de IA usar Apidog de manera estable?" |
Los límites arquitectónicos detrás de esto han cambiado drásticamente.
MCP vs CLI: Comparación de Cadena de Ejecución
Comparemos las cadenas de ejecución típicas para flujos de trabajo complejos.
Ruta MCP (Buena para Conexión de Herramientas)
Inicializar sesión MCP
↓
Cargar lista de herramientas + descripciones de herramientas
↓
El Agente selecciona la herramienta
↓
Buscar más herramientas (listOpenApiEndpoints)
↓
Obtener esquema (getOpenApiDetails)
↓
Ejecutar llamada HTTP (executeOpenApi)La fuerza de MCP: Protocolo estandarizado para conectar herramientas a Agentes.
Ubicación de la complejidad: La mayor parte de la complejidad se encuentra en el contexto del modelo y la etapa de selección de herramientas. El Agente necesita entender:
- Listas de herramientas
- Descripciones de herramientas
- Esquemas de entrada
- Secuencias de llamadas
- Estructuras de retorno
Dónde funciona bien: Operaciones simples con un mapeo claro de herramienta a tarea.
Dónde se vuelve desafiante: Flujos de trabajo complejos donde el Agente debe orquestar múltiples herramientas, comprender la semántica del producto y manejar la validación.
Ruta CLI + SKILL (Mejor para Flujos de Trabajo Complejos)
SKILL juzga el tipo de tarea
↓
CLI ejecuta comandos semánticos de producto
↓
cli-schema valida la estructura
↓
agentHints ofrece sugerencias para el siguiente paso
↓
Bucle de verificación (obtener lectura o apidog run)La fuerza de CLI + SKILL: Distribuye la complejidad en el sistema de ingeniería.
Ubicación de la complejidad:
- SKILL: Metodología y guía de flujo de trabajo
- CLI: Ejecución semántica del producto
- cli-schema: Validación antes de escribir
- agentHints: Navegación después de la ejecución
Dónde funciona bien: Flujos de trabajo de varios pasos, operaciones con mucha validación, pruebas impulsadas por Agentes.
La Diferencia Clave: Dónde Reside la Complejidad
La diferencia entre estos dos enfoques es dónde se sitúa la complejidad.
| Enfoque | Dónde Reside la Complejidad | Mejor Para |
|---|---|---|
| MCP | Contexto del modelo + etapa de selección de herramienta | Llamadas de herramienta simples, ecosistema MCP |
| CLI + SKILL | Sistema de ingeniería (SKILL, CLI, validación, sugerencias) | Flujos de trabajo complejos, operaciones de varios pasos |
En MCP, el modelo debe llevar:
- Qué herramienta usar
- Lo que dice la descripción de la herramienta
- Qué campos son obligatorios
- Qué secuencia seguir
- Lo que significa la estructura de retorno
Esto funciona cuando el mapeo de tarea a herramienta es directo.
En CLI + SKILL, el sistema de ingeniería lleva:
- Qué tipo de tarea es esta (SKILL)
- Qué comando ejecutar (CLI)
- Qué estructura es válida (cli-schema)
- Qué hacer a continuación (agentHints)
Esto funciona mejor cuando los flujos de trabajo tienen puertas de validación, requisitos de lectura y bucles de verificación.
Un Ejemplo de Flujo de Trabajo Típico
Aquí tienes un ejemplo concreto del flujo de trabajo CLI + SKILL:
# Paso 1: Leer hechos
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-reportsEstos tres comandos representan tres acciones 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 |
Ruta del Agente para Flujos de Trabajo Complejos
Para flujos de trabajo complejos y de varios pasos, la ruta del Agente se beneficia de la estructura CLI + SKILL.
Ruta MCP para Flujos de Trabajo Complejos
"Seleccionar herramientas → Entender esquemas → Orquestar secuencia → Manejar errores"El Agente:
- Selecciona las herramientas apropiadas entre muchas opciones
- Comprende las descripciones y esquemas de las herramientas
- Orquesta la secuencia correcta
- Maneja los errores mediante reintento
Esto puede funcionar, pero requiere un razonamiento significativo del modelo para cada punto de decisión.
Ruta CLI + SKILL para Flujos de Trabajo Complejos
"Leer hechos → Generar cambios → Validar estructura → Escribir → Ejecutar verificación"El Agente:
- Lee los hechos existentes primero (guiado por SKILL)
- Genera cambios basados en los hechos
- Valida la estructura localmente (cli-schema)
- Escribe en el proyecto
- Ejecuta la verificación (agentHints guía el siguiente paso)
El sistema de ingeniería maneja la validación, la guía y la verificación, reduciendo la carga de razonamiento del modelo.
Ambas rutas pueden completar la tarea. CLI + SKILL reduce la complejidad en la etapa de contexto del modelo.
Lo que Ahora Cubre el CLI
Con la actualización, el CLI ahora 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 de Apidog CLI.
Ya no es simplemente una forma de ejecutar pruebas una vez que todo lo demás está hecho.
Ahora puede participar antes en el ciclo de desarrollo, donde un Agente necesita:
- Comprender el proyecto
- Generar o actualizar activos de prueba
- Validar cambios
- Ejecutar la verificación
Resumen de la Arquitectura
| Dimensión | MCP | CLI + SKILL |
|---|---|---|
| Fuerza 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 completa de recursos + validación |
| Mejor ajuste | Operaciones simples, ecosistema MCP | Flujos de trabajo complejos, CI/CD |
Ambos están disponibles. Elige según tu tarea.
Lo que Sigue
Ahora que hemos establecido cómo CLI + SKILL complementa a MCP, la siguiente pregunta es:
¿Cuál es el principio fundamental que hace que CLI + SKILL sea efectivo para flujos de trabajo complejos?
En la Parte 3, La Regla de Oro: CLI Produce Hechos, el Modelo Actúa sobre los Hechos, exploraremos la filosofía de diseño que guía cada decisión de CLI + SKILL, comenzando con cli-schema validate, la puerta de calidad que detecta errores antes de que se conviertan en escrituras fallidas.
Puntos Clave
- MCP sigue funcionando — úsalo para operaciones simples e integración del ecosistema MCP
- CLI + SKILL complementa a MCP — mejor para flujos de trabajo complejos con validación
- La diferencia clave es dónde reside la complejidad: contexto del modelo vs. sistema de ingeniería
- CLI + SKILL reduce la carga de razonamiento del modelo a través de validación, guía y verificación
- El CLI ahora cubre proyectos, APIs, entornos, casos de prueba, escenarios y más
- Ambos enfoques están disponibles — elige 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.