Agent precisa de um conjunto de ferramentas básicas

Vendo todo mundo falando sobre o problema do conjunto de ferramentas do Agent — será que só um shell resolve tudo? Depois de fazer o holon, percebi que na verdade não é tão simples assim.
Lendo: por que abandonamos o Read/Glob, e seguimos pelo shell
O conjunto de ferramentas do holon foi alterado várias versões, e no final descartou ferramentas específicas como Read (ler arquivo) e Glob (busca por padrão) fornecidas pelo Claude Code, passando toda leitura e busca a serem feitas via shell. Isso é consistente com a abordagem do Codex — o ExecCommand do Codex é direto, ler arquivo com cat, procurar código com rg, sem definir uma ferramenta separada para cada operação de "leitura".
A razão para isso é bem simples: o shell é a "linguagem de programação" mais familiar para o LLM. Em vez de fazer o modelo aprender os parâmetros semânticos da sua ferramenta Read, é melhor deixá-lo escrever comandos shell treinados bilhões de vezes. Cada ferramenta especializada aumenta a carga cognitiva do modelo; enquanto o shell, essa interface, o modelo já domina bastante.
Mas usar só shell tem um custo: truncamento de saída. Para evitar que o valor retornado pelo shell seja grande demais e encha o contexto, o framework limita a saída de cada comando. O Agent usando cat para ler um arquivo grande pode pegar só a metade, o restante fica no arquivo artifact, e precisa fazer outro cat, às vezes várias vezes, para ler tudo. A ferramenta Read do Claude Code tem um limite de compressão muito maior que o shell comum, permitindo ler arquivos grandes de uma só vez, evitando várias idas e vindas. É uma questão de trade-off: definir menos ferramentas reduz a carga cognitiva, mas ferramentas específicas são mais eficientes em cenários de fronteira.
Escrevendo: de sed a ApplyPatch, e os desafios da ferramenta de gramática livre
Por outro lado, operações de escrita não podem ser feitas inteiramente com shell.
Se o Agent usar só sed para editar, vai perceber que lidar com correspondências multi-linha complexas é difícil — quebras de linha, escape, indentação, qualquer erro nessas camadas pode fazer a edição falhar. Por isso, muitos sistemas oferecem ferramentas de edição como Replace String, onde o Agent envia uma grande string old_string para fazer uma correspondência exata e substituir por new_string. Apesar de mais rudimentar, é muito mais estável que sed.
O Codex foi mais longe, inventando sua própria ferramenta ApplyPatch, que permite ao Agent gerar patches diretamente, fazendo edições em lote de uma vez só. O holon também se inspirou nisso.
Porém, na implementação, encontramos um problema: o Codex usa um formato de patch simplificado definido pela própria OpenAI, e combina isso com uma ferramenta especial chamada free grammar tool, que resolve o problema do formato.
Por que criar um mecanismo novo? Porque a definição padrão de ferramentas do LLM é tool(args) em JSON. Se passar o patch como uma string JSON, há muita necessidade de escape — quebras de linha, aspas, indentação, tudo precisa ser cuidadosamente tratado. Escrever patch com o Agent já é propenso a erros, e adicionar uma camada de escape JSON dobra a chance de erro. A ideia do free grammar tool é passar o texto do patch diretamente como entrada da ferramenta, sem passar por codificação JSON, ou seja, o que o modelo escrever é o que será usado. Isso reduz bastante a chance de erro na geração do patch.
Por enquanto, essa mecânica só é suportada pela interface do Codex da OpenAI. Como o holon precisa ser compatível com múltiplos provedores de modelos, não pode depender só disso.
Assim, o holon adota uma abordagem: injeta diferentes definições de ApplyPatch dependendo do modelo. Para modelos que suportam free grammar, usa o formato original do patch; para outros, aceita o padrão git diff. Acredito que, após bilhões de diffs treinados no GitHub, os LLMs ficam bastante proficientes em git diff. Na prática, funciona bem — embora ainda erre às vezes, na maioria das vezes consegue corrigir, e com o aumento dos dados de treinamento, essa capacidade só melhora. Ainda assim, recomendo que todos os fornecedores de modelos suportem o free grammar tool, pois é uma necessidade real na escrita de código pelo Agent.
Orquestração: comandos de longa duração e abstração de tarefas
O terceiro ponto é que comandos shell do Agent podem não terminar rápido — iniciar um servidor de dev, rodar testes, construir o projeto, tudo isso pode levar muito tempo, ou nem terminar. Nos primeiros frameworks, o tratamento era bem bruto: ou bloqueava de forma síncrona, travando o Agent, ou enviava todos os comandos para o background, fazendo o Agent repetir o mesmo comando várias vezes.
Hoje, a indústria está chegando a um consenso: não expor ao Agent a opção de "primeiro/plano ou background" — essa decisão o próprio Agent não consegue acertar. Uma abordagem melhor é definir um limite de tempo, e se o comando passar desse limite, ele é automaticamente enviado para o background, de forma transparente para o Agent. O Agent não precisa prever se o comando deve ou não ir para o background, o runtime cuida disso.
Mas essa transição automática para o background é só o começo. Depois, surgem problemas mais complexos — e ainda não há uma resposta padrão na indústria.
Primeiro, como ler a saída. Tarefas em background podem ainda estar rodando ou já terem terminado, e a saída pode ser grande. Mas as APIs de cada sistema não são padronizadas — algumas usam polling, outras usam push de eventos.
Segundo, como parar a tarefa. Cada sistema tem seu mecanismo de cancelamento, mas é kill imediato ou saída graciosa? E a saída já gerada, deve ser preservada?
Por último, quem acorda o Agent? Depois que o Agent envia a tarefa para o background e ela entra em modo de espera, quem a acorda quando termina? Isso exige uma integração profunda entre runtime e o agendamento do Agent, algo que não pode ser resolvido só na camada de ferramentas.
Essas três questões — leitura da saída, parada da tarefa, despertar do Agent — compõem o ciclo completo de gerenciamento de tarefas em background. Cada sistema implementou "execução em background", mas ainda não há uma padronização nesse gerenciamento, que pode ser o próximo grande avanço na evolução da cadeia de ferramentas do Agent.
Ainda não é hora de usar um padrão pronto de forma cega
Voltando à questão inicial: o shell resolve 80%, mas os outros 20% — precisão na edição, compatibilidade do formato de patch com a capacidade do modelo, orquestração de tarefas longas — são exatamente o que decide se o Agent sai do estágio de demonstração para um sistema realmente utilizável.
O conjunto de ferramentas envolve muito mais do que "embalar um shell", e ainda não é hora de aplicar um padrão pronto de forma automática. Essa é a razão de o Codex e o Claude Code oferecerem respostas diferentes para esses problemas básicos, e o holon fazer diferentes escolhas de acordo com seu cenário. Ainda há muito a explorar e melhorar nesse campo.