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. Lea en orden o salte a cualquier publicación que le 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 el Nuevo Apidog CLI | 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 los Agentes |
Salida estructurada |
| 5 | SKILL: 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 Ciclo de Pruebas: Un Flujo de Trabajo Completo de Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la Compatibilidad CI/CD es Innegociable para las Herramientas de 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 |
Comparamos MCP vs. CLI + SKILL en tareas típicas de usuario. Los resultados: menos llamadas a herramientas, menos desperdicio de tokens, mejor recuperación de errores, y los datos explican por qué.
La Pregunta que Importa
Toda la filosofía y principios de diseño que hemos compartido, ¿realmente funcionan?
Comparamos internamente muchas tareas típicas de usuario en ambos enfoques:
| Tipo de Tarea | Descripción |
|---|---|
| Agregar caso de prueba + verificación | Crear caso de prueba para el endpoint, ejecutar pruebas |
| Mantener escenarios de prueba | Actualizar escenarios complejos de varios pasos |
| Importar/verificar activos del proyecto | Importar datos, confirmar estructura, ejecutar pruebas |
Los resultados no fueron solo mejoras subjetivas. Fueron reducciones medibles.
Tarea 1: Agregar Caso de Prueba Basado en el Endpoint
Solicitud del usuario:
"Agregar una prueba para este endpoint y ejecutar la verificación"
Ruta MCP
| Etapa | Lo que Sucede |
|---|---|
| Descubrimiento de herramientas | El agente busca en la lista de herramientas |
| Selección de herramientas | Varias rondas de selección de la herramienta correcta |
| Descubrimiento de campos | El agente lee el esquema de la herramienta |
| Adivinación de campos | El agente adivina los campos requeridos |
| Intento de escritura | El agente llama a la herramienta de creación |
| Respuesta de error | El servidor rechaza (campo incorrecto/faltante requerido) |
| Reintento | El agente ajusta, lo intenta de nuevo |
| Más reintentos | Repetir hasta el éxito |
| Ejecutar pruebas | El agente encuentra la herramienta de ejecución, ejecuta |
Patrón típico:
Buscar herramientas → Seleccionar herramienta → Leer esquema → Adivinar campos → Escribir → Error → Reintentar → Escribir → Error → Reintentar → Éxito → Encontrar herramienta de ejecución → EjecutarRuta CLI + SKILL
| Etapa | Lo que Sucede |
|---|---|
| Guía SKILL | SKILL identifica el tipo de tarea, proporciona el flujo de trabajo |
| Leer endpoint | CLI lee los hechos del endpoint |
| Generar caso de prueba | El agente genera basándose en los datos reales del endpoint |
| Validar localmente | cli-schema valida antes de escribir |
| Escribir | CLI crea el caso de prueba |
| Lectura de retorno | CLI devuelve la estructura creada + agentHints |
| Ejecutar pruebas | agentHints sugiere ejecutar, el Agente sigue |
Patrón típico:
SKILL guía → Leer endpoint → Generar → Validar → Escribir → Leer de vuelta → EjecutarResultados
| Métrica | Ruta MCP | CLI + SKILL | Mejora |
|---|---|---|---|
| Pasos de llamada a herramientas | ~15-20 | ~10-12 | ↓ ~30% |
| Tokens de descripciones | ~50,000 cargados | ~2,000 cargados | ↓ ~96% |
| Tokens de reintentos | ~5,000+ desperdicio | ~500 desperdicio | ↓ ~90% |
| Desperdicio total de tokens | ~55,000 | ~2,500 | ↓ ~25% |
Los pasos de llamadas a herramientas disminuyeron en aproximadamente un 30%. El consumo de tokens por descripciones de herramientas no válidas y reintentos de error disminuyó en aproximadamente un 25%.
Tarea 2: Escrituras Estructuradas (Procesador, Aserción, Extractor)
Solicitud del usuario:
"Agregar aserciones post-operación y extracción de variables a este caso de prueba"
Ruta MCP
| Etapa | Lo que Sucede |
|---|---|
| Adivinar nombres de campos | El agente no conoce los nombres exactos |
| Adivinar valores de enumeración | El agente adivina el comparador, el tipo |
| Intento de escritura | El servidor rechaza valores incorrectos |
| Reintento de red | Ida y vuelta por cada error |
| Múltiples intentos | 3-5 reintentos son comunes |
Errores comunes:
| Suposición Incorrecta | Valor Correcto | Recuento de Reintentos |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Cada error = 1 ida y vuelta de red + respuesta + procesamiento del Agente.
Ruta CLI + SKILL
| Etapa | Lo que Sucede |
|---|---|
| Leer caso de prueba | CLI obtiene la estructura real |
| Generar adiciones | El agente genera basándose en el formato real |
| Validar localmente | cli-schema detecta errores antes de la red |
| Corregir localmente | El agente ajusta basándose en la salida de validación |
| Volver a validar | Confirmar la corrección |
| Escribir | Solo las escrituras válidas van al servidor |
Todos los errores detectados localmente. Sin reintentos de red por errores de campo.
Resultados
| Métrica | Ruta MCP | CLI + SKILL | Mejora |
|---|---|---|---|
| Reintentos de red por errores estructurales | 3-5 | 0 | ↓ ~100% |
| Tokens de respuestas de error | ~2,000 | ~0 | ↓ ~100% |
| Total de llamadas repetidas | ~5 | ~1 | ↓ ~40% |
Las llamadas repetidas por errores estructurales disminuyeron en aproximadamente un 40%.
Tarea 3: Operaciones Continuas Después de Crear
Solicitud del usuario:
"Crear un escenario de prueba con estos endpoints"
Ruta MCP
| Etapa | Lo que Sucede |
|---|---|
| Crear escenario | El agente llama a la herramienta de creación |
| Respuesta de éxito | El agente ve "creado" |
| Continuar escribiendo | El agente actualiza/agrega más inmediatamente |
| Omitir lectura de retorno | El agente no lee la estructura real |
| Escribir basado en suposiciones | El agente escribe con IDs/estructura adivinados |
| Error o incompleto | El resultado no coincide con la expectativa |
Problema: Inercia de ejecución.
El modelo tiende a continuar directamente después del éxito, omitiendo el paso de lectura de retorno.
Ruta CLI + SKILL
| Etapa | Lo que Sucede |
|---|---|
| Crear escenario | CLI crea el escenario |
| Éxito + agentHints | CLI devuelve éxito + sugerencias para el siguiente paso |
agentHints: "Leer de vuelta primero" |
El agente ve la sugerencia |
| Seguir sugerencia | El agente lee de vuelta |
| Trabajar con la estructura real | El agente procede con datos precisos |
agentHints sugiere explícitamente la lectura de retorno. El agente sigue.
Resultados
| Métrica | Ruta MCP | CLI + SKILL | Mejora |
|---|---|---|---|
| Proporción que lee de vuelta antes de continuar | ~20% | ~85% | ↑ ~425% |
| Reintentos de error por saltos directos | ~3-5 | ~0-1 | ↓ ~21% |
La proporción de Agentes que leen de vuelta, validan y ejecutan la verificación de forma proactiva aumentó significativamente. Los reintentos de error por saltar directamente al siguiente paso disminuyeron en aproximadamente un 21%.
Resumen: De Dónde Vienen los Ahorros
| Fuente de Ahorro | Explicación |
|---|---|
| Descubrimiento de herramientas | Los comandos CLI tienen nombres claros; SKILL guía la selección |
| Validación de esquemas | La validación local detecta errores antes de la llamada de red |
| Recuperación de errores | agentHints proporciona sugerencias accionables, no solo "fallido" |
| Guía de lectura de retorno | Evita escrituras basadas en suposiciones |
| Secuencia de flujo de trabajo | SKILL reduce los puntos de decisión |
El Análisis Real de Costos
Idea clave:
La habilitación de productos por parte de los agentes no se trata de cuantas más herramientas, mejor.
Lo que el modelo realmente consume:
| Tipo de Costo | Carga MCP | Carga CLI + SKILL |
|---|---|---|
| Contexto | Descripciones de herramientas, esquemas | SKILL centrado en la tarea solamente |
| Atención | Seleccionar entre muchas herramientas | Seguir un flujo de trabajo guiado |
| Selección de ruta | Adivinar secuencias | Secuencia definida por SKILL |
| Costos de tokens de usuario | Reintentos, llamadas fallidas | Escrituras validadas, menos llamadas |
Después de que el recuento de herramientas aumenta, lo que el modelo realmente consume no es la capacidad de llamada a la API, sino las compensaciones entre el contexto, la atención, la selección de ruta y los costos de tokens de usuario.
El Principio de Ingeniería
Objetivo:
Mover estos costos fuera del contexto del modelo y devolverlos a las posiciones que el sistema de ingeniería puede soportar.
| Costo | Ubicación MCP | Ubicación CLI + SKILL |
|---|---|---|
| Descubrimiento de herramientas | El modelo debe buscar | SKILL proporciona |
| Validación de campos | El modelo debe saber | cli-schema valida |
| Guía del siguiente paso | El modelo debe decidir | agentHints sugiere |
| Semántica del producto | El modelo debe entender | CLI maneja |
El sistema de ingeniería absorbe la complejidad. El modelo se centra en la generación y el juicio.
Lo que Significan Estos Números
Los números explican un problema más específico:
| Percepción | Implicación |
|---|---|
| 30% menos llamadas a herramientas | Complejidad movida del descubrimiento a la guía |
| 25% menos tokens desperdiciados | Errores detectados antes de la red |
| 40% menos reintentos estructurales | La puerta de validación funciona |
| 21% menos errores de salto | agentHints previene la continuación ciega |
CLI + SKILL no es solo elegancia arquitectónica. Es eficiencia medible.
Qué Sigue
Ahora que hemos validado el enfoque con números, veámoslo en acción.
En la Parte 7, De PRD al Ciclo de Pruebas: Un Flujo de Trabajo Completo de Agente, recorreremos un ejemplo real: un equipo tiene un PRD de "Reembolso de Pedido", y el Agente utiliza CLI + SKILL para generar OpenAPI, crear pruebas, validar y verificar.
Puntos Clave
- Los pasos de llamada a herramientas disminuyeron en ~30%
- El desperdicio de tokens por descripciones y reintentos disminuyó en ~25%
- Los reintentos por errores estructurales disminuyeron en ~40%
- Los errores de salto por omitir la lectura de retorno disminuyeron en ~21%
- Los ahorros provienen de: descubrimiento guiado, validación local, sugerencias accionables
- La complejidad se trasladó del contexto al sistema de ingeniería
Descarga Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Aprende más sobre Apidog CLI para pruebas de API de línea de comandos, automatización CI y flujos de trabajo de Agente de IA.