Noções Básicas de Uso de Ferramentas

10 exemplos para você começar com Uso de Ferramentas e Chamada de Funções - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o SDK: pip install anthropic.
• Defina ANTHROPIC_API_KEY em seu ambiente - o cliente a lê automaticamente.
• from anthropic import Anthropic; client = Anthropic() é toda a configuração que estes exemplos precisam.

Exemplos Básicos

1. Definindo um Esquema de Ferramenta

Descreva uma ferramenta com um nome, uma descrição e um JSON Schema para sua entrada.

weather_tool = {
    "name": "get_weather",
    "description": "Obtém o clima atual para uma localização. Chame esta ferramenta quando o usuário perguntar sobre as condições atuais.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Cidade e estado, por exemplo, São Paulo, SP",
            }
        },
        "required": ["location"],
    },
}

• name é o identificador que o Claude usa para solicitar a ferramenta e que você corresponde em seu próprio código.
• description é o principal sinal que o Claude usa para decidir quando chamar a ferramenta - escreva-a como documentação para um colega de equipe, não como um rótulo.
• input_schema é um JSON Schema padrão; required e os valores de description por campo melhoram a confiabilidade com que o Claude preenche os argumentos.
• A definição de uma ferramenta é um dicionário Python simples - nenhuma classe especial do SDK é necessária para declará-la.

Relacionado: Definindo Esquemas de Ferramentas com Nome, Descrição e Esquema de Entrada - a referência completa de esquema

2. Enviando uma Mensagem com Ferramentas

Passe sua lista de ferramentas para messages.create junto com a conversa.

from anthropic import Anthropic
 
client = Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Qual é o clima em São Paulo, SP?"}
    ],
)

• O parâmetro tools aceita uma lista, então você pode oferecer várias ferramentas ao Claude em uma única chamada.
• O Claude só usa uma ferramenta quando a conversa realmente a exige - passar tools não força uma chamada.
• max_tokens em torno de 1024 é suficiente para um único turno de chamada de ferramenta; aumente-o se a resposta final for longa.
• model="claude-sonnet-5" é o modelo padrão para uso geral de ferramentas nesta pilha.

3. Detectando um Motivo de Parada tool_use

Verifique stop_reason antes de assumir que você tem uma resposta de texto simples.

if response.stop_reason == "tool_use":
    print("Claude quer chamar uma ferramenta")
else:
    print(response.content[0].text)

• stop_reason == "tool_use" é como o SDK informa que o Claude pausou para solicitar uma chamada de ferramenta em vez de finalizar sua resposta.
• Sempre ramifique em stop_reason em vez de adivinhar a partir da forma do conteúdo - é o sinal documentado para este estado.
• Se o Claude não precisou de uma ferramenta, response.content contém blocos de texto comuns que você pode ler diretamente.
• Pular esta verificação é a fonte mais comum de falhas quando uma chamada de ferramenta é opcional.

Relacionado: Como o Claude Decide Quando Chamar uma Ferramenta - por que algumas rodadas pulam o uso de ferramentas inteiramente

4. Extraindo a Entrada da Ferramenta

Encontre o bloco de conteúdo tool_use e leia seus argumentos gerados.

tool_use_block = next(
    block for block in response.content if block.type == "tool_use"
)
 
tool_name = tool_use_block.name
tool_input = tool_use_block.input
tool_id = tool_use_block.id
 
print(tool_name, tool_input, tool_id)

• response.content é uma lista de blocos de conteúdo; um turno tool_use pode misturar um bloco text com um ou mais blocos tool_use.
• block.input já é um dicionário Python analisado que corresponde ao seu input_schema - nenhuma decodificação JSON é necessária.
• block.id é o valor que você deve ecoar de volta mais tarde no tool_result correspondente, então capture-o agora.
• block.name diz qual ferramenta executar quando você tem mais de uma definida.

5. Executando Sua Função de Ferramenta

Execute seu próprio código com os argumentos que o Claude gerou.

def get_weather(location: str) -> str:
    # Substitua por uma chamada real de API de clima.
    return f"22°C e ensolarado em {location}"
 
if tool_name == "get_weather":
    result = get_weather(**tool_input)

• O Claude nunca executa código sozinho - ele apenas produz o nome e a entrada da ferramenta; executar a ferramenta é inteiramente sua responsabilidade.
• Desempacotar tool_input com ** funciona de forma limpa quando os nomes dos parâmetros da sua função correspondem às chaves properties do esquema.
• Trate tool_input como qualquer outra entrada externa - valide-a antes de usá-la em caminhos de arquivo, consultas ou comandos de shell.
• Mantenha o valor de retorno da função como uma string simples ou uma estrutura serializável em JSON para que seja fácil devolvê-la como um tool_result.

6. Retornando um Bloco tool_result

Envie a saída da ferramenta de volta para o Claude como uma nova mensagem do usuário.

messages = [
    {"role": "user", "content": "Qual é o clima em São Paulo, SP?"},
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_id,
                "content": result,
            }
        ],
    },
]
 
final_response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=messages,
)
 
print(final_response.content[0].text)

• O turno do assistente que você anexa deve ser response.content verbatim - ele preserva o bloco tool_use exato que o Claude gerou, incluindo seu id.
• tool_use_id deve corresponder ao id do bloco tool_use ao qual ele responde, para que o Claude possa emparelhar a solicitação com seu resultado.
• O bloco tool_result sempre vai em uma mensagem com o papel user, mesmo que seja realmente uma resposta da máquina, não algo que o humano digitou.
• A segunda chamada messages.create é uma nova solicitação com todo o histórico anexado - o Claude só vê turnos anteriores que você inclui explicitamente.

Relacionado: Manipulando Solicitações de Uso de Ferramentas e Retornando Blocos tool_result - a referência completa do ciclo completo

7. Tratando Erros de Execução de Ferramenta

Informe ao Claude que uma chamada de ferramenta falhou em vez de ignorá-la silenciosamente.

try:
    result = get_weather(**tool_input)
    tool_result_content = result
    is_error = False
except Exception as exc:
    tool_result_content = f"Falha na execução da ferramenta: {exc}"
    is_error = True
 
tool_result_block = {
    "type": "tool_result",
    "tool_use_id": tool_id,
    "content": tool_result_content,
    "is_error": is_error,
}

• Defina "is_error": true no bloco tool_result quando sua função levantar uma exceção ou a chamada de API subjacente falhar.
• Uma string de erro informativa permite que o Claude decida o que fazer a seguir - tentar novamente, pedir esclarecimentos ao usuário ou explicar a falha.
• Nunca omita o tool_result para um bloco tool_use, mesmo em caso de falha - a conversa fica malformada se uma chamada de ferramenta for deixada sem resposta.
• Envolver a execução da ferramenta em try/except impede que uma única chamada de API ruim derrube todo o seu manipulador de solicitação.

Exemplos Intermediários

8. Ciclo Completo: Da Pergunta do Usuário à Resposta Final

Encadeie todos os passos acima em um loop de trabalho.

from anthropic import Anthropic
 
client = Anthropic()
 
weather_tool = {
    "name": "get_weather",
    "description": "Obtém o clima atual para uma localização. Chame esta ferramenta quando o usuário perguntar sobre as condições atuais.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "Cidade e estado, por exemplo, São Paulo, SP"}
        },
        "required": ["location"],
    },
}
 
def get_weather(location: str) -> str:
    return f"22°C e ensolarado em {location}"
 
messages = [{"role": "user", "content": "Devo levar um guarda-chuva em São Paulo, SP hoje?"}]
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=messages,
)
 
if response.stop_reason == "tool_use":
    tool_use_block = next(b for b in response.content if b.type == "tool_use")
    result = get_weather(**tool_use_block.input)
 
    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use_block.id, "content": result}
        ],
    })
 
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=[weather_tool],
        messages=messages,
    )
 
print(response.content[0].text)

• Este é o mesmo ciclo de cinco passos - criar, detectar tool_use, executar, anexar tool_result, criar novamente - escrito como um único script.
• Reutilizar a lista messages com .append() mantém todo o histórico da conversa intacto para a segunda chamada.
• A segunda chamada messages.create ainda passa tools=[weather_tool], pois o Claude pode legítimamente precisar chamar a ferramenta novamente.
• Em produção, essa lógica geralmente é encapsulada em um loop while response.stop_reason == "tool_use": para lidar com qualquer número de chamadas de ferramenta.

Relacionado: Construindo um Loop de Uso de Ferramentas Multi-Turno - generalizando isso em um loop reutilizável

9. Manipulando Múltiplos Blocos tool_use em um Único Turno

Itere sobre cada bloco tool_use, pois o Claude pode solicitar várias ferramentas em um único turno.

tool_result_blocks = []
 
for block in response.content:
    if block.type != "tool_use":
        continue
 
    if block.name == "get_weather":
        output = get_weather(**block.input)
    else:
        output = f"Ferramenta desconhecida: {block.name}"
 
    tool_result_blocks.append(
        {"type": "tool_result", "tool_use_id": block.id, "content": output}
    )
 
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_result_blocks})

• Um único turno de assistente pode conter mais de um bloco tool_use - filtre response.content por type == "tool_use" em vez de assumir exatamente um.
• Cada bloco tool_use precisa de seu próprio bloco tool_result correspondente na mensagem do usuário subsequente, cada um com seu próprio tool_use_id.
• Todos os blocos tool_result para um turno vão juntos em uma única lista content da mensagem do usuário, não como mensagens separadas.
• Ramificar em block.name é como você despacha para a função Python correta quando várias ferramentas são definidas.

Relacionado: Executando Chamadas de Ferramentas Paralelas em um Único Turno - mais sobre o agrupamento de resultados de ferramentas

10. Escolhendo Entre Ferramentas com tool_choice

Use tool_choice para forçar, restringir ou deixar em aberto qual ferramenta o Claude escolhe.

calculate_tool = {
    "name": "calculate",
    "description": "Avalia uma expressão aritmética básica. Chame esta ferramenta para qualquer pergunta de matemática.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {"type": "string", "description": "por exemplo, 12 * (4 + 1)"}
        },
        "required": ["expression"],
    },
}
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool, calculate_tool],
    tool_choice={"type": "tool", "name": "calculate"},
    messages=[{"role": "user", "content": "Quanto é 12 vezes 5?"}],
)

• tool_choice={"type": "tool", "name": "calculate"} força o Claude a chamar essa ferramenta específica em vez de escolher por conta própria.
• Deixar tool_choice indefinido é equivalente a {"type": "auto"} - o Claude decide se e qual ferramenta usar com base nas descrições.
• {"type": "any"} requer alguma chamada de ferramenta, mas permite que o Claude escolha qual; {"type": "none"} desabilita as chamadas de ferramenta para esse turno.
• Forçar uma ferramenta é útil para testar o esquema de uma única ferramenta isoladamente, sem depender da própria decisão de roteamento do Claude.

Relacionado: Referência de Opções de Escolha de Ferramenta - todos os modos de tool_choice em detalhes

Versões da Pilha: Escrito contra a linha de modelos Claude atual em aproximadamente Junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.