DEV Community

Cover image for agentHints: Cómo enseñar a las CLIs a hablar con agentes
Roobia
Roobia

Posted on • Originally published at apidog.com

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

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. Puede leerla en orden o saltar a la publicación que más le interese:

Prueba Apidog hoy

# 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 un Apidog CLI Completamente Nuevo Desarrollo de la 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: Entregando la Experiencia Operacional como Código Experiencia operacional
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 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

La salida tradicional de la CLI está pensada para humanos. Los agentes necesitan resultados estructurados, razones de fallo y sugerencias para decidir 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 mayoría de CLIs siguen un patrón simple:

Éxito Fallo
Imprimir "Éxito" o "Hecho" Imprimir un mensaje de error
Mostrar, quizá, el recurso creado Mostrar, quizá, el stack trace
El humano interpreta el resultado El humano depura el problema

Esto funciona cuando la persona que ejecuta el comando puede:

  • Interpretar mensajes ambiguos.
  • Decidir qué hacer después.
  • Recordar el contexto de comandos anteriores.
  • Aplicar conocimiento del dominio.

Pero un agente no debería depender de inferencias implícitas. Necesita una salida que pueda analizar y usar para continuar el flujo de trabajo.

Lo que los agentes realmente necesitan

Un agente no solo “lee” resultados. Debe conectar cada resultado con la siguiente acción.

Necesidad del agente Por qué importa
Resultados estructurados La salida debe poder analizarse programáticamente
Razones de fallo El agente necesita detalles concretos, no errores genéricos
Sugerencias para el siguiente paso El agente necesita saber qué acción ejecutar después

Un humano ve:

Recurso creado con éxito
Enter fullscreen mode Exit fullscreen mode

Y puede pensar:

Debería verificar qué se creó y luego ejecutar pruebas.
Enter fullscreen mode Exit fullscreen mode

Un agente, en cambio, puede continuar con una escritura nueva sin comprobar el estado real del recurso.

agentHints: la solución

Apidog CLI añade agentHints a su salida para guiar al agente después de cada operación.

Una respuesta típica puede verse así:

{
  "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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

La estructura separa tres responsabilidades:

Campo Propósito
success + data Resultado real de la operación
agentHints.summary Resumen breve del estado
agentHints.nextSteps Acciones sugeridas para continuar

Para un flujo automatizado, el agente puede hacer algo tan directo como:

const result = JSON.parse(cliOutput)

if (result.success && result.agentHints?.nextSteps?.length) {
  const nextAction = result.agentHints.nextSteps[0]
  console.log(`Siguiente acción sugerida: ${nextAction}`)
}
Enter fullscreen mode Exit fullscreen mode

El problema de la inercia en la ejecución

Un problema frecuente en flujos con agentes es la ejecución mecánica continua.

Ejemplo:

Agente: Crea caso de prueba
CLI: Devuelve éxito
Agente: Crea inmediatamente un escenario de prueba sin leer el caso creado
Agente: Ejecuta pruebas
Resultado: El escenario tiene una estructura incorrecta y las pruebas fallan
Enter fullscreen mode Exit fullscreen mode

En procesos de negocio complejos, no basta con encadenar escrituras. El flujo más seguro suele ser:

  1. Crear el recurso.
  2. Leerlo de vuelta.
  3. Confirmar la estructura real.
  4. Continuar con la siguiente operación.

Por qué es importante leer de vuelta

Omitir la lectura posterior puede introducir errores difíciles de depurar.

Problema Causa
Valores predeterminados incorrectos El servidor completa campos que el agente no especificó
IDs asociados faltantes La importación puede generar nuevos IDs internos
Variantes estructurales El frontend o el backend pueden depender de un formato específico
Suposiciones incorrectas El agente continúa basándose en una estructura imaginada

Si el agente no lee la estructura real, puede escribir el siguiente recurso usando datos incompletos o incorrectos.

agentHints como navegador

agentHints convierte conocimiento operativo en instrucciones legibles por máquinas.

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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Un agente puede seguir este patrón:

  1. Ejecutar el comando.
  2. Analizar la salida JSON.
  3. Leer agentHints.nextSteps.
  4. Ejecutar la primera acción sugerida.
  5. Continuar usando datos reales, no suposiciones.

Ejemplo de pseudoflujo:

create-test-case
  -> leer agentHints.nextSteps[0]
  -> get-test-case --with-case-detail
  -> validar estructura
  -> actualizar caso o añadirlo a un escenario
Enter fullscreen mode Exit fullscreen mode

Cambio de rol de la CLI

Con agentHints, la CLI deja de ser solo una interfaz de ejecución.

Rol anterior Nuevo rol
Ejecutar comandos Navegar flujos de trabajo
Imprimir resultados Guiar el siguiente paso
Salida para humanos Salida estructurada para agentes
Respuesta única Orientación continua

La CLI se convierte en un navegador de estado ligero para flujos automatizados.

Árboles de flujo de trabajo integrados

Apidog CLI incorpora miles de flujos de trabajo estructurados en árbol. Estas sugerencias no son mensajes genéricos: dependen del contexto de la operación.

Característica Descripción
Sensible al contexto Las sugerencias coinciden con la operación ejecutada
Específico del recurso Hay sugerencias distintas para endpoints, casos de prueba y escenarios
Sensible al flujo de trabajo Las sugerencias reflejan secuencias típicas
Informado por errores El siguiente paso cambia según éxito o fallo

Ejemplo después de actualizar correctamente un 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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Así, incluso los fallos se vuelven accionables.

Un bucle más seguro con agentHints

Un flujo completo puede modelarse así:

Paso 1: El agente crea un caso de prueba
        ↓
Salida de la CLI: success + data + agentHints
        ↓
agentHints.nextSteps[0]: "Leer de vuelta el caso de prueba creado"
        ↓
Paso 2: El agente lee el caso de prueba real
        ↓
Salida de la CLI: estructura real + agentHints
        ↓
agentHints.nextSteps[0]: "Añadir aserciones si es necesario"
        ↓
Paso 3: El agente añade aserciones usando la estructura real
        ↓
Salida de la CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Ejecutar pruebas"
        ↓
Paso 4: El agente ejecuta pruebas
        ↓
Salida de la CLI: informe de prueba
Enter fullscreen mode Exit fullscreen mode

El punto clave: cada transición está guiada. No hay saltos ciegos ni dependencias en datos imaginados.

Comparación: con y sin agentHints

Escenario Sin agentHints Con agentHints
Después de crear El agente continúa con la siguiente escritura El agente lee de vuelta primero
Después de actualizar El agente asume que todo está correcto El agente verifica la estructura
Después de pasar la validación El agente escribe inmediatamente El agente escribe y luego lee de vuelta
Después de fallar la validación El agente puede no saber cómo corregir El agente recibe pasos específicos
Después de ejecutar pruebas El agente solo ve aprobado/fallido El agente recibe orientación para depurar

Patrón de implementación recomendado

Si está diseñando una CLI para agentes, puede adoptar una estructura similar:

{
  "success": true,
  "data": {},
  "agentHints": {
    "summary": "",
    "nextSteps": []
  }
}
Enter fullscreen mode Exit fullscreen mode

Para errores:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Mensaje legible",
    "details": []
  },
  "agentHints": {
    "summary": "Qué ocurrió.",
    "nextSteps": [
      "Revisar los detalles del error.",
      "Corregir el archivo de entrada.",
      "Volver a validar antes de escribir."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Buenas prácticas:

  • Devuelva siempre JSON estructurado cuando la CLI se use en flujos automatizados.
  • Incluya success para que el agente no infiera el estado desde texto libre.
  • Separe data de agentHints.
  • Haga que nextSteps sea específico de la operación.
  • En operaciones de escritura, sugiera leer de vuelta el recurso cuando la estructura real importe.
  • En errores, incluya pasos de recuperación, no solo el mensaje de fallo.

Qué sigue

Ahora que la CLI puede guiar a los agentes en cada paso, queda una pregunta:

¿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, veremos 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 humanos; los agentes necesitan orientación estructurada.
  • agentHints añade summary y nextSteps a la salida JSON.
  • La inercia de ejecución puede hacer que los agentes omitan la lectura posterior.
  • Leer de vuelta evita que el agente continúe con suposiciones.
  • La CLI pasa de ser un ejecutor a ser un navegador de flujo de trabajo.
  • Los fallos también pueden volverse accionables si incluyen pasos de recuperación.

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.

Top comments (0)