Padrões de Design CLI para Agentes de IA: Equívocos e Abordagens Práticas

Esclarecimento do Protocolo de Interface CLI

O maior equívoco da Parte 1 foi pensar que "CLI" significava dar um terminal Linux a um LLM. CLI é na verdade um protocolo de interface: comando de texto entra → resultado de texto sai. A implementação pode acontecer de duas maneiras:

• Como um binário ou script no PATH do shell — torna-se uma ferramenta CLI que roda em um shell real
• Como um analisador de comandos dentro do seu código — quando o LLM emite run(command="weather --city Tokyo"), você analisa a string e a executa diretamente no código do seu aplicativo, sem envolver o shell

A chave é fazer o LLM sentir como se estivesse usando uma CLI. No sistema do autor, a maioria dos comandos nunca toca o SO — são funções Go despachadas por um roteador de comandos. Apenas comandos que genuinamente precisam de um SO real (executar scripts, instalar pacotes) vão para uma micro-VM isolada. O agente não sabe e não se importa com qual camada lida com seu comando.

Princípios de Design de CLI Amigável para Agentes

Duas Filosofias Centrais

Filosofia 1: Design de Ajuda no Estilo Unix

• tool --help → lista de comandos de alto nível
• tool <command> --help → parâmetros específicos e uso para aquele subcomando

Isso permite que o agente descubra capacidades sob demanda sem colocar toda a documentação no contexto de uma vez.

Filosofia 2: Pensamento de Dicas

Cada resposta — especialmente erros — deve incluir orientação que reduza exploração desnecessária.

Exemplo ruim:

> cat photo.png [erro] arquivo binário

Exemplo bom:

> cat photo.png [erro] cat: arquivo binário detectado (image/png, 182KB). Use: see photo.png (visualizar imagem) Ou: cat -b photo.png (codificar em base64)

Por que isso importa: exploração inválida desperdiça tokens. Em conversas com múltiplas interações, esse desperdício se acumula — cada tentativa falha permanece no contexto, consumindo atenção e recursos de inferência para cada interação subsequente. Uma única dica útil pode economizar tokens significativos no restante da conversa.

Design de CLI Seguro

Quando comandos CLI envolvem operações perigosas ou irreversíveis, a própria ferramenta deve fornecer mecanismos de segurança.

Simulação / Previsão de Alterações — Evitando Erros

Para operações dentro da autoridade do agente, mas com consequências difíceis de reverter. O objetivo é permitir que o agente (ou humano) veja o que acontecerá antes de confirmar.

> dns update --zone example.com --record A --value 1.2.3.4 ⚠ SIMULAÇÃO: Registro A para example.com: 5.6.7.8 → 1.2.3.4 Propagação: ~300s. Não é instantaneamente reversível. Para executar: adicione --confirm

A previsão deve mostrar claramente qual é o estado atual e para o que será alterado. O agente confirma com --confirm.

Autorização Humana — Operações Além da Autonomia do Agente

Para operações que exigem julgamento ou aprovação humana — não importa o quão confiante o agente esteja, ele não pode concluí-las sozinho.

Abordagem 1: Aprovação por Push Bloqueante

> pay --amount 500 --to vendor --reason "material de escritório para Q2" ⏳ Aprovação necessária. Notificação enviada para seu dispositivo. Aguardando resposta... ✓ Aprovado. Pagamento de $500 concluído. [exit:0 | 7.2s]

Como a verificação de login de dispositivo da Apple — o CLI envia uma notificação push diretamente para o dispositivo do humano com contexto completo (valor, destinatário, motivo). O CLI bloqueia até que o humano aprove ou rejeite, então retorna o resultado para o agente.

Abordagem 2: Código de Verificação / 2FA

> transfer --from savings --to checking --amount 10000 ⚠ Esta operação requer verificação 2FA. Motivo: transferir $10.000 entre contas. Um código foi enviado para seu autenticador. Execute novamente com: --otp <código>