Não Reescreva Sua CLI para Agentes: a Interface de Ferramentas É uma Superfície de Controle

Trocar os argumentos de linha de comando de uma ferramenta por um único payload JSON fez as tarefas de agente custarem de 4 a 11 vezes mais por execução, e fez os modelos mais fracos devolverem respostas erradas. É o que a Microsoft encontrou ao testar um dos conselhos mais repetidos na engenharia de agentes: tornar suas ferramentas de desenvolvimento “amigáveis para agentes” entregando JSON estruturado no lugar das convenções --flag valor que os humanos usam.

O conselho parece razoável. Agentes emitem e leem JSON nativamente, então uma interface JSON deveria encaixar melhor do que strings de argumento feitas para um terminal. Waldek Mastykarz, principal developer advocate na Microsoft, testou a afirmação em vez de aceitá-la. A interface convencional venceu em todos os eixos que um time mede em produção.

Uma Tarefa, Duas Interfaces

Mastykarz manteve a ferramenta e a tarefa fixas e mudou apenas como o agente chamava aquilo. Uma versão recebia flags comuns de linha de comando. A outra recebia um único payload JSON carregando os mesmos parâmetros. Ele rodou cada versão cinco vezes contra um conjunto de modelos dentro do harness do GitHub Copilot Chat, incluindo GPT-5.3-Codex, Haiku 4.5 e MAI-Code-1-Flash. Mesmo prompt, mesmo objetivo, mesmas cinco execuções. A interface era a única variável.

É esse desenho que torna os números úteis. Quando correção e custo divergem entre as duas versões, a ferramenta não mudou e a tarefa não mudou. O que mudou foi o jeito como o agente se dirigiu à ferramenta.

Os Argumentos Convencionais Acertaram Sempre

Comece pela correção, porque é o resultado que deveria encerrar o debate. Com argumentos em formato de flag, todo modelo marcou 5 de 5. Perfeito, entre modelos fortes e fracos por igual.

Passe a mesma tarefa para JSON e os modelos mais fortes se seguraram, mas os mais fracos quebraram. O Haiku 4.5 caiu para 2 de 5. O MAI-Code-1-Flash ficou em 3 de 5. Nada no trabalho de fundo ficou mais difícil. A interface JSON simplesmente exigiu mais do modelo para chamar a ferramenta corretamente, e os modelos com menos folga gastaram essa folga com formatação em vez da tarefa. A escolha da interface decidiu se um modelo menor e mais barato podia ser confiável.

O JSON Custou de 4 a 11 Vezes Mais

O custo andou na mesma direção, para todo modelo, sem exceção. O JSON saiu de 4x a 11x mais caro por tarefa. O GPT-5.3-Codex foi de US$ 0,05 para US$ 0,54 no mesmo serviço, um salto de 11x. O Haiku 4.5 pagou por volta de 8x mais.

O mecanismo foi retentativa. Quando um modelo produzia JSON malformado, a chamada falhava e ele tentava de novo. Essas retentativas geraram de 7 a 14 vezes mais tokens de saída do que as execuções limpas de um único disparo que a interface baseada em flags produziu. Entrada estruturada que parece mais organizada no quadro branco virou uma fogueira de tokens no harness, porque cada erro de escape comprava mais uma ida e volta.

O Resultado Que Ninguém Prevê

O achado que deveria fazer os times pararem é entre plataformas. O custo do JSON dependia do shell em que rodava. No PowerShell, a interface JSON custou 9x mais do que no Bash, porque as regras de aspas e escape diferem entre shells e o modelo insistia em errá-las. Os argumentos convencionais mal sentiram a diferença: US$ 0,05 em um shell, US$ 0,07 no outro.

Uma interface que parece neutra entre plataformas introduziu uma variação de custo de 9x que aparece só nas máquinas de alguns desenvolvedores. Um time testando apenas no Bash colocaria isso em produção e depois veria custo e taxa de falha dispararem para cada colega no Windows, sem causa óbvia nos logs. A avaliação em um único ambiente esconde exatamente essa classe de defeito.

A Interface É uma Superfície de Controle

Junte os três resultados. A interface definiu a correção, definiu o custo e definiu a variância entre plataformas. Mesma ferramenta, mesma tarefa, mesmos modelos o tempo todo. A única coisa que mudou moveu todos os números que um time de produção acompanha.

Essa é a definição de uma superfície de controle. A interface de ferramentas de agente se comporta como um limite de taxa ou uma política de retentativa: um botão que define diretamente a taxa de falha e o gasto. Tratá-la como preferência de gosto ignora esse efeito. A maioria dos times trata isso como preferência de design, escolhida uma vez por intuição e nunca revisada. Os dados da Microsoft dizem que ela merece o mesmo escrutínio de qualquer outro controle de produção. Você mede, entende o raio de impacto e testa antes de mudar.

Há uma segunda lição embaixo da primeira. A interface vencedora foi a que já existia. Diziam aos times para reescrever ferramentas que funcionavam, na teoria de que agentes precisam de entradas sob medida, moldadas para máquina. A evidência aponta para o outro lado. Já argumentamos que agentes muitas vezes vão melhor com os artefatos simples que os humanos já leem do que com estruturas construídas só para eles. A CLI legível por humanos vencendo o JSON estruturado para máquina, em favor das máquinas, é esse mesmo padrão surgindo na camada de ferramentas.

Isso também eleva a aposta nas superfícies de avaliação em geral. Uma vez que você aceita que a interface governa custo e confiabilidade, a interface vira algo que você precisa vigiar, que é o argumento que fizemos para tratar a saída do agente como uma superfície mensurável, e não como uma caixa-preta.

Meça Antes de Reestruturar

O ativo reaproveitável aqui é o método. Mastykarz não ganhou uma discussão. Ele rodou um experimento barato que qualquer time pode copiar antes de gastar semanas numa reescrita.

Escolha um cenário real. Pegue uma tarefa única que a ferramenta de fato executa no seu fluxo, não um exemplo de brinquedo. A questão toda é testar a coisa real.
Defina correção antes. Decida como se parece uma resposta certa antes de rodar qualquer coisa, para que a pontuação não vire julgamento depois do fato.
Rode as duas interfaces nos seus modelos. Inclua os modelos mais baratos e fracos para onde você espera rotear trabalho. Os modelos fortes muitas vezes mascaram uma falha de interface que os pequenos expõem.
Rode nos seus shells e plataformas. Bash e PowerShell no mínimo. A variância de 9x mora aqui, e é invisível em um único ambiente.
Leia custo e contagem de tokens, não só passa ou falha. Uma versão pode estar correta e ainda custar 11x mais por retentativas silenciosas.

O experimento é barato. Uma reescrita movida por intuição não é.

Faça Isto Agora

Encontre uma ferramenta que seus agentes chamam hoje e verifique se alguém propôs torná-la “amigável para agentes” com uma interface JSON. Antes que esse trabalho entre no cronograma, rode o teste de cinco passos acima na interface existente contra a proposta. Pontue correção, custo por tarefa e variância entre shells. Se a interface convencional se segurar, e os dados da Microsoft dizem que ela costuma segurar, você economizou uma reescrita e manteve uma ferramenta mais barata e confiável. Se o JSON realmente vencer no seu caso, agora você tem evidência no lugar de palpite. De qualquer forma, você passou a tratar a interface como o que ela é: um controle que se ajusta com números, em vez de um design que se redesenha na fé.

Fontes

Microsoft Developer Blog (Waldek Mastykarz). “Don’t Rewrite Your CLI for Agents.” Julho de 2026.

A Victorino ajuda times a tratar a interface de ferramentas de agentes como uma superfície de controle mensurável, não como uma reescrita: contato@victorino.com.br | www.victorino.com.br