Uma das partes mais difíceis de construir um harness para agentes é estruturar seu espaço de ações.
O Claude atua por meio de Tool Calling, mas existem várias formas de construir ferramentas na API do Claude com primitivas como bash, skills e, recentemente, execução de código (leia mais sobre chamadas programáticas de ferramentas na API do Claude no novo artigo de @RLanceMartin).
Diante de todas essas opções, como você projeta as ferramentas do seu agente? Você precisa de apenas uma ferramenta, como execução de código ou bash? E se você tivesse 50 ferramentas, uma para cada caso de uso que seu agente pudesse encontrar?
Para me colocar na mente do modelo, gosto de imaginar que estou recebendo um problema de matemática difícil. Quais ferramentas você gostaria de ter para resolvê-lo? Dependeria das suas próprias habilidades!
Papel seria o mínimo, mas você estaria limitado por cálculos manuais. Uma calculadora seria melhor, mas você precisaria saber operar as opções mais avançadas. A opção mais rápida e poderosa seria um computador, mas você teria que saber usá-lo para escrever e executar código.
Este é um framework útil para projetar seu agente. Você quer dar a ele ferramentas que sejam moldadas para suas próprias habilidades. Mas como saber quais são essas habilidades? Você presta atenção, lê suas saídas, experimenta. Você aprende a ver como um agente.
Aqui estão algumas lições que aprendemos prestando atenção no Claude enquanto construímos o Claude Code.
Melhorando a Elicitação e a Ferramenta AskUserQuestion
Ao construir a ferramenta AskUserQuestion, nosso objetivo era melhorar a capacidade do Claude de fazer perguntas (muitas vezes chamada de elicitação).
Embora o Claude pudesse simplesmente fazer perguntas em texto simples, percebemos que responder a essas perguntas parecia levar um tempo desnecessário. Como poderíamos reduzir esse atrito e aumentar a largura de banda da comunicação entre o usuário e o Claude?
Tentativa #1 - Editando o ExitPlanTool
A primeira coisa que tentamos foi adicionar um parâmetro ao ExitPlanTool para ter um array de perguntas junto com o plano. Essa foi a implementação mais fácil, mas confundiu o Claude porque estávamos pedindo simultaneamente um plano e um conjunto de perguntas sobre o plano. E se as respostas do usuário entrassem em conflito com o que o plano dizia? O Claude precisaria chamar o ExitPlanTool duas vezes? Precisávamos de outra abordagem.
(você pode ler mais sobre por que criamos um ExitPlanTool em nosso post sobre cache de prompt
Tentativa #2 - Alterando o Formato de Saída
Em seguida, tentamos modificar as instruções de saída do Claude para servir um formato Markdown ligeiramente modificado que ele pudesse usar para fazer perguntas. Por exemplo, poderíamos pedir que ele gerasse uma lista de perguntas em tópicos com alternativas entre colchetes. Poderíamos então analisar e formatar essa pergunta como uma interface para o usuário.
Embora essa fosse a mudança mais geral que poderíamos fazer e o Claude até parecesse razoável em gerar isso, não era garantido. O Claude acrescentava frases extras, omitia opções ou usava um formato totalmente diferente.
Tentativa #3 - A Ferramenta AskUserQuestion
Por fim, decidimos criar uma ferramenta que o Claude pudesse chamar a qualquer momento, mas que era particularmente instruída a fazer isso durante o modo de planejamento. Quando a ferramenta era acionada, mostrávamos um modal para exibir as perguntas e bloquear o loop do agente até que o usuário respondesse.
Essa ferramenta nos permitiu instruir o Claude a gerar uma saída estruturada e nos ajudou a garantir que o Claude oferecesse múltiplas opções ao usuário. Também deu aos usuários maneiras de compor essa funcionalidade, por exemplo, chamando-a no Agent SDK ou referenciando-a em skills.
Mais importante ainda, o Claude parecia gostar de chamar essa ferramenta e descobrimos que suas saídas funcionavam bem. Nem a ferramenta melhor projetada funciona se o Claude não entender como chamá-la.
Será esta a forma final de elicitação no Claude Code? Não temos certeza. Como você verá no próximo exemplo, o que funciona para um modelo pode não ser o melhor para outro.
Atualizando com Capacidades - Tasks & Todos
Quando lançamos o Claude Code pela primeira vez, percebemos que o modelo precisava de uma lista de tarefas (Todo) para se manter no caminho certo. As tarefas podiam ser escritas no início e marcadas como concluídas à medida que o modelo trabalhava. Para isso, demos ao Claude a ferramenta TodoWrite, que escrevia ou atualizava tarefas e as exibia ao usuário.
Mas mesmo assim, muitas vezes víamos o Claude esquecendo o que tinha que fazer. Para nos adaptarmos, inserimos lembretes do sistema a cada 5 turnos, que lembravam o Claude de seu objetivo.
Mas, à medida que os modelos melhoraram, eles não apenas não precisavam mais ser lembrados da lista de tarefas, como também podiam achá-la limitante. Receber lembretes da lista de tarefas fazia o Claude pensar que precisava segui-la à risca, em vez de modificá-la. Também vimos o Opus 4.5 ficar muito melhor no uso de subagentes, mas como os subagentes poderiam coordenar uma lista de tarefas compartilhada?
Vendo isso, substituímos o TodoWrite pela Task Tool (leia mais sobre Tasks aqui). Enquanto as tarefas (Todos) eram sobre manter o modelo no caminho certo, as Tasks eram mais sobre ajudar os agentes a se comunicarem entre si. As Tasks podiam incluir dependências, compartilhar atualizações entre subagentes, e o modelo podia alterá-las e excluí-las.
À medida que as capacidades dos modelos aumentam, as ferramentas que seus modelos antes precisavam podem agora estar os restringindo. É importante revisitar constantemente suposições anteriores sobre quais ferramentas são necessárias. Isso também é útil para manter um conjunto pequeno de modelos suportados que tenham um perfil de capacidades relativamente semelhante.
Projetando uma Interface de Busca
Um conjunto particularmente importante de ferramentas para o Claude são as ferramentas de busca que podem ser usadas para construir seu próprio contexto.
Quando o Claude Code foi lançado, usávamos um banco de dados vetorial RAG para encontrar contexto para o Claude. Embora o RAG fosse poderoso e rápido, exigia indexação e configuração, e podia ser frágil em diversos ambientes. Mais importante ainda, o Claude recebia esse contexto em vez de encontrá-lo por conta própria.
Mas se o Claude pode pesquisar na web, por que não pesquisar no seu código? Ao dar ao Claude uma ferramenta Grep, poderíamos deixá-lo buscar arquivos e construir contexto por conta própria.
Este é um padrão que observamos: à medida que o Claude fica mais inteligente, ele se torna cada vez mais capaz de construir seu contexto se receber as ferramentas certas.
Quando introduzimos o Agent Skills, formalizamos a ideia de revelação progressiva, que permite que os agentes descubram incrementalmente o contexto relevante por meio de exploração.
O Claude podia ler arquivos de skills, e esses arquivos podiam referenciar outros arquivos que o modelo podia ler recursivamente. Na verdade, um uso comum das skills é adicionar mais capacidades de busca ao Claude, como dar a ele instruções sobre como usar uma API ou consultar um banco de dados.
Ao longo de um ano, o Claude passou de não conseguir realmente construir seu próprio contexto a ser capaz de fazer buscas aninhadas em várias camadas de arquivos para encontrar exatamente o contexto de que precisava.
A revelação progressiva é agora uma técnica comum que usamos para adicionar novas funcionalidades sem adicionar uma ferramenta.
Revelação Progressiva - O Agente Claude Code Guide
O Claude Code atualmente tem cerca de 20 ferramentas, e estamos constantemente nos perguntando se precisamos de todas elas. A barreira para adicionar uma nova ferramenta é alta, pois isso dá ao modelo mais uma opção para considerar.
Por exemplo, notamos que o Claude não sabia o suficiente sobre como usar o Claude Code. Se você perguntasse como adicionar um MCP ou o que um comando de barra fazia, ele não conseguia responder.
Poderíamos ter colocado todas essas informações no prompt do sistema, mas, como os usuários raramente perguntavam sobre isso, isso teria adicionado degradação do contexto e interferido na principal função do Claude Code: escrever código.
Em vez disso, tentamos uma forma de revelação progressiva. Demos ao Claude um link para sua documentação, que ele podia carregar para buscar mais informações. Isso funcionou, mas descobrimos que o Claude carregava muitos resultados no contexto para encontrar a resposta certa, quando na verdade tudo o que você precisava era da resposta.
Então, construímos o subagente Claude Code Guide, que o Claude é instruído a chamar quando você pergunta sobre ele mesmo. O subagente tem instruções extensas sobre como pesquisar bem na documentação e o que retornar.
Embora não seja perfeito — o Claude ainda pode ficar confuso quando você pergunta como configurá-lo — está muito melhor do que costumava ser! Conseguimos adicionar coisas ao espaço de ações do Claude sem adicionar uma ferramenta.
Uma Arte, não uma Ciência
Se você esperava um conjunto de regras rígidas sobre como construir suas ferramentas, infelizmente este não é esse guia. Projetar as ferramentas para seus modelos é tanto uma arte quanto uma ciência. Depende muito do modelo que você está usando, do objetivo do agente e do ambiente em que ele opera.
Experimente com frequência, leia suas saídas, tente coisas novas. Veja como um agente.
