Que tipo de ferramentas básicas o Agent precisa ter

Vendo que todos estão falando sobre o conjunto de ferramentas do Agent — será que um shell resolve tudo? Depois de fazer o holon, percebi que na verdade não é tão simples assim.
Leitura: por que abandonámos o Read/Glob, e seguimos pelo shell
O conjunto de ferramentas do holon foi alterado várias versões, e no final descartámos ferramentas específicas como o Read (leitura de ficheiros) e Glob (pesquisa por padrão), semelhantes às oferecidas pelo Claude Code, e toda leitura e busca passaram a ser feitas via shell. Isto é consistente com a abordagem do Codex — o ExecCommand do Codex é uma única ferramenta, onde ler ficheiros é simplesmente cat, procurar código é rg, sem definir uma ferramenta separada para cada operação de "leitura".
A razão para isso é bastante simples: o shell é a "linguagem de programação" mais familiar ao LLM. Em vez de fazer o modelo aprender os parâmetros semânticos da ferramenta Read que você define, é melhor deixá-lo escrever comandos shell treinados bilhões de vezes. Cada ferramenta especializada adicional aumenta a carga cognitiva do modelo; enquanto a interface do shell, o modelo já domina completamente.
Mas usar só shell tem um custo: truncamento de saída. Para evitar que o valor retornado pelo shell seja demasiado longo e preencha o contexto, o framework limita a saída de cada comando. O Agent usando cat para ler um ficheiro grande pode obter apenas a primeira metade, o restante fica no ficheiro artifact, e é preciso fazer outro cat, talvez várias vezes, para ler tudo. A ferramenta Read do Claude Code tem um limite de compressão muito maior do que o shell genérico, permitindo ler ficheiros 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.
Escrever: 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 fizer o Agent usar só sed para editar, vai perceber que lidar com correspondências complexas de múltiplas linhas — quebras de linha, escape, indentação — é difícil, pois qualquer problema nessas camadas causa falha na edição. Assim, muitos sistemas oferecem ferramentas de edição como Replace String, onde o Agent envia uma grande porção de old_string para fazer uma correspondência exata e substituí-la por new_string. Apesar de menos elegante, é muito mais estável do que sed.
O Codex foi mais longe, inventando a sua própria ferramenta ApplyPatch, que permite ao Agent gerar patches diretamente, fazendo edições em lote de uma só vez. O holon também adotou essa abordagem.
Porém, ao implementar, 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, para resolver o problema do formato.
Por que criar um mecanismo novo? Porque a definição padrão de ferramentas do LLM é tool(args) com parâmetros em JSON. Se passar o patch como uma string JSON, há muita necessidade de escape — quebras de linha, aspas com barras invertidas, indentação cuidadosa. Como o Agent já tende a cometer erros ao escrever patches, acrescentar uma camada de escape JSON aumenta a probabilidade de erro. A ideia do free grammar tool é passar o texto original do patch diretamente como entrada da ferramenta, sem codificação JSON, deixando o que o modelo gerar como está. Isso reduz drasticamente os erros na geração de patches.
Atualmente, 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ó dessa solução.
Assim, o holon define diferentes implementações de ApplyPatch dependendo do modelo: para modelos que suportam free grammar, usa o formato original do patch; para outros, aceita o formato padrão diff do git. Acredito que, após bilhões de diffs treinados no GitHub, os LLMs ficam bastante proficientes nesse formato. Na prática, funciona bem — embora ainda haja erros, na maioria das vezes as correções estão corretas, e com mais 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.
Agendamento: comandos de longa duração e abstração de tarefas
O terceiro ponto é que comandos shell do Agent podem não terminar rapidamente — iniciar um servidor de desenvolvimento, rodar testes, construir projetos, 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, levando o Agent a 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/ background" — essa decisão o próprio Agent não consegue acertar. Uma abordagem melhor é definir um limite de tempo, e após o timeout, o comando é 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 o envio automático para o background é só o primeiro passo. Depois, surgem problemas mais complexos — e ainda não há uma solução 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 fornecedor têm semânticas diferentes — algumas usam polling, outras usam push de eventos.
Segundo, como parar a tarefa. Cada um tem seu mecanismo de cancelamento, mas cancelar é um kill imediato ou uma saída graciosa? E a saída já gerada, deve ser preservada?
Por último, quem acorda o Agent? Quando o comando fica no background e o Agent entra em modo de espera, quem o acorda ao terminar? Isso exige uma integração profunda entre runtime e agendamento do Agent, não é algo que uma ferramenta isolada resolve.
Essas três questões — leitura da saída, parada da tarefa, despertar do Agent — juntas representam o ciclo completo de gerenciamento de tarefas em background. Cada fornecedor 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, agendamento de tarefas longas — são exatamente o que determina se o Agent pode evoluir de um protótipo para um sistema realmente utilizável.
A escolha do conjunto de ferramentas vai muito além de "embalar um shell", e ainda não estamos na fase de aplicar um padrão pronto sem pensar. Essa é a razão de o Codex e o Claude Code oferecerem respostas diferentes para esses problemas básicos, e o holon fazer diferentes concessões de acordo com seu cenário. Ainda há muito a explorar e melhorar nesse campo.