Uso de ferramentas com Claude

O "tool use" (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, ele 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-5",
    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 que Claude chame 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. Como o uso de ferramentas funciona mostra essa ida e volta de ponta a ponta. Saiba mais sobre definir ferramentas e lidar com chamadas de ferramentas.



Como o uso de ferramentas funciona

As ferramentas diferem principalmente pelo local 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).

Aqui está essa ida e volta completa para uma ferramenta do cliente. A primeira solicitação define uma ferramenta get_weather, e Claude responde à pergunta chamando-a: a resposta carrega um bloco tool_use, seu código executa a consulta, e uma segunda solicitação envia o resultado de volta em um bloco tool_result para que Claude possa responder com a resposta.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude responde com um bloco tool_use nomeando a ferramenta e seus argumentos.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # Peça no máximo uma chamada de ferramenta por turno.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude usa o resultado para responder à pergunta original.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Lidar com chamadas de ferramentas cobre cada etapa em detalhes, incluindo formatação de resultados e sinalização de erros; Uso de ferramentas em paralelo cobre respostas que chamam várias ferramentas de uma vez. Para evitar escrever essa ida e volta você mesmo, use o Tool Runner: os SDKs executam suas ferramentas e enviam os resultados de volta automaticamente.

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

Para se conectar a servidores do Model Context Protocol (MCP), consulte o conector MCP. Para construir seu próprio cliente MCP, consulte o guia do Model Context Protocol sobre como construir 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 é direcionável 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 prompting, defina tool_choice.

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



Escolha uma ferramenta

Para strings de type, versões e cabeçalhos beta, consulte a 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 solicitaçõ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 solicitação da API do Claude, embora ferramentas do lado do servidor possam 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 solicitações da API (nomes, descrições e esquemas de ferramentas)
• Blocos de conteúdo tool_use nas solicitações e respostas da API
• Blocos de conteúdo tool_result nas solicitações da 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ário para cada modelo está listado na tabela a seguir (excluindo os tokens adicionais listados anteriormente). 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 solicitaçã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 as contagens de tokens de entrada e saída nas métricas de usage relatadas.

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



Próximos passos