Criando CLIs para Agentes de IA: Princípios de Design do CLI gws do Google

Por que o Design CLI Focado em Agentes é Importante

A experiência do desenvolvedor humano (DX) otimiza para descoberta e tolerância a erros, enquanto a DX do agente requer previsibilidade e defesa em profundidade. O artigo argumenta que adaptar CLIs focadas em humanos para agentes é ineficaz, e demonstra isso através do CLI gws do Google para Google Workspace, que foi projetado desde o primeiro dia com agentes de IA como consumidores principais.

Princípios de Design Fundamentais

Payloads JSON Brutos em Vez de Flags Personalizadas: Humanos preferem flags simples como --title "Meu Documento", mas agentes funcionam melhor com payloads JSON diretos que mapeiam para esquemas de API sem perda de tradução.

Exemplo de comparação:

Focado em humanos (10 flags, namespace plano):
my-cli spreadsheet create --title "Orçamento Q1" --locale "en_US" --timezone "America/Denver" --sheet-title "Janeiro" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

Focado em agentes (uma flag JSON):
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Orçamento Q1", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "Janeiro", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

O CLI gws usa flags --params e --json para todas as entradas, aceitando payloads completos da API diretamente. A abordagem recomendada é suportar ambos os caminhos no mesmo binário em vez de manter ferramentas separadas.

Considerações Adicionais

O artigo descreve várias outras considerações de design para CLIs focadas em agentes:

• Introspecção de Esquema: Esquemas auto-descritivos que agentes podem introspectar em tempo de execução
• Disciplina de Janela de Contexto: Gerenciar a saída para caber dentro dos limites de contexto do agente
• Proteção de Entrada: Proteção contra alucinações do agente
• Habilidades do Agente: Entregar capacidades em vez de apenas comandos
• Suporte a Múltiplas Superfícies: Trabalhar com MCP, extensões e variáveis de ambiente
• Barreiras de Segurança: Modos de simulação e sanitização de resposta

CLIs estão se tornando a interface de menor atrito para agentes de IA interagirem com sistemas externos, exigindo saída determinística e legível por máquina em vez de interfaces orientadas para humanos.