Uso de ferramentas com Claude

O uso de ferramentas permite que Claude chame funções que você define ou que a Anthropic fornece. Claude determina quando chamar uma ferramenta com base na solicitação do usuário e na descrição da ferramenta. Em seguida, retorna uma chamada estruturada que sua aplicação executa (ferramentas do cliente) ou que a Anthropic executa (ferramentas do servidor).

Aqui está um exemplo mínimo usando uma ferramenta do servidor, a ferramenta de busca na web, que a Anthropic executa para você:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude executa a busca na infraestrutura da Anthropic e retorna os resultados citados na mesma resposta. Para fazer Claude chamar uma função que você define, passe uma ferramenta com um input_schema e, em seguida, execute a chamada quando Claude retornar um bloco tool_use. Definir ferramentas e Lidar com chamadas de ferramentas cobrem esse ciclo completo.



Como o uso de ferramentas funciona

As ferramentas diferem principalmente por onde o código é executado. Ferramentas do cliente (incluindo ferramentas definidas pelo usuário e ferramentas com esquemas definidos pela Anthropic, como bash e text_editor) são executadas na sua aplicação. Claude responde com stop_reason: "tool_use" e um ou mais blocos tool_use. Seu código executa a operação e envia de volta um tool_result. Ferramentas do servidor (como web_search, web_fetch, code_execution e tool_search) são executadas na infraestrutura da Anthropic: você vê os resultados diretamente sem lidar com a execução, a menos que Claude chame a ferramenta no mesmo grupo de chamadas de ferramentas paralelas que uma de suas ferramentas do cliente (consulte Motivos de parada e fallback).

Para o modelo conceitual completo, incluindo o loop agêntico e quando escolher cada abordagem, consulte Como o uso de ferramentas funciona.

Para conectar-se a servidores do "Model Context Protocol", ou MCP, consulte o conector MCP. Para criar seu próprio cliente MCP, consulte o guia do Model Context Protocol para criar um cliente MCP.



Quando Claude usa ferramentas

Com o tool_choice padrão de {"type": "auto"}, Claude determina a cada turno se deve chamar uma ferramenta ou responder diretamente. Ele chama uma ferramenta quando a solicitação corresponde à capacidade descrita dessa ferramenta e a resposta ainda não está no contexto. Ele responde diretamente para conhecimento estável, tarefas criativas e turnos conversacionais.

Esse limite pode ser direcionado por meio do seu prompt do sistema. Se Claude não estiver chamando ferramentas quando você espera, uma instrução leve como "Use the tools to investigate before responding." aumenta o uso de ferramentas. Uma forma mais forte como "Always call a tool first before responding." vai além. Por outro lado, "Use your judgment about whether to call a tool or respond directly." mantém o comportamento de acionamento conservador.

Para exigir uma chamada de ferramenta em vez de depender de prompts, defina tool_choice.

A página de cada ferramenta do servidor descreve seu próprio limite de acionamento com mais detalhes.



Escolha uma ferramenta

Para strings de type, versões e cabeçalhos beta, consulte Referência de ferramentas.



Suas próprias ferramentas

Para ferramentas que você define, você escreve o esquema e sua aplicação executa cada chamada.



Ferramentas do cliente com esquema da Anthropic

A Anthropic publica o esquema e treina Claude nele. Sua aplicação ainda executa cada chamada e retorna o tool_result.



Ferramentas do servidor

As ferramentas do servidor são executadas na infraestrutura da Anthropic, sem código de manipulação na sua aplicação. Consulte Ferramentas do servidor para a mecânica que elas compartilham.



Preços

As requisições de uso de ferramentas são precificadas com base em:

1. O número total de tokens de entrada enviados ao modelo (incluindo no parâmetro tools)
2. O número de tokens de saída gerados
3. Para ferramentas do lado do servidor, precificação adicional baseada em uso (por exemplo, a busca na web cobra por busca realizada)

Ferramentas do lado do cliente são precificadas da mesma forma que qualquer outra requisição à API do Claude, enquanto ferramentas do lado do servidor podem incorrer em cobranças adicionais com base em seu uso específico.

Os tokens adicionais do uso de ferramentas vêm de:

• O parâmetro tools nas requisições de API (nomes, descrições e esquemas de ferramentas)
• Blocos de conteúdo tool_use em requisições e respostas de API
• Blocos de conteúdo tool_result em requisições de API

Quando você usa tools, a API também inclui automaticamente um prompt do sistema especial para o modelo que habilita o uso de ferramentas. O número de tokens de uso de ferramentas necessários para cada modelo está listado abaixo (excluindo os tokens adicionais listados acima). Observe que a tabela pressupõe que pelo menos 1 ferramenta seja fornecida. Se nenhuma tools for fornecida, então uma escolha de ferramenta none usa 0 tokens adicionais de prompt do sistema.

Essas contagens de tokens são adicionadas aos seus tokens normais de entrada e saída para calcular o custo total de uma requisição.

Consulte a tabela de Visão geral dos modelos para os preços atuais por modelo.

Quando você envia um prompt de uso de ferramentas, como qualquer outra solicitação de API, a resposta inclui contagens de tokens de entrada e saída nas métricas de usage reportadas.

Algumas ferramentas do servidor adicionam cobranças baseadas em uso além dos tokens: consulte Ferramenta de busca na web e Ferramenta de execução de código para suas taxas.



Próximos passos