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 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 Agentes | Descubrimiento de problemas |
| 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 CLIs a Hablar con Agentes |
Salida estructurada |
| 5 | SKILL: Enviando Experiencia Operativa como Código | Experiencia operativa |
| 6 | Los Números No Mienten: 30% Menos Llamadas a Herramientas, 25% Menos Tokens | Resultados cuantitativos |
| 7 | Del PRD al Ciclo de Pruebas: Un Flujo de Trabajo Completo de Agentes con Apidog CLI | Tutorial práctico |
| 8 | Por Qué la Compatibilidad CI/CD Es Innegociable para Herramientas de Agentes | Perspectiva DevOps |
| 9 | AI Branch: 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 126 Herramientas MCP. Luego Descubrimos Que No Es la Mejor Solución para Trabajar en Desarrollo de API con Agentes.
Cuando MCP (Model Context Protocol) se convirtió en el punto de interés de la industria a principios de 2025, la pregunta que enfrentaba cada producto de API era simple: "¿Tienen MCP?"
Para Apidog, respondimos que sí. Construimos un MCP Server completo—no solo una simple demostración. El cliente MCP inicializaría una sesión, el servidor generaría un sessionId, y guardaría el estado de la sesión a través de Redis. Era un sistema de sesión a nivel de protocolo. Dividimos las herramientas en categorías: herramientas nativas del proyecto, herramientas de dominio integradas, y 126 herramientas generadas automáticamente convertidas desde definiciones de endpoints OpenAPI.
Apidog MCP continúa funcionando y sirviendo a usuarios que necesitan integración MCP. Proporciona conexiones de herramientas estandarizadas siguiendo el protocolo MCP, lo cual es valioso para el ecosistema.
Pero cuando entramos en tareas reales que involucran flujos de trabajo de I+D complejos, descubrimos limitaciones. Cuando un usuario dice "ayúdame a agregar una prueba para este endpoint y ejecutar la verificación", el Agente enfrenta un muro de herramientas aleatorias—decidiendo cuál usar, en qué secuencia, con qué validación.
Nos dimos cuenta: MCP sobresale en conectar herramientas, pero las tareas complejas de I+D necesitan más que conexión de herramientas—necesitan procesos de ingeniería ejecutables.
Esa percepción nos llevó a desarrollar Apidog CLI como un mejor enfoque—uno que maneja mejor los flujos de trabajo de desarrollo.
¿Qué es Apidog CLI?
Apidog CLI es una herramienta de línea de comandos para pruebas de API que te permite ejecutar escenarios de prueba, gestionar documentación de API, y automatizar flujos de trabajo de pruebas directamente desde tu terminal o pipelines CI/CD. Construido específicamente para que agentes de IA gestionen recursos de API, va más allá del CLI tradicional para pruebas de API—proporcionando salida estructurada, validación de esquemas, y orientación de próximos pasos que los agentes necesitan para ejecutar flujos de trabajo complejos de manera segura. Ya sea que estés ejecutando pruebas de API automatizadas en GitHub Actions, generando casos de prueba desde código con Claude Code, o manteniendo escenarios de prueba entre proyectos, Apidog CLI sirve como el puente entre los agentes de IA y tu infraestructura de pruebas de API.
Inicio Rápido: Prueba Apidog CLI + SKILL
Si quieres probar el enfoque descrito en esta serie, aquí te explicamos cómo empezar:
# 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
O pide a tu Agente de IA que lo instale:
Read the instructions and help me install Apidog CLI:
Tu Primera Tarea con el Agente
Después de la instalación, asigna a tu Agente una tarea pequeña y de bajo riesgo:
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
Esto te da un punto de partida concreto: el Agente verifica la configuración, pregunta antes de escribir, crea una pequeña definición de API, valida antes de escribir, y confirma el resultado guardado.
La Arquitectura Central
| Capa | Responsabilidad |
|---|---|
| Apidog | Gestiona recursos de API y pruebas (docs, esquemas, mocks, pruebas, reportes) |
| CLI | Proporciona ejecución determinista (read, validate, write, run) |
| SKILL | Proporciona juicio de tareas y rutas de operación (8 Skills complementarios) |
| AI Branch | Isola cambios para revisión humana antes de merge |
| Agents | Entienden objetivos, llaman comandos, ajustan basándose en retroalimentación |
El Ciclo Más Seguro para Pruebas Dirigidas por Agentes
Con AI Branch como la capa de seguridad exterior, el flujo de trabajo completo se ve así:
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (Capa de Seguridad) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 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) │ │
│ └──────────────────────────────────────┘ │
Este ciclo es importante porque muchos recursos de Apidog están estructurados. Los casos de prueba y escenarios de prueba incluyen datos de solicitud, assertions, extracción de variables, pre/post procesadores, orden de pasos, y referencias de entorno. Si un Agente adivina la estructura, pequeños errores causan escrituras fallidas, visualización incompleta, o pruebas que no funcionan como se espera.
Deja que el Agente genere, deja que el CLI valide, y deja que AI Branch isole los cambios hasta la revisión humana.
Resumen del Viaje de Apidog CLI
Esta serie documenta cómo desarrollamos Apidog CLI como una mejor estrategia para flujos de trabajo de I+D de API.
Apidog MCP continúa proporcionando conexiones de herramientas estandarizadas—eso es valioso y lo mantenemos. Pero para tareas que involucran flujos de trabajo de múltiples pasos, puertas de validación, y ejecución estructurada, encontramos que CLI + SKILL ofrece una mejor experiencia.
No solo agregamos comandos al CLI antiguo, donde los usuarios ejecutaban pruebas de API automáticas integrando con su CI/CD. Introdujimos sistemáticamente las capacidades centrales de Apidog en el CLI, haciéndolo una capa de flujo de trabajo para desarrolladores, scripts, y Agentes de IA.
La diferencia clave es dónde vive la complejidad:
- Ruta MCP: Complejidad en el contexto del modelo y etapa de selección de herramientas—genial para llamadas de herramientas simples
- Ruta CLI + SKILL: Complejidad distribuida en el sistema de ingeniería—mejor para flujos de trabajo más avanzados
El resultado: flujos de trabajo de Agentes más seguros para tareas complejas, menos llamadas de herramientas, menos desperdicio de tokens, y mejor recuperación de errores—mientras MCP sigue disponible para usuarios que prefieren ese enfoque.
El Mapa del Viaje de 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 │
│ └────┘ │
│ │
Navegación Rápida del Viaje
Parte 1: Descubrimiento del Problema
MCP proporciona conexiones de herramientas estandarizadas—pero para flujos de trabajo de I+D complejos, descubrimos limitaciones. Los Agentes enfrentaban un muro de herramientas aleatorias cuando las tareas involucraban procesos de múltiples pasos. Este post explora cuatro desafíos estructurales y por qué CLI + SKILL son mejores para tareas con flujos de trabajo pesados.
Parte 2: Desarrollo de Arquitectura
2. Por Qué Desarrollamos un Apidog CLI Completamente Nuevo
No abandonamos MCP—construimos CLI + SKILL para manejar lo que MCP no optimiza: flujos de trabajo complejos con puertas de validación y ejecución estructurada. Este post compara cadenas de ejecución y explica cómo CLI + SKILL distribuye la complejidad en el sistema de ingeniería mientras MCP sigue sirviendo su propósito.
Parte 3: Filosofía Central
3. La Regla de Oro: CLI Produce Hechos, el Modelo Actúa Sobre los Hechos
El principio central: no hagas que el modelo memorice todas las reglas—deja que las reglas se ejecuten en los lugares correctos. Este post introduce `cli-schema validate`, la puerta de calidad que detecta errores de campos, enums incorrectos, y problemas estructurales antes de que se conviertan en escrituras fallidas.
Partes 4-5: Diseño Técnico
4. agentHints: Enseñando a los CLIs a Hablar con Agentes
La salida tradicional del CLI es para humanos. Los Agentes necesitan resultados estructurados, razones de fallos, y sugerencias de próximos pasos. `agentHints` convierte la experiencia del producto en guía machine-readable—apareciendo exactamente donde los Agentes necesitan hacer decisiones.
5. SKILL: Enviando Experiencia Operativa como Código
Un SKILL no es solo una referencia de comandos. Es una guía operativa para Agentes de IA: cuándo usar un comando, cuál viene primero, qué campos no deben ser adivinados, cuándo validar, cuándo leer de vuelta. SKILL empaqueta conocimiento de flujos de trabajo en guías versionables, evolucionables.
Partes 6-7: Validación y Práctica
6. Los Números No Mienten: 30% Menos Llamadas a Herramientas, 25% Menos Tokens
Comparamos MCP vs. CLI + SKILL en tareas típicas. Los pasos de llamadas de herramientas disminuyeron ~30%. El consumo de tokens de descripciones inválidas y reintentos disminuyó ~25%. Los reintentos de errores estructurales disminuyeron ~40%. Este post desglosa dónde provienen los ahorros.
7. Del PRD al Ciclo de Pruebas: Un Flujo de Trabajo Completo de Agentes con Apidog CLI
Atraviesa un ejemplo real: un equipo tiene un PRD de Order Refund y base de código. Ve cómo un Agente usa CLI + SKILL para generar OpenAPI, crear casos de prueba, validar estructuras, construir escenarios de prueba, y ejecutar verificación—end to end.
Partes 8-9: Fundación y Seguridad
8. Por Qué la Compatibilidad CI/CD Es Innegociable para Herramientas de Agentes
La amigabilidad para Agentes debe construirse sobre amigabilidad para CI/CD. `apidog run` sirve a ambos: CI importa sobre códigos de salida, archivos de reporte, parámetros estables; Agents importan sobre resultados estructurados, razones de fallos, sugerencias de próximos pasos. Un comando, múltiples consumidores.
9. AI Branch: Cambios de Proyecto Más Seguros con Agentes de IA
Cuando los Agentes modifican recursos del proyecto, la seguridad importa. AI Branch proporciona edición isolada—los cambios permanecen en una branch separada hasta la revisión humana. Esto previene que los cambios automáticos afecten directamente la branch principal. Crea, revisa, luego merge con confianza.
Parte 10: Visión y Futuro
10. Spec-First Fue Ayer. Bienvenido a Skill-First.
El desarrollo de API está cambiando con Agentes de IA uniéndose al flujo de trabajo. Spec-First fue para colaboración humana. Skill-First empaqueta specs, pruebas, y escenarios en skills ejecutables, verificables—complementando enfoques existentes para la era de Agentes. Este post delinea el futuro y proporciona pasos concretos para empezar.
Conclusiones Clave (TL;DR)
| Insight | Qué Significa |
|---|---|
| MCP y CLI + SKILL sirven diferentes necesidades | MCP conecta herramientas; CLI + SKILL ejecuta flujos de trabajo—usa lo que se ajuste a tu tarea |
| La complejidad pertenece a la ingeniería, no al contexto | 126 herramientas × 500 tokens = 50,000 tokens de carga para flujos de trabajo complejos |
| `cli-schema validate` es la puerta de calidad | Detecta errores localmente, no mediante escrituras fallidas |
| `agentHints` guía los próximos pasos | Evita que los Agentes escriban basándose en "imaginación" |
| SKILL empaqueta experiencia operativa | No solo comandos—sabiduría de flujos de trabajo para Agentes |
| CI/CD sigue siendo la base | Características de Agentes añadidas encima, no reemplazando CI |
| AI Branch proporciona capa de seguridad | Edición isolada + revisión humana antes de merge |
Comienza a Leer
¿Listo para empezar? Comienza con Post 1: Construimos 126 Herramientas MCP. Luego Descubrimos Una Mejor Solución para Flujos de Trabajo.
Descarga Apidog para diseñar, mock, probar, y documentar APIs en un espacio de trabajo. Conoce más sobre Apidog CLI para pruebas de API en línea de comandos, automatización CI y flujos de trabajo de Agentes de IA.