Patrones de Diseño CLI para Agentes de IA: Conceptos Erróneos y Enfoques Prácticos

Aclaración del Protocolo de Interfaz CLI

El mayor malentendido de la Parte 1 fue que "CLI" significaba darle a un LLM una terminal de Linux. CLI es en realidad un protocolo de interfaz: comando de texto entra → resultado de texto sale. La implementación puede ocurrir de dos maneras:

• Como un binario o script en el PATH del shell — se convierte en una herramienta CLI que se ejecuta en un shell real
• Como un analizador de comandos dentro de tu código — cuando el LLM produce run(command="weather --city Tokyo"), analizas la cadena y la ejecutas directamente en el código de tu aplicación sin involucrar ningún shell

La clave es hacer que el LLM sienta que está usando una CLI. En el sistema del autor, la mayoría de los comandos nunca tocan el SO — son funciones de Go despachadas por un enrutador de comandos. Solo los comandos que genuinamente necesitan un SO real (ejecutar scripts, instalar paquetes) van a una micro-VM aislada. El agente no sabe y no le importa qué capa maneja su comando.

Principios de Diseño de CLI Amigable para Agentes

Dos Filosofías Centrales

Filosofía 1: Diseño de Ayuda al Estilo Unix

• tool --help → lista de comandos de nivel superior
• tool <command> --help → parámetros específicos y uso para ese subcomando

Esto permite que el agente descubra capacidades bajo demanda sin tener que incluir toda la documentación en el contexto de antemano.

Filosofía 2: Pensamiento de Sugerencias

Cada respuesta — especialmente los errores — debe incluir orientación que reduzca la exploración innecesaria.

Mal ejemplo:

> cat photo.png [error] binary file

Buen ejemplo:

> cat photo.png [error] cat: archivo binario detectado (image/png, 182KB). Usar: see photo.png (ver imagen) O: cat -b photo.png (codificar en base64)

Por qué esto importa: la exploración inválida desperdicia tokens. En conversaciones de múltiples turnos, este desperdicio se acumula — cada intento fallido permanece en el contexto, consumiendo atención y recursos de inferencia para cada turno posterior. Una sola sugerencia útil puede ahorrar tokens significativos durante el resto de la conversación.

Diseño de CLI Seguro

Cuando los comandos CLI involucran operaciones peligrosas o irreversibles, la herramienta misma debe proporcionar mecanismos de seguridad.

Ejecución en Seco / Vista Previa de Cambios — Prevención de Errores

Para operaciones dentro de la autoridad del agente pero con consecuencias difíciles de revertir. El objetivo es permitir que el agente (o humano) vea lo que sucederá antes de comprometerse.

> dns update --zone example.com --record A --value 1.2.3.4 ⚠ EJECUCIÓN EN SECO: Registro A para example.com: 5.6.7.8 → 1.2.3.4 Propagación: ~300s. No es instantáneamente reversible. Para ejecutar: agregar --confirm

La vista previa debe mostrar claramente cuál es el estado actual y a qué cambiará. El agente confirma con --confirm.

Autorización Humana — Operaciones Más Allá de la Autonomía del Agente

Para operaciones que requieren juicio o aprobación humana — sin importar cuán seguro esté el agente, no puede completarlas por sí solo.

Enfoque 1: Aprobación por Notificación Bloqueante

> pay --amount 500 --to vendor --reason "office supplies for Q2" ⏳ Se requiere aprobación. Notificación enviada a tu dispositivo. Esperando respuesta... ✓ Aprobado. Pago de $500 completado. [exit:0 | 7.2s]

Como la verificación de inicio de sesión de Apple — el CLI envía una notificación directamente al dispositivo del humano con todo el contexto (monto, destinatario, razón). El CLI se bloquea hasta que el humano aprueba o rechaza, luego devuelve el resultado al agente.

Enfoque 2: Código de Verificación / 2FA

> transfer --from savings --to checking --amount 10000 ⚠ Esta operación requiere verificación 2FA. Razón: transferir $10,000 entre cuentas. Se ha enviado un código a tu autenticador. Re-ejecutar con: --otp <code>