Construcción de CLIs para Agentes de IA: Principios de Diseño desde la CLI gws de Google

Por qué importa el diseño CLI centrado en agentes

La experiencia del desarrollador humano (DX) optimiza para la descubribilidad y la tolerancia a errores, mientras que la DX del agente requiere predictibilidad y defensa en profundidad. El artículo argumenta que adaptar CLIs centradas en humanos para agentes es ineficaz, y demuestra esto a través de la CLI gws de Google para Google Workspace, que fue diseñada desde el primer día con agentes de IA como consumidores principales.

Principios clave de diseño

Cargas útiles JSON sin procesar en lugar de indicadores personalizados: Los humanos prefieren indicadores simples como --title "Mi documento", pero los agentes funcionan mejor con cargas útiles JSON directas que se mapean a esquemas de API sin pérdida de traducción.

Comparación de ejemplo:

Centrado en humanos (10 indicadores, espacio de nombres plano):
my-cli spreadsheet create --title "Presupuesto Q1" --locale "en_US" --timezone "America/Denver" --sheet-title "Enero" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

Centrado en agentes (un indicador JSON):
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Presupuesto Q1", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "Enero", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

La CLI gws utiliza indicadores --params y --json para todas las entradas, aceptando cargas útiles completas de API directamente. El enfoque recomendado es admitir ambos caminos en el mismo binario en lugar de mantener herramientas separadas.

Consideraciones adicionales

El artículo describe varias otras consideraciones de diseño para CLIs centradas en agentes:

• Introspección de esquema: Esquemas autodescriptivos que los agentes pueden inspeccionar en tiempo de ejecución
• Disciplina de ventana de contexto: Gestionar la salida para que se ajuste a los límites de contexto del agente
• Endurecimiento de entrada: Protección contra alucinaciones del agente
• Habilidades del agente: Envío de capacidades en lugar de solo comandos
• Soporte multi-superficie: Funcionamiento con MCP, extensiones y variables de entorno
• Barreras de seguridad: Modos de prueba y saneamiento de respuestas

Las CLIs se están convirtiendo en la interfaz de menor fricción para que los agentes de IA interactúen con sistemas externos, requiriendo salida determinista y legible por máquina en lugar de interfaces orientadas a humanos.