Ferramentas

Claude Managed Agents fornece um conjunto de ferramentas integradas que Claude pode usar autonomamente dentro de uma sessão. Você controla quais ferramentas estão disponíveis especificando-as na configuração do agente.

Ferramentas personalizadas definidas pelo usuário também são suportadas. Sua aplicação executa essas ferramentas separadamente e envia os resultados da ferramenta de volta para Claude; Claude pode usar os resultados para continuar a tarefa em questão.

Ferramentas disponíveis

O conjunto de ferramentas do agente inclui as seguintes ferramentas. Todas são habilitadas por padrão quando você inclui o conjunto de ferramentas na configuração do seu agente.

Configurando o conjunto de ferramentas

Habilite o conjunto de ferramentas completo com agent_toolset_20260401 ao criar um agente. Use o array configs para desabilitar ferramentas específicas ou substituir suas configurações.

Desabilitando ferramentas específicas

Para desabilitar uma ferramenta, defina enabled: false em sua entrada de configuração:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

Habilitando apenas ferramentas específicas

Para começar com tudo desligado e habilitar apenas o que você precisa, defina default_config.enabled como false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

Ferramentas personalizadas

Além das ferramentas integradas, você pode definir ferramentas personalizadas. As ferramentas personalizadas são análogas às ferramentas personalizadas definidas pelo usuário na API Messages.

As ferramentas personalizadas permitem que você estenda os recursos do Claude para realizar uma variedade maior de tarefas. Cada ferramenta define um contrato: você especifica quais operações estão disponíveis e o que elas retornam; Claude decide quando e como chamá-las. O modelo nunca executa nada por conta própria. Ele emite uma solicitação estruturada, seu código executa a operação e o resultado flui de volta para a conversa.

Depois de definir a ferramenta no nível do agente, o agente invocará as ferramentas ao longo de uma sessão. Consulte Fluxo de eventos da sessão para o fluxo completo.

Melhores práticas para definições de ferramentas personalizadas

• Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho da ferramenta. Suas descrições devem explicar o que a ferramenta faz, quando deve ser usada (e quando não deve), o que cada parâmetro significa e como afeta o comportamento da ferramenta, e quaisquer ressalvas ou limitações importantes. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Procure por pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
• Consolide operações relacionadas em menos ferramentas. Em vez de criar uma ferramenta separada para cada ação (create_pr, review_pr, merge_pr), agrupe-as em uma única ferramenta com um parâmetro action. Menos ferramentas, mais capazes, reduzem a ambiguidade de seleção e tornam sua superfície de ferramentas mais fácil para Claude navegar.
• Use namespacing significativo em nomes de ferramentas. Quando suas ferramentas abrangem múltiplos serviços ou recursos, prefixe nomes com o recurso (por exemplo, db_query, storage_read). Isso torna a seleção de ferramentas inequívoca conforme sua biblioteca cresce.
• Projete respostas de ferramentas para retornar apenas informações de alto sinal. Retorne identificadores semânticos e estáveis (por exemplo, slugs ou UUIDs) em vez de referências internas opacas, e inclua apenas os campos que Claude precisa para raciocinar sobre seu próximo passo. Respostas inchadas desperdiçam contexto e tornam mais difícil para Claude extrair o que importa.