Esta serie de 10 partes explica 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. Léala en orden o salte a la parte que necesite implementar.
| # | 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 la Nueva Apidog CLI | Desarrollo de arquitectura |
| 3 | La Regla de Oro: La CLI Produce Hechos, el Modelo Actúa sobre Hechos | Filosofía central |
| 4 | agentHints: Enseñando a las CLIs a Hablar con Agentes |
Salida estructurada |
| 5 | HABILIDAD: 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 Bucle de Pruebas: Un Flujo de Trabajo Completo de Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la Compatibilidad 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 |
La facilidad para el agente debe construirse sobre la facilidad para CI/CD. En esta parte veremos cómo apidog run puede servir tanto a pipelines de CI como a Agentes de IA, sin romper la automatización existente.
La audiencia dual
Cuando se construyen herramientas para Agentes de IA, es tentador optimizar solo la experiencia conversacional. Pero una CLI útil para ingeniería también debe funcionar bien en automatización.
Apidog CLI tiene dos audiencias principales:
| Audiencia original | Nueva audiencia |
|---|---|
| Pipelines de CI/CD | Agentes de IA |
| Sistemas de programación externos | Flujos de trabajo conversacionales |
| Scripts y automatización | Tareas impulsadas por el usuario |
Muchos equipos ya ejecutan Apidog en pipelines para:
- Ejecutar pruebas automatizadas de API
- Generar informes
- Mantener puertas de calidad
- Validar cambios antes del despliegue
Ese escenario exige una CLI estable:
| Requisito | Por qué importa |
|---|---|
| Salida estable | Los scripts necesitan resultados predecibles |
| Comandos programables | La ejecución debe poder automatizarse |
| Códigos de salida claros | La pipeline decide éxito o fallo |
| Parámetros configurables | Cada entorno puede requerir valores distintos |
La automatización no debe romperse para acomodar a los Agentes.
Principio principal
La facilidad para el agente debe construirse sobre la facilidad para CI/CD.
No hace falta reinventar un protocolo exclusivo para IA. La estrategia es extender una CLI ya usable por sistemas de ingeniería con:
- Salida estructurada
- Validación de esquema
- Detalles de error
- Sugerencias de próximos pasos para Agentes
Una buena CLI de ingeniería en la era de los Agentes debe servir a varios consumidores:
| Consumidor | Necesidades |
|---|---|
| Humanos | Salida legible, ayuda, funciones interactivas |
| Scripts | Salida estable, comandos programables |
| Pipelines de CI | Códigos de salida, informes, configuración por entorno |
| Agentes de IA | Resultados estructurados, validación, guía accionable |
apidog run: comando central
La base es un comando ejecutable por humanos, scripts, CI y Agentes:
apidog run --project <projectId> \
--test-scenario <scenarioId> \
--environment <environmentId> \
-r "cli,html,junit" \
--out-dir ./apidog-reports
Este comando puede usarse como:
- Paso de pipeline
- Verificación local
- Ejecución automatizada desde un script
- Acción invocada por un Agente de IA
Lo que necesita CI
Para CI/CD, el objetivo es tomar decisiones automáticas y reproducibles.
| Requisito de CI | Característica de CLI |
|---|---|
| Códigos de salida |
0 para éxito, 1 para fallo |
| Archivos de informe | HTML, JUnit, JSON en --out-dir
|
| Parámetros estables | Opciones consistentes entre versiones |
| Ejecuciones configurables | Iteraciones (-n), retrasos (--delay-request), entornos (-e) |
Ejemplo en GitHub Actions
# GitHub Actions
- name: Run API Tests
run: |
apidog run --project $PROJECT_ID \
--test-scenario $SCENARIO_ID \
--environment $ENV_ID \
-r "junit" \
--out-dir ./reports
env:
PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
SCENARIO_ID: ${{ secrets.APIDOG_SCENARIO_ID }}
ENV_ID: production
- name: Publish Test Report
uses: mikepenz/action-junit-report@v3
with:
report_paths: './reports/junit.xml'
El flujo es simple:
- CI ejecuta
apidog run. - La CLI devuelve código de salida.
- La pipeline pasa o falla.
- El informe se publica como artefacto o reporte de pruebas.
Lo que necesitan los Agentes
Para un Agente de IA, no basta con saber si algo falló. Necesita entender qué falló y qué hacer después.
| Requisito del Agente | Característica de CLI |
|---|---|
| Resultados estructurados | Salida JSON con objeto data
|
| Razones de fallo | Detalles específicos en el objeto error
|
| Siguientes pasos |
agentHints con array nextSteps
|
| Validación |
cli-schema validate antes de escrituras |
Ejemplo de salida consumible por un Agente
{
"success": true,
"stats": {
"total": 10,
"passed": 8,
"failed": 2
},
"failures": [
{
"step": "Payment processing",
"error": "Assertion failed: status != 'success'",
"response": {}
}
],
"agentHints": {
"summary": "2 tests failed. Review failure details.",
"nextSteps": [
"Debug the Payment processing step failure.",
"Check assertion: expected status 'success'.",
"Update test case or endpoint after fixing."
]
}
}
El flujo para el Agente sería:
- Ejecutar
apidog run. - Leer la salida JSON.
- Identificar pruebas fallidas.
- Analizar
agentHints.nextSteps. - Aplicar correcciones o pedir confirmación humana.
Mismo comando, diferentes consumidores
apidog run --project <projectId> --out-dir ./apidog-reports
| Consumidor | Qué extrae |
|---|---|
| Pipeline de CI | Código de salida 0/1, ubicación de informes |
| Agente | JSON, agentHints, detalles de fallo |
| Humano | Salida de consola, informe HTML |
| Script | Stdout/stderr, formato configurable |
Un solo comando sirve a todos, siempre que la CLI mantenga contratos estables.
Puntos de integración
Apidog CLI puede integrarse con herramientas comunes de CI/CD usando la misma base: apidog run.
| Herramienta de CI | Integración |
|---|---|
| Jenkins | Pasos de pipeline, publicación de informes |
| GitLab CI | Configuración YAML, artefactos |
| GitHub Actions | Pasos de workflow, secretos |
| CircleCI | Orbs, configuración de workflow |
| Azure DevOps | Tareas de pipeline, resultados de pruebas |
La recomendación práctica es mantener una estructura consistente:
apidog run \
--project "$PROJECT_ID" \
--test-scenario "$SCENARIO_ID" \
--environment "$ENV_ID" \
-r "junit,html" \
--out-dir ./reports
Luego cada sistema de CI puede encargarse de publicar ./reports como artefacto o reporte de pruebas.
Puerta de calidad vs. verificación
El mismo comando tiene significados distintos según el contexto.
| Caso de uso | Significado |
|---|---|
| Puerta de calidad de CI | El éxito o fallo determina si la pipeline continúa |
| Verificación de Agente | El Agente ejecuta pruebas después de hacer cambios |
| Contexto | Cuándo se usa | Propósito |
|---|---|---|
| CI | Después de un push
|
Evitar desplegar código defectuoso |
| Agente | Después de crear o modificar pruebas | Confirmar que el trabajo del Agente es correcto |
Ejemplo de puerta de calidad:
apidog run --project "$PROJECT_ID" \
--test-scenario "$SCENARIO_ID" \
--environment production \
-r "junit" \
--out-dir ./reports
Si el comando devuelve 1, la pipeline falla. Si devuelve 0, continúa.
El principio fundamental
Todo lo descrito en esta serie —cli-schema, agentHints, SKILL— se apoya sobre una base de CLI compatible con CI/CD:
┌────────────────────────────────────────────┐
│ Características del Agente │
│ cli-schema, agentHints, SKILL │
├────────────────────────────────────────────┤
│ Base CI/CD │
│ apidog run, códigos de salida, informes │
├────────────────────────────────────────────┤
│ CLI central │
│ comandos, parámetros, ejecución │
└────────────────────────────────────────────┘
Las características para Agentes no reemplazan las características de CI. Las extienden.
Qué sigue
Ya cubrimos el panorama completo: descubrimiento del problema, diseño de arquitectura, salida estructurada, experiencia operativa, resultados cuantitativos y flujos de trabajo prácticos.
Queda una pieza crítica: la seguridad.
Cuando los Agentes modifican recursos del proyecto, ¿cómo evitamos que afecten directamente la rama principal?
En la Parte 9, Rama de IA: Cambios de Proyecto Más Seguros con Agentes de IA, veremos cómo la Rama de IA proporciona un entorno de edición aislado. Los cambios permanecen en una rama separada hasta la revisión humana, creando una capa de seguridad para modificaciones impulsadas por Agentes.
Puntos clave
- La compatibilidad CI/CD es una base, no una opción.
- La facilidad para Agentes debe construirse sobre la facilidad para CI.
-
apidog runpuede servir a CI, Agentes, humanos y scripts. - CI necesita códigos de salida, informes y parámetros estables.
- Los Agentes necesitan salida estructurada, detalles de fallo y siguientes pasos.
- Puerta de calidad en CI + verificación por Agente = doble propósito.
Descargue Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Aprenda más sobre Apidog CLI para pruebas de API por línea de comandos, automatización de CI y flujos de trabajo de Agentes de IA.
Top comments (0)