Esta es una serie de 10 partes sobre 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 la API. Puedes leerla en orden o saltar 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 el nuevo Apidog CLI | Desarrollo de arquitectura |
| 3 | La Regla de Oro: La CLI Produce Hechos, el Modelo Actúa sobre los Hechos | Filosofía central |
| 4 | agentHints: Enseñando a las CLIs 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 de llamadas a herramientas, 25% menos de tokens | Resultados cuantitativos |
| 7 | Del PRD al Bucle de Pruebas: Un Flujo de Trabajo Completo del Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la Compatibilidad con CI/CD No Es Negociable 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 |
No hagas que el modelo memorice todas las reglas. Haz que las reglas se ejecuten en el lugar correcto.
cli-schema validateconvierte el esquema en una puerta de calidad antes de escribir datos reales.
Principio base: las reglas deben ejecutarse donde corresponde
Cuando un Agente de IA trabaja con recursos estructurados, no conviene cargar todo el esquema en el prompt.
La regla práctica es:
No hagas que el modelo memorice todas las reglas. Deja que las reglas se ejecuten en los lugares correctos.
Separar responsabilidades reduce errores, tokens y llamadas innecesarias.
| Tipo de indicador | Dónde pertenece |
|---|---|
| Indicadores deterministas | Scripts, código, validaciones automatizadas |
| Juicios semánticos | LLMs, razonamiento del modelo |
En Apidog CLI + SKILL, esto se traduce así:
| Qué | Dónde |
|---|---|
| Validación estructural determinista | CLI, mediante cli-schema
|
| Juicio, planificación y generación de tareas | Agentes |
En resumen:
La CLI valida estructura. El Agente genera contenido.
El problema: confiar demasiado en la memoria del modelo
Cuando un Agente crea o actualiza recursos de Apidog, el riesgo no está solo en generar texto o JSON.
El riesgo real es este:
Escribir contenido generado en un proyecto real sin validación estructural suficiente.
Los recursos de Apidog tienen estructuras específicas. Un caso de prueba o escenario puede incluir:
| Componente | Complejidad |
|---|---|
| Datos de solicitud | Método, URL, encabezados, cuerpo, autenticación |
| Aserciones | Comparador, sujeto, valor esperado, condiciones |
| Extracción de variables | Nombre de variable, tipo, ruta de extracción |
| Preprocesadores | Scripts antes de la solicitud |
| Postprocesadores | Scripts después de la respuesta |
| Orden de pasos | Secuencia y dependencias |
| Referencias de entorno | ID de entorno y sobrescrituras de variables |
Si el Agente adivina la estructura, pueden aparecer errores como:
- Nombre de campo incorrecto → la escritura falla.
- Valor de enumeración inválido → el servidor rechaza la solicitud.
- Campo requerido faltante → el recurso queda incompleto.
- Tipo incorrecto → puede romper la visualización o ejecución.
- Anidamiento incorrecto → la prueba no se comporta como se espera.
La solución no es pedirle al modelo que recuerde todo. La solución es validar localmente antes de escribir.
cli-schema validate: la puerta de calidad antes de escribir
cli-schema validate permite validar un archivo contra el esquema esperado antes de ejecutar una operación de creación o actualización.
Ejemplo:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Este comando se usa antes de escribir recursos como escenarios o casos de prueba.
La validación comprueba:
- Nombres de campos.
- Estructura del JSON.
- Valores permitidos en enumeraciones.
- Restricciones de tipo.
- Campos requeridos.
- Anidamientos esperados.
Lo importante es que todo ocurre antes de iniciar la solicitud de escritura.
Errores comunes que cli-schema detecta
Estos son ejemplos de errores típicos que un Agente puede generar al construir JSON para pruebas:
| Valor incorrecto | Valor correcto | Contexto |
|---|---|---|
global |
globals |
Tipo de alcance de variable |
contains |
include |
Comparador de aserción |
responseBody |
responseJson |
Sujeto del cuerpo de la respuesta |
"500" |
500 |
Retardo en milisegundos |
equals |
equal |
Comparador de aserción |
header |
headers |
Campo de encabezados de solicitud |
Estos errores no son teóricos. Aparecen en interacciones reales con Agentes.
Sin validación local, cada uno puede provocar:
- Una solicitud de escritura fallida.
- Una respuesta de error de API.
- Confusión del Agente sobre la causa.
- Reintentos innecesarios.
- Consumo extra de tokens.
Con cli-schema validate, el error se detecta localmente, antes de la llamada de red.
Por qué no conviene poner todas las reglas en el prompt
Hay varias formas de intentar resolver este problema. Algunas parecen simples, pero escalan mal.
Alternativa 1: escribir todas las reglas en el prompt
Podrías incluir en el prompt:
- Todos los nombres de campos.
- Todos los valores de enumeración.
- Todas las restricciones de tipo.
- Todas las estructuras anidadas.
El problema es el costo de contexto.
Un esquema completo de escenario de prueba podría ocupar fácilmente miles de tokens. Además, el modelo tendría que cargar ese contexto en cada tarea, incluso cuando solo usa una parte pequeña.
Resultado:
Más contexto, más ruido y más probabilidad de error.
Alternativa 2: confiar en la memoria del modelo
También podrías asumir que el modelo “conoce” la estructura correcta.
Pero los esquemas de producto son específicos:
- Los nombres de campos varían entre herramientas.
- Las enumeraciones no son universales.
- Las convenciones internas no siempre aparecen en datos de entrenamiento.
- Los detalles cambian con el tiempo.
Resultado:
El modelo adivina. Y algunas adivinanzas fallan.
Enfoque recomendado: validar localmente
El flujo correcto es dejar que el Agente genere un borrador y que la CLI lo valide antes de escribir.
# 1. El Agente genera el JSON
# Archivo resultante: ./test-case-create.json
# 2. La CLI valida el archivo contra el esquema esperado
apidog cli-schema validate test-case-create --file ./test-case-create.json
# 3. Si hay errores, el Agente corrige el JSON y vuelve a validar
# 4. Solo si la validación pasa, se escribe el recurso
apidog test-case create --project <projectId> --file ./test-case-create.json
Este patrón mantiene las reglas deterministas fuera del prompt y dentro de la herramienta.
Cómo cambia el rol del esquema
cli-schema validate cambia la forma de usar el esquema.
| Antes | Después |
|---|---|
| El esquema es conocimiento que el modelo debe memorizar | El esquema es una puerta de calidad que debe pasarse |
| Los errores aparecen tras escrituras fallidas | Los errores aparecen mediante validación local |
| El Agente reintenta con llamadas de red | El Agente corrige el archivo localmente |
| El esquema consume contexto | El esquema se ejecuta como validación |
El objetivo es simple:
No gastes solicitudes de red en errores que puedes detectar localmente.
Flujo práctico: crear un caso de prueba con validación
Un flujo típico puede verse así:
# 1. Leer el endpoint existente
apidog endpoint get <endpointId> --project <projectId>
# 2. El Agente genera el archivo JSON del caso de prueba
# Archivo: ./test-case-create.json
# 3. Validar antes de escribir
apidog cli-schema validate test-case-create --file ./test-case-create.json
Si la validación pasa:
apidog test-case create --project <projectId> --file ./test-case-create.json
Si la validación falla, la CLI puede devolver errores específicos como:
Error: El campo "assertions[0].comparator" tiene un valor inválido "contains"
Valores válidos: equal, not_equal, greater, less, include, not_include, exists, not_exists
Error: El campo "extractors[0].type" tiene un valor inválido "global"
Valores válidos: globals, environment, collection, local
Sugerencia: Corrige estos campos y vuelve a validar antes de escribir.
Con esta salida, el Agente puede seguir un ciclo claro:
- Leer los errores.
- Identificar el campo incorrecto.
- Actualizar el JSON.
- Ejecutar de nuevo
cli-schema validate. - Escribir solo cuando el archivo sea válido.
Resultado:
Sin escrituras fallidas. Sin reintentos confusos. Sin tokens desperdiciados en errores evitables.
Patrón de implementación recomendado
Cuando integres Agentes con Apidog CLI, usa este patrón para cualquier operación que escriba datos:
# Generar o actualizar archivo local
# ./resource.json
# Validar contra el esquema correspondiente
apidog cli-schema validate <schema-name> --file ./resource.json
# Escribir solo si la validación es exitosa
apidog <resource> <operation> --project <projectId> --file ./resource.json
Ejemplo para creación de caso de prueba:
apidog cli-schema validate test-case-create --file ./test-case-create.json
apidog test-case create --project <projectId> --file ./test-case-create.json
Ejemplo para actualización de escenario:
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
apidog test-scenario update --project <projectId> --file ./scenario-update.json
La idea es tratar la validación como una etapa obligatoria del pipeline local del Agente.
La lección más amplia
Este principio no aplica solo a esquemas. También ayuda a decidir qué responsabilidad debe tener cada capa.
| Tipo de regla | Dónde pertenece |
|---|---|
| Reglas de nombres de campo | cli-schema |
| Reglas de valores de enumeración | cli-schema |
| Restricciones de tipo | cli-schema |
| Secuencia de flujo de trabajo | SKILL |
| Guía para el siguiente paso | agentHints |
| Descomposición de tareas | Agente |
La división práctica es:
- Reglas deterministas → sistema de ingeniería
- Juicio semántico → Agente
Esto reduce la carga cognitiva del modelo y convierte los errores estructurales en feedback ejecutable.
Qué sigue
Una vez que la CLI valida la estructura, aparece la siguiente pregunta:
Después de la validación, ¿cómo guía la CLI al Agente hacia el siguiente paso?
En la Parte 4, agentHints: Enseñando a las CLIs a Hablar con los Agentes, veremos cómo la salida estructurada con sugerencias transforma una CLI de ejecutor de comandos a navegador de flujo de trabajo.
Puntos clave
- Las reglas deterministas no deberían vivir en el contexto del modelo.
-
cli-schema validateactúa como puerta de calidad antes de escribir. - La validación detecta nombres de campo incorrectos, enumeraciones inválidas y tipos erróneos.
- Detectar errores localmente evita llamadas de red fallidas.
- El esquema pasa de ser “conocimiento a memorizar” a “validación a ejecutar”.
- La división recomendada es: reglas deterministas en ingeniería, juicio semántico en el Agente.
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 de línea de comandos, automatización CI y flujos de trabajo de Agentes de IA.
Top comments (0)