agentHints: Cómo enseñar a las CLIs a hablar con agentes

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. Léala en orden o salte a cualquier publicación que le interese:

La salida tradicional de la CLI es para humanos. Los agentes necesitan resultados estructurados, razones de fallas y sugerencias para el siguiente paso. agentHints convierte la experiencia del producto en una guía legible por máquinas.

La Brecha en la Salida de la CLI

La salida tradicional de la CLI está diseñada para humanos.

Esto funciona para las personas. Los humanos pueden:

• Interpretar mensajes vagos
• Decidir qué hacer a continuación
• Recordar el contexto de comandos anteriores
• Aplicar conocimientos del dominio para continuar

Pero los Agentes funcionan de manera diferente.

Lo Que los Agentes Realmente Necesitan

Los Agentes no solo leen los resultados. Necesitan conectar los resultados con la siguiente cadena de tareas.

Un humano ve "Recurso creado con éxito" y sabe: "Probablemente debería verificar qué se creó, y luego quizás ejecutar algunas pruebas."

Un Agente ve "Recurso creado con éxito" y... no tiene idea de qué hacer a continuación.

agentHints: La Solución

Apidog CLI añade agentHints a su salida.

Así es como se ve una respuesta típica:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Caso de prueba creado con éxito.",
    "nextSteps": [
      "Leer el caso de prueba creado para confirmar la estructura.",
      "Añadir aserciones si el caso de prueba necesita validación de respuesta.",
      "Añadir el caso de prueba a un escenario de prueba para pruebas de integración.",
      "Ejecutar pruebas relacionadas después de añadirlo al escenario."
    ]
  }
}

Tres componentes:

El Problema de la Inercia en la Ejecución

Aquí hay un problema real que observamos:

Después de crear un recurso con éxito, el modelo a menudo continúa directamente para generar la siguiente escritura.

Ejemplo:

Agente: Crea caso de prueba
CLI: Devuelve éxito
Agente: Crea inmediatamente escenario de prueba (sin leerlo de vuelta)
Agente: Ejecuta pruebas inmediatamente
Resultado: El escenario tiene una estructura incorrecta, las pruebas fallan

En procesos de negocio complejos, la ejecución continua mecánica no es apropiada.

El enfoque más correcto es a menudo:

1. Crear recurso
2. Leer de vuelta primero
3. Confirmar estructura
4. Luego proceder

Por Qué Es Importante la Lectura Posterior

Omitir la lectura posterior causa problemas reales:

Si la estructura real no se lee de vuelta, el Agente fácilmente continúa escribiendo basándose en su propia suposición, no en datos reales.

agentHints como Navegador

agentHints convierte la experiencia del producto en sugerencias de siguientes pasos legibles por máquinas.

Aparece exactamente donde el Agente necesita tomar decisiones.

Ejemplo después de crear un caso de prueba:

{
  "agentHints": {
    "nextSteps": [
      "Leer de vuelta el caso de prueba creado con la bandera --with-case-detail.",
      "Validar cualquier actualización con cli-schema antes de escribir.",
      "Ejecutar pruebas después de completar el escenario de prueba."
    ]
  }
}

El Agente:

1. Lee la salida
2. Analiza agentHints
3. Sigue nextSteps[0]: lee de vuelta el caso de prueba
4. Confirma la estructura real
5. Luego procede con información precisa

Transformación del Rol de la CLI

Esto cambia lo que significa la CLI en el flujo de trabajo del Agente.

La CLI se convierte en un navegador de estado ligero.

Árboles de Flujo de Trabajo Integrados

Apidog CLI tiene incorporados miles de flujos de trabajo estructurados en árbol.

Estas no son solo sugerencias codificadas. Son:

Ejemplo después de una actualización exitosa del escenario de prueba:

{
  "agentHints": {
    "summary": "Escenario de prueba actualizado con éxito.",
    "nextSteps": [
      "Ejecutar el escenario de prueba para verificar los cambios.",
      "Revisar el informe de prueba para detectar cualquier fallo.",
      "Si ocurren fallos, leer de vuelta los pasos del escenario para depurar."
    ]
  }
}

Ejemplo después de un fallo de validación:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Fallo de validación. Corrige los errores y vuelve a validar.",
    "nextSteps": [
      "Revisar los detalles del error en la salida.",
      "Ajustar el archivo JSON según las sugerencias de error.",
      "Volver a ejecutar cli-schema validate antes de escribir."
    ]
  }
}

Incluso los fallos se vuelven navegables.

El Bucle Más Seguro con agentHints

Tracemos un flujo de trabajo completo con agentHints:

Paso 1: El Agente crea un caso de prueba
        ↓
Salida de la CLI: éxito + agentHints
        ↓
agentHints.nextSteps[0]: "Leer de vuelta el caso de prueba creado"
        ↓
Paso 2: El Agente lee de vuelta (con la estructura real)
        ↓
Salida de la CLI: estructura del caso de prueba + agentHints
        ↓
agentHints.nextSteps[0]: "Añadir aserciones si es necesario"
        ↓
Paso 3: El Agente añade aserciones (basado en la estructura real)
        ↓
Salida de la CLI: éxito + agentHints
        ↓
agentHints.nextSteps[0]: "Ejecutar pruebas"
        ↓
Paso 4: El Agente ejecuta pruebas
        ↓
Salida de la CLI: informe de prueba

Cada paso es guiado. Sin saltos ciegos. Sin suposiciones.

Comparación: Con y Sin agentHints

Qué Sigue

Ahora que la CLI puede guiar a los Agentes a través de los siguientes pasos, la pregunta restante es:

¿Cómo saben los Agentes qué flujo de trabajo seguir en primer lugar?

En la Parte 5, HABILIDAD: Entregando la Experiencia Operacional como Código, exploraremos cómo HABILIDAD empaqueta el conocimiento del flujo de trabajo: cuándo usar comandos, qué secuencia seguir y qué campos no deben adivinarse.

Puntos Clave

• La salida tradicional de la CLI está orientada a los humanos; los Agentes necesitan orientación estructurada
• agentHints proporciona un resumen + sugerencias para el siguiente paso en la salida JSON
• La inercia en la ejecución hace que los Agentes se salten la lectura posterior; agentHints lo evita
• La CLI se transforma de ejecutor a navegador
• Los árboles de flujo de trabajo incorporados hacen que cada paso sea navegable
• Incluso los fallos se vuelven procesables con agentHints

Descargue Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtenga más información sobre Apidog CLI para pruebas de API de línea de comandos, automatización de CI y flujos de trabajo de Agentes de IA.