La Regla de Oro: CLI genera datos, el modelo se basa en datos

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 la API. Lee en orden o salta a cualquier publicación que te interese:

No hagas que el modelo memorice todas las reglas; deja que las reglas se ejecuten en los lugares correctos. cli-schema validate convierte el esquema de conocimiento en una puerta de calidad.

El Principio Fundamental: Que las Reglas se Ejecuten en los Lugares Correctos.

Destilamos un principio fundamental de nuestra experiencia:

No hagas que el modelo memorice todas las reglas. Deja que las reglas se ejecuten en los lugares correctos.

Esto es similar a una lección de la evaluación del Agente:

En Apidog CLI + SKILL:

Deja que la CLI valide la estructura. Deja que los Agentes generen contenido.

El Problema con la Memoria del Modelo

Cuando un Agente de IA ayuda a crear o actualizar recursos de Apidog, la parte arriesgada no es solo generar contenido.

La parte arriesgada es escribir contenido generado en un proyecto real sin suficiente estructura o verificación.

Los recursos de Apidog están estructurados. Considera lo que incluye un caso de prueba o un escenario de prueba:

Si un Agente adivina la estructura:

• Nombre de campo incorrecto → Escritura fallida
• Valor de enumeración inválido → Rechazo del servidor
• Campo requerido faltante → Recurso incompleto
• Tipo incorrecto → Problemas de visualización en la interfaz de usuario
• Anidamiento incorrecto → Las pruebas no se comportan como se espera

cli-schema validate: La Puerta de Calidad

La encarnación más directa de nuestro principio es cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Cuando un Agente quiere escribir o actualizar un escenario de prueba, hacer que la IA genere estructuras de pasos complejas es muy propenso a errores.

El comando validate:

• Confirma los nombres de los campos
• Verifica la validez estructural
• Verifica la efectividad del valor de enumeración
• Valida las restricciones de tipo

Todo antes de iniciar la solicitud de escritura.

Errores Comunes que cli-schema Detecta

Aquí tienes ejemplos reales de errores que los Agentes suelen cometer, y que cli-schema validate detecta:

Estos no son teóricos. Los descubrimos a través de interacciones reales del Agente.

Cada error causaría:

• Una solicitud de escritura fallida
• Una respuesta de error de API
• Confusión del Agente sobre qué salió mal
• Múltiples intentos de reintento
• Gasto de tokens en llamadas repetidas

Con cli-schema validate, estos errores se detectan localmente, antes de la llamada de red.

La Filosofía de Diseño

Consideremos las alternativas:

Alternativa 1: Escribir Reglas en el Prompt

Si escribiéramos todas las reglas de campo en el prompt del Agente:

• Cada nombre de campo documentado
• Cada valor de enumeración listado
• Cada restricción de tipo explicada
• Cada estructura anidada descrita

Resultado: Enorme carga de contexto.

Un esquema de escenario de prueba completo podría requerir fácilmente más de 5,000 tokens de descripción. Ese es un contexto que el modelo debe llevar para cada tarea, incluso cuando la mayoría de las reglas no son relevantes.

Alternativa 2: Confiar en la Memoria del Modelo

Si confiamos en que el modelo "conozca" la estructura correcta:

• Modelo entrenado en algunos patrones de API
• Pero no específicamente en esquemas de Apidog
• Los nombres de los campos varían entre productos
• Los valores de enumeración son específicos del producto

Resultado: Altas tasas de error.

El modelo no tiene una memoria perfecta de las convenciones específicas de Apidog. Adivinará, y las adivinanzas serán incorrectas.

Mejor Enfoque: Validar Localmente

Deja que el Agente genere borradores. Deja que la CLI ejecute la validación antes de escribir.

# El Agente genera JSON
# (El Agente no necesita memorizar todas las reglas)

# La CLI valida
apidog cli-schema validate test-case-create --file ./test-case-create.json

# La CLI muestra errores específicos si los hay
# El Agente se ajusta según los errores

# Solo se procesan escrituras válidas
apidog test-case create --project <projectId> --file ./test-case-create.json

Transformación del Esquema

cli-schema validate transforma lo que significa el Esquema:

Los problemas no se consumen en solicitudes de red de ida y vuelta sin sentido.

Las verificaciones de calidad se completan mediante comandos locales.

Ejemplo Práctico

Vamos a repasar un flujo de trabajo real:

# El Agente lee el endpoint
apidog endpoint get <endpointId> --project <projectId>

# El Agente genera JSON del caso de prueba
# (Crea ./test-case-create.json)

# 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:

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.

El Agente:

1. Lee los errores específicos
2. Comprende exactamente qué está mal
3. Ajusta el archivo JSON
4. Vuelve a ejecutar la validación
5. Procede solo cuando es válido

Sin escrituras fallidas. Sin reintentos confusos. Sin tokens desperdiciados.

La Lección Más Amplia

Este principio se extiende más allá de la validación.

Reglas deterministas → Sistema de ingeniería

Juicio semántico → Agente

Qué Sigue

Ahora que hemos establecido el principio de validación, la siguiente pregunta es:

Después de la validación, ¿cómo guía la CLI al Agente al siguiente paso?

En la Parte 4, agentHints: Enseñando a las CLIs a Hablar con los Agentes, exploraremos cómo la salida estructurada con sugerencias para el siguiente paso transforma la CLI de un ejecutor de comandos en un navegador de flujo de trabajo.

Puntos Clave

• Principio fundamental: las reglas pertenecen a la ejecución, no al contexto
• cli-schema validate es la puerta de calidad antes de escribir
• Errores comunes: nombres de campo incorrectos, enumeraciones inválidas, tipos incorrectos
• La validación detecta errores localmente, ahorrando viajes de ida y vuelta a la red
• El esquema se transforma de "conocimiento a memorizar" a "puerta a pasar"
• Reglas deterministas → ingeniería; juicio semántico → 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.