Uma das partes mais difíceis de construir um harness para agentes é estruturar seu espaço de ação.
O Claude age por meio de Tool Calling, mas há várias maneiras 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 do @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 você sabe quais são essas habilidades? Você presta atenção, lê suas saídas, experimenta. Você aprende a enxergar como um agente.
Aqui estão algumas lições que aprendemos prestando atenção no Claude enquanto construíamos 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 (frequentemente 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 coisa mais fácil de implementar, 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 prompt caching
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 bullet points 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 adicionava frases extras, omitia opções ou usava um formato totalmente diferente.
Tentativa #3 - A ferramenta AskUserQuestion
Finalmente, 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 fosse acionada, mostraríamos 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 ter uma saída estruturada e nos ajudou a garantir que o Claude desse ao usuário múltiplas opções. Também deu aos usuários maneiras de compor essa funcionalidade, por exemplo, chamando-a no Agent SDK ou usando-a em skills.
Mais importante ainda, o Claude parecia gostar de chamar essa ferramenta e descobrimos que suas saídas funcionavam bem. Mesmo a ferramenta melhor projetada não funciona se o Claude não entender como chamá-la.
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 e Todos
Quando lançamos o Claude Code pela primeira vez, percebemos que o modelo precisava de uma lista de Tarefas (Todo list) 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 para o usuário.
Mas, mesmo assim, muitas vezes víamos o Claude esquecendo o que tinha que fazer. Para nos adaptarmos, inserimos lembretes de 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 seguir a lista 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 em uma Lista de Tarefas compartilhada?
Vendo isso, substituímos o TodoWrite pela Ferramenta de Tarefas (Task Tool) (leia mais sobre Tarefas aqui). Enquanto as Tarefas (Todos) eram sobre manter o modelo no caminho certo, as Tarefas (Tasks) eram mais sobre ajudar os agentes a se comunicarem entre si. As Tarefas (Tasks) podiam incluir dependências, compartilhar atualizações entre subagentes, e o modelo podia alterá-las e excluí-las.
À medida que as capacidades do modelo aumentam, as ferramentas que seus modelos antes precisavam podem agora estar os limitando. É importante revisitar constantemente suposições anteriores sobre quais ferramentas são necessárias. Isso também é por que é útil manter um conjunto pequeno de modelos suportados que tenham um perfil de capacidades razoavelmente 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 si só.
Mas se o Claude pode pesquisar na web, por que não pesquisar em sua base de código? Ao dar ao Claude uma ferramenta Grep, poderíamos deixá-lo pesquisar arquivos e construir seu próprio contexto.
Este é um padrão que temos visto: à medida que o Claude fica mais inteligente, ele se torna cada vez melhor em construir seu contexto se receber as ferramentas certas.
Quando introduzimos as Agent Skills, formalizamos a ideia de divulgação progressiva (progressive disclosure), que permite que os agentes descubram incrementalmente o contexto relevante por meio de exploração.
O Claude podia ler arquivos de skill, 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 divulgação progressiva é agora uma técnica comum que usamos para adicionar novas funcionalidades sem adicionar uma ferramenta.
Divulgação Progressiva - O Agente Guia do Claude Code
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, porque 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 contexto desnecessário (context rot) e interferido na função principal do Claude Code: escrever código.
Em vez disso, tentamos uma forma de divulgação progressiva. Demos ao Claude um link para sua documentação, que ele poderia carregar para pesquisar 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 isso 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ção 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 está operando.
Experimente com frequência, leia suas saídas, tente coisas novas. Enxergue como um agente.
