Uso de ferramentas com Claude

Claude é capaz de interagir com ferramentas e funções, permitindo que você estenda as capacidades do Claude para realizar uma variedade maior de tarefas.

Aprenda tudo o que você precisa para dominar o uso de ferramentas com Claude como parte dos nossos novos cursos! Por favor, continue a compartilhar suas ideias e sugestões usando este formulário.

Aqui está um exemplo de como fornecer ferramentas ao Claude usando a API Messages:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

Como funciona o uso de ferramentas

Claude suporta dois tipos de ferramentas:

Ferramentas do cliente: Ferramentas que executam em seus sistemas, que incluem:
- Ferramentas personalizadas definidas pelo usuário que você cria e implementa
- Ferramentas definidas pela Anthropic como uso do computador e editor de texto que requerem implementação do cliente
Ferramentas do servidor: Ferramentas que executam nos servidores da Anthropic, como as ferramentas de busca na web e busca na web. Essas ferramentas devem ser especificadas na solicitação da API, mas não requerem implementação da sua parte.

Ferramentas definidas pela Anthropic usam tipos versionados (por exemplo, web_search_20250305, text_editor_20250124) para garantir compatibilidade entre versões de modelos.

Ferramentas do cliente

Integre ferramentas do cliente com Claude nestas etapas:

Forneça ao Claude ferramentas e um prompt do usuário

Defina ferramentas do cliente com nomes, descrições e esquemas de entrada em sua solicitação da API.
Inclua um prompt do usuário que possa requerer essas ferramentas, por exemplo, “Como está o tempo em San Francisco?”

Claude decide usar uma ferramenta

Claude avalia se alguma ferramenta pode ajudar com a consulta do usuário.
Se sim, Claude constrói uma solicitação de uso de ferramenta formatada adequadamente.
Para ferramentas do cliente, a resposta da API tem um stop_reason de tool_use, sinalizando a intenção do Claude.

Execute a ferramenta e retorne os resultados

Extraia o nome da ferramenta e a entrada da solicitação do Claude
Execute o código da ferramenta em seu sistema
Retorne os resultados em uma nova mensagem user contendo um bloco de conteúdo tool_result

Claude usa o resultado da ferramenta para formular uma resposta

Claude analisa os resultados da ferramenta para elaborar sua resposta final ao prompt original do usuário.

Nota: As etapas 3 e 4 são opcionais. Para alguns fluxos de trabalho, a solicitação de uso de ferramenta do Claude (etapa 2) pode ser tudo o que você precisa, sem enviar resultados de volta ao Claude.

Ferramentas do servidor

Ferramentas do servidor seguem um fluxo de trabalho diferente:

Forneça ao Claude ferramentas e um prompt do usuário

Ferramentas do servidor, como busca na web e busca na web, têm seus próprios parâmetros.
Inclua um prompt do usuário que possa requerer essas ferramentas, por exemplo, “Busque as últimas notícias sobre IA” ou “Analise o conteúdo nesta URL.”

Claude executa a ferramenta do servidor

Claude avalia se uma ferramenta do servidor pode ajudar com a consulta do usuário.
Se sim, Claude executa a ferramenta, e os resultados são automaticamente incorporados na resposta do Claude.

Claude usa o resultado da ferramenta do servidor para formular uma resposta

Claude analisa os resultados da ferramenta do servidor para elaborar sua resposta final ao prompt original do usuário.
Nenhuma interação adicional do usuário é necessária para a execução da ferramenta do servidor.

Exemplos de uso de ferramentas

Aqui estão alguns exemplos de código demonstrando vários padrões e técnicas de uso de ferramentas. Para fins de brevidade, as ferramentas são ferramentas simples, e as descrições das ferramentas são mais curtas do que seria ideal para garantir o melhor desempenho.

Exemplo de ferramenta única

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude retornará uma resposta similar a:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Você então precisaria executar a função get_weather com a entrada fornecida, e retornar o resultado em uma nova mensagem user:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll check the current weather in San Francisco for you."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

Isso imprimirá a resposta final do Claude, incorporando os dados meteorológicos:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

Uso de ferramentas paralelas

Exemplo de múltiplas ferramentas

Você pode fornecer ao Claude múltiplas ferramentas para escolher em uma única solicitação. Aqui está um exemplo com uma ferramenta get_weather e uma get_time, junto com uma consulta do usuário que pede por ambas.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

Neste caso, Claude pode:

Usar as ferramentas sequencialmente (uma de cada vez) — chamando get_weather primeiro, depois get_time após receber o resultado do tempo
Usar chamadas de ferramentas paralelas — produzindo múltiplos blocos tool_use em uma única resposta quando as operações são independentes

Quando Claude faz chamadas de ferramentas paralelas, você deve retornar todos os resultados das ferramentas em uma única mensagem user, com cada resultado em seu próprio bloco tool_result.

Informações faltando

Se o prompt do usuário não incluir informações suficientes para preencher todos os parâmetros obrigatórios para uma ferramenta, Claude Opus é muito mais provável de reconhecer que um parâmetro está faltando e perguntar por ele. Claude Sonnet pode perguntar, especialmente quando solicitado a pensar antes de produzir uma solicitação de ferramenta. Mas também pode fazer o seu melhor para inferir um valor razoável.Por exemplo, usando a ferramenta get_weather acima, se você perguntar ao Claude “Como está o tempo?” sem especificar um local, Claude, particularmente Claude Sonnet, pode fazer uma suposição sobre as entradas das ferramentas:

JSON

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

Este comportamento não é garantido, especialmente para prompts mais ambíguos e para modelos menos inteligentes. Se Claude Opus não tiver contexto suficiente para preencher os parâmetros obrigatórios, é muito mais provável que responda com uma pergunta esclarecedora em vez de fazer uma chamada de ferramenta.

Ferramentas sequenciais

Algumas tarefas podem requerer chamar múltiplas ferramentas em sequência, usando a saída de uma ferramenta como entrada para outra. Em tal caso, Claude chamará uma ferramenta de cada vez. Se solicitado a chamar todas as ferramentas de uma vez, Claude provavelmente adivinhará parâmetros para ferramentas mais distantes se elas forem dependentes dos resultados das ferramentas mais próximas.Aqui está um exemplo de usar uma ferramenta get_location para obter a localização do usuário, depois passar essa localização para a ferramenta get_weather:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

Neste caso, Claude primeiro chamaria a ferramenta get_location para obter a localização do usuário. Depois que você retornar a localização em um tool_result, Claude então chamaria get_weather com essa localização para obter a resposta final.A conversa completa poderia parecer com:

Papel	Conteúdo
Usuário	Como está o tempo onde eu estou?
Assistente	Vou encontrar sua localização atual primeiro, depois verificar o tempo lá. [Uso de ferramenta para get_location]
Usuário	[Resultado da ferramenta para get_location com id correspondente e resultado de San Francisco, CA]
Assistente	[Uso de ferramenta para get_weather com a seguinte entrada]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Usuário	[Resultado da ferramenta para get_weather com id correspondente e resultado de “59°F (15°C), principalmente nublado”]
Assistente	Com base na sua localização atual em San Francisco, CA, o tempo agora está 59°F (15°C) e principalmente nublado. É um dia bastante fresco e encoberto na cidade. Você pode querer levar uma jaqueta leve se estiver saindo.

Este exemplo demonstra como Claude pode encadear múltiplas chamadas de ferramentas para responder uma pergunta que requer coletar dados de diferentes fontes. Os passos principais são:

Claude primeiro percebe que precisa da localização do usuário para responder a pergunta sobre o tempo, então chama a ferramenta get_location.
O usuário (ou seja, o código do cliente) executa a função get_location real e retorna o resultado “San Francisco, CA” em um bloco tool_result.
Com a localização agora conhecida, Claude procede a chamar a ferramenta get_weather, passando “San Francisco, CA” como o parâmetro location (bem como um parâmetro unit adivinhado, já que unit não é um parâmetro obrigatório).
O usuário novamente executa a função get_weather real com os argumentos fornecidos e retorna os dados meteorológicos em outro bloco tool_result.
Finalmente, Claude incorpora os dados meteorológicos em uma resposta em linguagem natural à pergunta original.

Uso de ferramentas com cadeia de pensamento

Modo JSON

Você pode usar ferramentas para fazer Claude produzir saída JSON que segue um esquema, mesmo se você não tiver intenção de executar essa saída através de uma ferramenta ou função.Ao usar ferramentas desta forma:

Você geralmente quer fornecer uma única ferramenta
Você deve definir tool_choice (veja Forçando uso de ferramenta) para instruir o modelo a usar explicitamente essa ferramenta
Lembre-se de que o modelo passará a input para a ferramenta, então o nome da ferramenta e descrição devem ser da perspectiva do modelo.

O seguinte usa uma ferramenta record_summary para descrever uma imagem seguindo um formato particular.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

Preços

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage. The additional tokens from tool use come from:

The tools parameter in API requests (tool names, descriptions, and schemas)
tool_use content blocks in API requests and responses
tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4.1	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct) (deprecated)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3 (deprecated)	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request. Consulte nossa tabela de visão geral de modelos para preços atuais por modelo. Quando você envia um prompt de uso de ferramenta, assim como qualquer outra solicitação da API, a resposta produzirá contagens de tokens de entrada e saída como parte das métricas de usage relatadas.

Próximos Passos

Explore nosso repositório de exemplos de código de uso de ferramentas prontos para implementar em nossos cookbooks:

Ferramenta Calculadora

Aprenda como integrar uma ferramenta de calculadora simples com Claude para computações numéricas precisas.

Agente de Atendimento ao Cliente

Construa um bot de atendimento ao cliente responsivo que aproveita ferramentas do cliente para melhorar o suporte.

Extrator JSON

Veja como Claude e o uso de ferramentas podem extrair dados estruturados de texto não estruturado.

Primeiros passos

Modelos e preços

Saiba mais sobre Claude

Capacidades

Ferramentas

Protocolo de Contexto do Modelo (MCP)

Casos de uso

Engenharia de prompts

Testar e avaliar

Fortalecer proteções

Centro legal

Uso de ferramentas com Claude

Como funciona o uso de ferramentas

Ferramentas do cliente

Ferramentas do servidor

Exemplos de uso de ferramentas

Preços

Próximos Passos

Ferramenta Calculadora

Agente de Atendimento ao Cliente

Extrator JSON

Primeiros passos

Modelos e preços

Saiba mais sobre Claude

Capacidades

Ferramentas

Protocolo de Contexto do Modelo (MCP)

Casos de uso

Engenharia de prompts

Testar e avaliar

Fortalecer proteções

Centro legal

​Como funciona o uso de ferramentas

​Ferramentas do cliente

​Ferramentas do servidor

​Exemplos de uso de ferramentas

​Preços

​Próximos Passos

Ferramenta Calculadora

Agente de Atendimento ao Cliente

Extrator JSON

Como funciona o uso de ferramentas

Ferramentas do cliente

Ferramentas do servidor

Exemplos de uso de ferramentas

Preços

Próximos Passos