CLI para agentes de IA: até 83% menos tokens em Unity, Unreal e Godot

Nossas três ferramentas de linha de comando para engines, unity-mcp-cli, unreal-mcp-cli e godot-cli, agora custam muito menos para agentes de IA usarem. Nas mesmas tarefas de editor, um agente em cold start gasta de 60% a 83% menos tokens e faz visivelmente menos chamadas de ferramenta do que nas versões anteriores. Chegamos lá fazendo algo simples e um pouco humilhante: demos a um pequeno agente de IA apenas a CLI, observamos onde ele travava, corrigimos isso e medimos de novo.

Este post percorre as três rodadas desse trabalho, os números (incluindo o que foi na direção errada) e as lições que valem para qualquer pessoa que esteja construindo uma CLI para agentes de IA. Se você usa Claude Code, Codex ou outro agente com Unity, Unreal Engine ou Godot, essas mudanças significam sessões mais curtas, menos tentativas e uma conta menor.

Como testamos uma CLI para agentes de IA

Toda execução em toda rodada usou a mesma configuração rigorosa, então os resultados refletem o que um agente real encontra em uma máquina real:

• O agente é um LLM pequeno e rápido (DeepSeek Flash). Um modelo pequeno mostra as arestas que um modelo grande contorna silenciosamente.
• Ele recebe apenas a CLI e ferramentas básicas de arquivo. Nenhuma conexão MCP, nenhuma documentação, nenhuma dica no prompt.
• Ele começa do zero: um projeto novo, a engine fechada, nada em cache.
• Uma execução só passa se o estado final real estiver certo: os arquivos de cena ou de nível no disco, ou o resultado da compilação. O que o agente diz que fez não conta.

Contamos os tokens que o agente leu e escreveu, o número de turnos ou chamadas de ferramenta, os erros de ferramenta e as tarefas concluídas. Depois lemos as transcrições, porque os números dizem que algo está lento, e as transcrições dizem por quê.

Rodada 1: um agente consegue se orientar?

As primeiras transcrições foram difíceis. Os agentes não encontravam as ferramentas de IA do editor de jeito nenhum. Quando a CLI dizia "não logado", eles editavam arquivos de configuração à mão para contornar. Chutavam nomes de comandos que não existiam. Nada disso é culpa do agente: a CLI simplesmente não dizia o que ele precisava saber.

Então a primeira rodada de correções foi sobre descoberta:

• Um novo comando tools lista as ferramentas de IA do editor mesmo com a engine fechada. Ele inicia um editor headless uma vez, coloca a lista em cache e responde a partir do cache depois disso.
• A saída de --help agora termina com um rodapé curto de fluxo de trabalho do dia a dia: o punhado de comandos que um agente realmente precisa, na ordem em que precisa deles.
• Uma máquina que nunca fez login em ai-game.dev agora recebe um servidor local em vez de um beco sem saída. Uma máquina com login sempre fica na nuvem.
• O editor headless sobrevive a erros de compilação e informa ao agente onde está seu log, em vez de falhar sem dizer nada.
• Novos comandos test e compile (no godot-cli ele se chama check), além de um comando dialog para Unity e Unreal que lista os diálogos modais bloqueando o editor e consegue pressionar um botão em um deles.
• Os códigos de saída são iguais nas três CLIs, e os comandos voltados ao agente aceitam --format json para uma saída que um script consegue interpretar.

Comparando a primeira rodada com a rodada final desta fase (uma execução por tarefa):

• Unity: tokens de entrada 275k → 104k (−62%), turnos 46 → 30.
• Godot: tokens de entrada 598k → 203k (−66%), turnos 71 → 40, tarefas concluídas 3/4 → 4/4, erros de ferramenta 27 → 6.
• Unreal: tokens de entrada 383k → 414k (+8%), turnos 66 → 60, erros de ferramenta 13 → 8.

Somando as três engines, o agente usou 1,9 vez menos tokens de entrada por tarefa resolvida (114k → 60k) e passou em 12 de 12 tarefas em vez de 11 de 12.

Sim, a Unreal subiu. O agente cometeu menos erros e terminou em menos turnos, mas leu mais no caminho. A rodada 1 corrigiu o que o agente conseguia encontrar. Ela ainda não corrigiu quanto ele precisava ler, e é disso que trata a próxima rodada.

Rodada 2: cada byte lido no início é pago de novo a cada turno

A percepção central desta rodada é simples quando você a vê. A conversa de um agente cresce a cada passo, e tudo o que ele leu no início é enviado ao modelo de novo em cada turno seguinte. Uma página de ajuda grande lida no primeiro turno é paga de novo no segundo, no décimo e no trigésimo.

Na linha de base, o --help raiz (4,8 KB, e sempre a primeira coisa que um agente lê) representava 43% do peso em tokens de toda a saída de ferramentas. O schema RQL representava outros 24%. Duas leituras iniciais eram dois terços do custo.

As correções:

• Um --help curto com receitas RQL prontas para usar, para o agente copiar uma consulta que funciona em vez de estudar uma referência.
• Uma visão geral compacta do schema em vez do schema completo.
• Erros de RQL que incluem uma dica sobre o source ou o nome de membro correto.
• Um comando rql de primeira classe que recebe a consulta como argumento simples, sem aspas de JSON para errar.
• Operações de save que imprimem os arquivos gravados em disco. Os agentes costumavam gastar de 4 a 9 chamadas extras conferindo se o save realmente aconteceu.

RQL é a linguagem de consulta que nossas ferramentas de editor usam para ler e alterar cenas, objetos, componentes e assets. Você pode ler mais sobre ela em ai-game.dev/docs/rql.

Medimos cada ideia separadamente antes de empilhar a próxima em cima. Na Unreal, com três execuções por tarefa, a escada ficou assim:

1. Linha de base: 403k tokens, 60 chamadas de ferramenta.
2. Help curto com receitas, schema compacto, dicas de RQL: 123k tokens (−69%).
3. Mais o comando rql de primeira classe: 106k tokens (−74%).
4. Mais saves que imprimem os arquivos gravados: 68k tokens (−83%), 31 chamadas de ferramenta (−48%).

As mesmas mudanças aplicadas às três CLIs, medidas a partir de um início frio em toda execução (Unreal três execuções por tarefa, Unity e Godot duas):

• Unreal: tokens 403k → 68k (−83%), chamadas de ferramenta 60 → 31.
• Unity: tokens 248k → 82k (−67%), chamadas de ferramenta 33,5 → 26, tarefas concluídas 4/4.
• Godot: tokens 131k → 53k (−60%), chamadas de ferramenta 34 → 28,5, tarefas concluídas 4/4.

Rodada 3: uma pequena skill escrita pela própria CLI

Muitos agentes suportam skills: arquivos curtos de instrução que o agente carrega quando uma tarefa corresponde. O comando setup-skills de cada CLI agora escreve uma skill de cerca de 2,2 KB, offline, sem nenhum editor rodando. A skill é gerada a partir da mesma fonte que o --help, então as duas nunca podem divergir.

Comparamos agentes sem skill com agentes com a skill, ambos na CLI otimizada, em três tarefas de editor e 207 execuções isoladas:

• Unity: tokens 160k → 60k (−63%), chamadas de ferramenta 42 → 23, 18/18 aprovadas.
• Unreal: tokens 87k → 53k (−39%), chamadas de ferramenta 37 → 24, 9/9 aprovadas.
• Godot: tokens 117k → 81k (−31%), chamadas de ferramenta 49 → 39, 18/18 aprovadas.

Três coisas nos surpreenderam ao ajustar a skill:

• Uma skill mais curta venceu uma mais longa. Cada linha de uma skill é relida a cada turno, assim como o help.
• Uma regra escrita como aviso fez os agentes executarem verificações extras. Afirmar o fato de forma direta funcionou melhor do que avisar sobre ele.
• Para tarefas que envolvem apenas código, a skill não ajuda muito. O valor dela está no trabalho de editor: cenas, níveis, objetos e assets.

Lições para quem constrói uma CLI para agentes de IA

Nada disso é específico de engines de jogos. Se você constrói uma ferramenta de linha de comando que agentes de IA vão usar, estas são as lições que passaríamos adiante:

• Coloque o fluxo de trabalho e as receitas no --help. Os agentes leem o help primeiro. Dê a eles os cinco comandos que importam e um exemplo funcional de cada, não uma referência completa.
• Mantenha a saída inicial minúscula. Tudo o que um agente lê nos primeiros turnos é pago de novo em cada turno seguinte. Corte a primeira tela sem piedade.
• Faça os resultados se autoverificarem. Quando um save imprime "Gravado em disco" com os caminhos dos arquivos, o agente para de gastar chamadas conferindo.
• Dê a cada erro um próximo passo. Um erro que nomeia as opções válidas transforma um beco sem saída em mais uma chamada.
• Meça com uma avaliação de cold start. Use um modelo pequeno, um projeto novo e uma checagem do estado final real. Leia as transcrições, mude uma coisa e meça de novo.

Experimente

Os novos comandos estão na versão mais recente do plugin de cada engine: unity-mcp-cli 1.11.1, unreal-mcp-cli 0.31.1 e godot-cli 0.39.1. Se unity-mcp-cli --help (ou o equivalente em Unreal ou Godot) não lista rql e tools, você está em uma versão anterior, e o comando update leva você à mais recente.

npx unity-mcp-cli tools
npx unity-mcp-cli rql 'objects | where name starts-with "Tree" | count'
npx unity-mcp-cli compile
npx unity-mcp-cli setup-skills claude-code

npx unreal-mcp-cli tools --filter rql
npx unreal-mcp-cli rql 'actors | where Label starts-with "Rock" | set Scale = Scale * 1.5'
npx unreal-mcp-cli rql 'editor | call SaveLevel()'

npx godot-cli rql 'nodes | where name contains "Enemy" | count'
npx godot-cli check
npx godot-cli setup-skills claude-code

O primeiro comando de editor inicia um editor headless e o mantém aquecido, então não é preciso abrir a engine antes. Uma alteração feita com rql imprime o que mudou e quais arquivos foram gravados, então seu agente pode seguir direto para o próximo passo.

Comece agora

• Unity: ai-game.dev/engines/unity
• Unreal Engine: ai-game.dev/engines/unreal
• Godot: ai-game.dev/engines/godot
• A linguagem de consulta RQL: ai-game.dev/docs/rql
• Guia de início rápido: ai-game.dev/docs/quickstart
• Comunidade no Discord: https://discord.gg/cfbdMZX99G

Vamos continuar rodando essas avaliações de cold start conforme as CLIs crescem. Se seu agente travar em algum lugar, conte pra gente no Discord: uma transcrição de onde ele errou é exatamente o que precisamos.