Pular para o conteúdo principal
A busca de ferramentas permite que seu agente trabalhe com centenas ou milhares de ferramentas descobrindo e carregando-as dinamicamente sob demanda. Em vez de carregar todas as definições de ferramentas na janela de contexto antecipadamente, o agente pesquisa seu catálogo de ferramentas e carrega apenas as ferramentas de que precisa. Esta abordagem resolve dois desafios conforme as bibliotecas de ferramentas se dimensionam:
  • Eficiência de contexto: As definições de ferramentas podem consumir grandes porções da janela de contexto (50 ferramentas podem usar 10-20K tokens), deixando menos espaço para o trabalho real.
  • Precisão da seleção de ferramentas: A precisão da seleção de ferramentas se degrada com mais de 30-50 ferramentas carregadas simultaneamente.
A busca de ferramentas está ativada por padrão. Esta página cobre como funciona, como configurá-la e como otimizar a descoberta de ferramentas.

​
Como funciona a busca de ferramentas

Quando a busca de ferramentas está ativa, as definições de ferramentas são retidas da janela de contexto. O agente recebe um resumo das ferramentas disponíveis e pesquisa as relevantes quando a tarefa requer uma capacidade não carregada. As 3-5 ferramentas mais relevantes são carregadas no contexto, onde permanecem disponíveis para turnos subsequentes. Se a conversa for longa o suficiente para que o SDK compacte mensagens anteriores para liberar espaço, as ferramentas descobertas anteriormente podem ser removidas e o agente pesquisa novamente conforme necessário. A busca de ferramentas adiciona uma viagem extra de ida e volta na primeira vez que Claude descobre uma ferramenta (a etapa de pesquisa), mas para grandes conjuntos de ferramentas isso é compensado por um contexto menor a cada turno. Com menos de ~10 ferramentas, carregar tudo antecipadamente é geralmente mais rápido. Para detalhes sobre o mecanismo de API subjacente, consulte Busca de ferramentas na API.
A busca de ferramentas requer Claude Sonnet 4 ou posterior, ou Claude Opus 4 ou posterior. Os modelos Haiku não suportam busca de ferramentas.

​
Configurar busca de ferramentas

A busca de ferramentas está ativada por padrão. Está desativada por padrão no Vertex AI, onde é suportada para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior. Também está desativada quando ANTHROPIC_BASE_URL aponta para um host não de primeira parte, já que a maioria dos proxies não encaminha blocos tool_reference. Você pode substituir qualquer padrão com a variável de ambiente ENABLE_TOOL_SEARCH:
ValorComportamento
(não definido)A busca de ferramentas está ativada. As definições de ferramentas são adiadas e descobertas sob demanda. Volta para carregamento antecipado no Vertex AI ou em um ANTHROPIC_BASE_URL não de primeira parte.
trueA busca de ferramentas está sempre ativada. O SDK envia o cabeçalho beta mesmo no Vertex AI e através de proxies. As solicitações falham em modelos Vertex AI anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam blocos tool_reference.
autoVerifica a contagem de tokens combinada de todas as definições de ferramentas em relação à janela de contexto do modelo. Se excederem 10%, a busca de ferramentas é ativada. Se estiverem abaixo de 10%, todas as ferramentas são carregadas no contexto normalmente.
auto:NO mesmo que auto com uma porcentagem personalizada. auto:5 ativa quando as definições de ferramentas excedem 5% da janela de contexto. Valores mais baixos ativam mais cedo.
falseA busca de ferramentas está desativada. Todas as definições de ferramentas são carregadas no contexto a cada turno.
A busca de ferramentas se aplica a todas as ferramentas registradas, sejam elas provenientes de servidores MCP remotos ou servidores MCP SDK personalizados. Ao usar auto, o limite é baseado no tamanho combinado de todas as definições de ferramentas em todos os servidores. Defina o valor na opção env em query(). Este exemplo se conecta a um servidor MCP remoto que expõe muitas ferramentas, pré-aprova todas elas com um curinga e usa auto:5 para que a busca de ferramentas seja ativada quando suas definições excedem 5% da janela de contexto: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
Definir ENABLE_TOOL_SEARCH como "false" desativa a busca de ferramentas e carrega todas as definições de ferramentas no contexto a cada turno. Isso remove a viagem de pesquisa, que pode ser mais rápida quando o conjunto de ferramentas é pequeno (menos de ~10 ferramentas) e as definições cabem confortavelmente na janela de contexto.

​
Otimizar descoberta de ferramentas

O mecanismo de pesquisa corresponde consultas com nomes e descrições de ferramentas. Nomes como search_slack_messages aparecem para uma gama mais ampla de solicitações do que query_slack. Descrições com palavras-chave específicas (“Pesquisar mensagens do Slack por palavra-chave, canal ou intervalo de datas”) correspondem a mais consultas do que genéricas (“Consultar Slack”). Você também pode adicionar uma seção de prompt do sistema listando categorias de ferramentas disponíveis. Isso dá ao agente contexto sobre que tipos de ferramentas estão disponíveis para pesquisar: 
You can search for tools to interact with Slack, GitHub, and Jira.

​
Limites

  • Ferramentas máximas: 10.000 ferramentas em seu catálogo
  • Resultados de pesquisa: Retorna 3-5 ferramentas mais relevantes por pesquisa
  • Suporte de modelo: Claude Sonnet 4 e posterior, Claude Opus 4 e posterior (sem Haiku)

​
Documentação relacionada