Como usar ferramentas (tool use) na API do Claude com Python, passo a passo

O tool use (uso de ferramentas) permite que o Claude chame funções definidas por você, como consultar o clima, buscar um pedido ou ler um banco de dados. O modelo não executa nada sozinho: ele devolve um pedido estruturado, seu código roda a função e envia o resultado de volta. Este tutorial mostra o ciclo completo em Python, a partir do exemplo da documentação oficial da Anthropic.

Como o ciclo funciona

A documentação divide as ferramentas em dois tipos. As ferramentas de cliente rodam na sua aplicação: o Claude responde com stop_reason: "tool_use" e um ou mais blocos tool_use, seu código executa a operação e envia um tool_result. As ferramentas de servidor, como busca na web, rodam na infraestrutura da Anthropic, sem código seu. Aqui o foco é a ferramenta de cliente.

O ciclo tem quatro etapas:

1. Você envia a pergunta junto com a definição das ferramentas.
2. O Claude responde com um bloco tool_use, com o nome da ferramenta e os argumentos.
3. Seu código executa a função e monta um bloco tool_result.
4. Você envia o resultado de volta, e o Claude escreve a resposta final.

Pré-requisitos

• Python 3 e a biblioteca oficial: pip install anthropic.
• Chave de API na variável de ambiente ANTHROPIC_API_KEY. Não escreva a chave no código.

Passo 1: definir a ferramenta

Cada ferramenta tem name, description e um input_schema em JSON Schema. A descrição é o que o Claude usa para decidir se deve chamar a ferramenta, então escreva-a com clareza.

import json
import anthropic

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?"}]

Passo 2: enviar a pergunta e receber o tool_use

A chamada abaixo segue o exemplo da documentação, com o modelo claude-haiku-5-5. A página de ferramentas lista o Haiku 5.5 entre os modelos que suportam tool use. O parâmetro disable_parallel_tool_use pede no máximo uma chamada de ferramenta por turno, o que simplifica o código.

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=2048,
    tools=tools,
    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)}")

Com tool_choice em auto, o Claude decide a cada turno se chama uma ferramenta ou responde direto. O max_tokens está em 2048 porque o Haiku 5.5 raciocina por padrão e esse raciocínio conta dentro do limite.

Saída esperada, segundo a documentação:

Claude called get_weather with {"location": "San Francisco, CA"}

Passo 3: executar a função e devolver o tool_result

No exemplo oficial, o clima vem de um texto fixo. Troque pela sua função real ou por uma chamada a uma API de previsão do tempo. O ponto central é devolver o resultado em um bloco tool_result que cite o id do tool_use, junto com a mensagem do assistente que o continha:

weather = "15 degrees Celsius, partly cloudy"  # sua consulta de clima entra aqui

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-haiku-5-5",
    max_tokens=2048,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

O ponto de atenção é o tool_use_id: ele liga o resultado ao pedido. Sem essa ligação, a API rejeita a requisição.

Resultado esperado

A segunda chamada devolve a resposta final em linguagem natural. O texto exato muda a cada execução, mas na documentação o exemplo é parecido com este:

The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Passo 4: dicas para ferramentas melhores

• Influencie quando o Claude usa ferramentas: a documentação diz que uma instrução leve no prompt de sistema, como "Use the tools to investigate before responding", aumenta o uso; uma instrução mais forte empurra ainda mais.
• Force uma chamada: para exigir o uso de ferramenta sem depender de prompt, defina o tool_choice.
• Garanta o formato dos argumentos: adicione strict: true à definição para que as chamadas sempre sigam o seu esquema.
• Menos código de laço: a documentação cita o Tool Runner do SDK, que executa as ferramentas e reenvia os resultados automaticamente.

Erros comuns

• Esquecer a mensagem do assistente: o histórico precisa conter a resposta anterior (response.content) antes do tool_result.
• tool_use_id errado: use o id do bloco tool_use devolvido pela API.
• Parâmetro obrigatório ausente: se a pergunta não traz todos os dados exigidos, o Claude pode pedir o dado ou inferir um valor. Segundo a documentação, os modelos Opus tendem a perguntar mais, e esse comportamento não é garantido.
• Resposta cortada: com raciocínio ativo, max_tokens baixo pode truncar a saída.
• Custo: os esquemas das ferramentas e os blocos tool_use e tool_result contam como tokens. A documentação informa que, com uma ou mais ferramentas, a API adiciona um prompt de sistema próprio de uso de ferramentas, que custa 286 tokens no Haiku 5.5 com tool_choice em auto.

Próximos passos

Para um agente de verdade, repita os passos 2 e 3 em um laço até o stop_reason deixar de ser tool_use. A própria documentação tem um tutorial para construir um agente com ferramentas, do primeiro chamado até um laço de produção.