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-sonnet-4-5",
    "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:
  1. 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 de computador e editor de texto que requerem implementação do cliente
  2. 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:
1

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?”
2

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.
3

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
4

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:
1

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.”
2

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.
3

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 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. 
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-sonnet-4-5",
    "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-sonnet-4-5",
  "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-sonnet-4-5",
    "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-sonnet-4-5",
  "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!"
    }
  ]
}
Claude pode chamar múltiplas ferramentas em paralelo dentro de uma única resposta, o que é útil para tarefas que requerem múltiplas operações independentes. Ao usar ferramentas paralelas, todos os blocos tool_use são incluídos em uma única mensagem do assistente, e todos os blocos tool_result correspondentes devem ser fornecidos na mensagem subsequente do usuário.
Importante: Os resultados das ferramentas devem ser formatados corretamente para evitar erros da API e garantir que Claude continue usando ferramentas paralelas. Veja nosso guia de implementação para requisitos detalhados de formatação e exemplos de código completos.
Para exemplos abrangentes, scripts de teste e melhores práticas para implementar chamadas de ferramentas paralelas, veja a seção de uso de ferramentas paralelas em nosso guia de implementação.
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 ferramenta 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-sonnet-4-5",
    "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.
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á ausente 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.
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 downstream se elas forem dependentes dos resultados das ferramentas para ferramentas mais upstream.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-sonnet-4-5",
    "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:
PapelConteúdo
UsuárioComo está o tempo onde eu estou?
AssistenteVou 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”]
AssistenteCom 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:
  1. 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.
  2. 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.
  3. 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).
  4. 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.
  5. Finalmente, Claude incorpora os dados meteorológicos em uma resposta em linguagem natural à pergunta original.
Por padrão, Claude Opus é solicitado a pensar antes de responder uma consulta de uso de ferramenta para melhor determinar se uma ferramenta é necessária, qual ferramenta usar e os parâmetros apropriados. Claude Sonnet e Claude Haiku são solicitados a tentar usar ferramentas o máximo possível e são mais propensos a chamar uma ferramenta desnecessária ou inferir parâmetros ausentes. Para solicitar que Sonnet ou Haiku avaliem melhor a consulta do usuário antes de fazer chamadas de ferramentas, o seguinte prompt pode ser usado:Prompt de cadeia de pensamentoResponda à solicitação do usuário usando ferramentas relevantes (se estiverem disponíveis). Antes de chamar uma ferramenta, faça alguma análise. Primeiro, pense sobre qual das ferramentas fornecidas é a ferramenta relevante para responder à solicitação do usuário. Segundo, passe por cada um dos parâmetros obrigatórios da ferramenta relevante e determine se o usuário forneceu diretamente ou deu informações suficientes para inferir um valor. Ao decidir se o parâmetro pode ser inferido, considere cuidadosamente todo o contexto para ver se ele suporta um valor específico. Se todos os parâmetros obrigatórios estiverem presentes ou puderem ser razoavelmente inferidos, proceda com a chamada da ferramenta. MAS, se um dos valores para um parâmetro obrigatório estiver ausente, NÃO invoque a função (nem mesmo com preenchimentos para os parâmetros ausentes) e, em vez disso, peça ao usuário para fornecer os parâmetros ausentes. NÃO peça mais informações sobre parâmetros opcionais se não for fornecido.
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 a 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-sonnet-4-5",
    "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:
  1. The total number of input tokens sent to the model (including in the tools parameter)
  2. The number of output tokens generated
  3. 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.
ModelTool choiceTool use system prompt token count
Claude Opus 4.1auto, none
any, tool		346 tokens
313 tokens
Claude Opus 4auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 4.5auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 4auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 3.7auto, 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 4.5auto, none
any, tool		346 tokens
313 tokens
Claude Haiku 3.5auto, none
any, tool		264 tokens
340 tokens
Claude Opus 3 (deprecated)auto, none
any, tool		530 tokens
281 tokens
Claude Sonnet 3auto, none
any, tool		159 tokens
235 tokens
Claude Haiku 3auto, 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.