TutoriaisAtualizado em 29 de setembro de 20264 min de leitura

Tool use na API do Claude: como o Claude chama funções do seu código

Tool use, também chamado de function calling, é o recurso que deixa o Claude pedir para o seu código executar uma função: consultar um pedido, buscar um cliente no banco, chamar outra API. O modelo decide quando precisa da ferramenta e com quais argumentos; o seu código executa e devolve o resultado.

Neste guia você monta um exemplo completo em Python com o Claude Opus 5. Se o seu código usa o function calling da OpenAI, o guia Migrar da OpenAI para o Claude mostra o que muda.

Como funciona

1. Você envia a pergunta e a lista de ferramentas disponíveis, cada uma com nome, descrição e o formato dos argumentos (JSON Schema).
2. Se precisar de uma ferramenta, o Claude responde com um bloco tool_use, com o nome da ferramenta e os argumentos. O stop_reason vem como "tool_use".
3. O seu código executa a função e manda o resultado de volta num bloco tool_result.
4. O Claude usa o resultado para continuar, e pode pedir outras ferramentas, até responder com o texto final.

O Claude nunca executa nada sozinho no seu sistema: quem executa é o seu código, e você controla o que cada ferramenta pode fazer.

Definindo uma ferramenta

Uma ferramenta de exemplo, que consulta o status de um pedido de loja virtual:

ferramentas = [
    {
        "name": "consultar_pedido",
        "description": "Consulta o status e a previsão de entrega de um pedido pelo número. "
                       "Use quando o cliente perguntar sobre um pedido.",
        "input_schema": {
            "type": "object",
            "properties": {
                "numero": {"type": "string", "description": "Número do pedido, ex.: 10231"}
            },
            "required": ["numero"],
        },
    }
]

A descrição importa: é por ela que o modelo decide quando usar a ferramenta. Diga o que ela faz e quando deve ser usada.

O loop completo

import json
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_BASE_URL=https://api.open33.tech

PEDIDOS = {
    "10231": {"status": "em transporte", "previsao": "2026-10-02"},
    "10232": {"status": "entregue", "previsao": "2026-09-20"},
}

def consultar_pedido(numero: str) -> dict:
    pedido = PEDIDOS.get(numero)
    if pedido is None:
        raise ValueError(f"Pedido {numero} não encontrado")
    return pedido

FUNCOES = {"consultar_pedido": consultar_pedido}

mensagens = [{"role": "user", "content": "Cadê meu pedido 10231? E o 99999?"}]

while True:
    resposta = client.messages.create(
        model="claude-opus-5",
        max_tokens=16000,
        system="Você é o atendimento da loja. Responda em português, de forma curta.",
        tools=ferramentas,
        messages=mensagens,
    )

    if resposta.stop_reason != "tool_use":
        break  # resposta final

    # guarda a resposta do modelo, com os blocos tool_use
    mensagens.append({"role": "assistant", "content": resposta.content})

    # executa todas as ferramentas pedidas e devolve TODOS os resultados numa só mensagem
    resultados = []
    for bloco in resposta.content:
        if bloco.type != "tool_use":
            continue
        try:
            saida = FUNCOES[bloco.name](**bloco.input)
            resultados.append({
                "type": "tool_result",
                "tool_use_id": bloco.id,
                "content": json.dumps(saida, ensure_ascii=False),
            })
        except Exception as erro:
            resultados.append({
                "type": "tool_result",
                "tool_use_id": bloco.id,
                "content": f"Erro: {erro}",
                "is_error": True,
            })
    mensagens.append({"role": "user", "content": resultados})

print("".join(b.text for b in resposta.content if b.type == "text"))

O que esse loop faz certo:

• Devolve todos os resultados numa só mensagem. O Claude pode pedir várias ferramentas de uma vez (no exemplo, os dois pedidos). Mandar cada resultado numa mensagem separada ensina o modelo a parar de fazer chamadas em paralelo.
• Usa tool_use_id para ligar cada resultado ao pedido certo.
• Não esconde erros. Quando a função falha, o resultado vai com is_error: True e uma mensagem clara. O modelo explica o problema ao usuário em vez de inventar uma resposta.
• Lê os argumentos como objeto (bloco.input), sem tentar interpretar texto na mão.

Boas práticas

• Poucas ferramentas, bem descritas. Nomes claros e descrições objetivas ajudam o modelo a escolher certo.
• Valide os argumentos antes de executar, principalmente em ferramentas que alteram dados.
• Limite o poder de cada ferramenta. Uma ferramenta de leitura não deve conseguir apagar nada.
• Argumentos garantidos: marcar a ferramenta com "strict": True (junto de "additionalProperties": False no schema) faz a API garantir que os argumentos sigam o schema.
• Confirme ações sensíveis (pagamento, exclusão, envio de e-mail) com o usuário antes de executar.
• Precisa só de dados em JSON, sem executar nada? Use as saídas estruturadas em vez de uma ferramenta.