Uso de ferramentas com Claude

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

Aprenda tudo o que você precisa para dominar o uso de ferramentas com Claude através do nosso novo curso abrangente sobre uso de ferramentas! Continue compartilhando suas ideias e sugestões usando este formulário.

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

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-20250514",
    "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

O Claude suporta dois tipos de ferramentas:

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

As 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 o 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 de API.
Inclua um prompt do usuário que possa exigir essas ferramentas, por exemplo, “Como está o clima em São 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 corretamente.
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

As ferramentas do servidor seguem um fluxo de trabalho diferente:

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

Ferramentas do servidor, como pesquisa na web, têm seus próprios parâmetros.
Inclua um prompt do usuário que possa exigir essas ferramentas, por exemplo, “Pesquise as últimas notícias sobre IA.”

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. Por questão de brevidade, as ferramentas são 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-20250514",
    "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?"}]
}'

O Claude retornará uma resposta semelhante a:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Você precisaria então 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-20250514",
    "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": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "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-20250514",
  "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!"
    }
  ]
}

Exemplo de múltiplas ferramentas

Você pode fornecer ao Claude várias ferramentas para escolher em uma única solicitação. Aqui está um exemplo com as ferramentas get_weather e get_time, junto com uma consulta do usuário que pede 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-20250514",
    "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, o Claude provavelmente tentará usar duas ferramentas separadas, uma de cada vez — get_weather e depois get_time — para responder completamente à pergunta do usuário. No entanto, ocasionalmente também pode produzir dois blocos tool_use de uma vez, particularmente se eles não forem dependentes um do outro. Você precisaria executar cada ferramenta e retornar seus resultados em blocos tool_result separados dentro de uma única mensagem user.

Informações ausentes

Se o prompt do usuário não incluir informações suficientes para preencher todos os parâmetros necessários para uma ferramenta, o Claude Opus tem muito mais probabilidade de reconhecer que um parâmetro está faltando e perguntar por ele. O Claude Sonnet pode perguntar, especialmente quando solicitado a pensar antes de produzir uma solicitação de ferramenta. Mas ele 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 clima?” sem especificar um local, o Claude, particularmente o 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 o Claude Opus não tiver contexto suficiente para preencher os parâmetros necessários, é muito mais provável que responda com uma pergunta de esclarecimento em vez de fazer uma chamada de ferramenta.

Ferramentas sequenciais

Algumas tarefas podem exigir chamar várias ferramentas em sequência, usando a saída de uma ferramenta como entrada para outra. Em tal caso, o Claude chamará uma ferramenta de cada vez. Se solicitado a chamar todas as ferramentas de uma vez, o Claude provavelmente adivinhará parâmetros para ferramentas posteriores se elas dependerem dos resultados de ferramentas anteriores.

Aqui está um exemplo de uso de uma ferramenta get_location para obter a localização do usuário e, em seguida, 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-20250514",
    "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, o Claude primeiro chamaria a ferramenta get_location para obter a localização do usuário. Depois de retornar a localização em um tool_result, o Claude chamaria então get_weather com essa localização para obter a resposta final.

A conversa completa pode ser assim:

Papel	Conteúdo
Usuário	Como está o clima onde estou?
Assistente	<thinking>Para responder a isso, primeiro preciso determinar a localização do usuário usando a ferramenta get_location. Então posso passar essa localização para a ferramenta get_weather para encontrar o clima atual lá.</thinking>[Uso da ferramenta get_location]
Usuário	[Resultado da ferramenta get_location com id correspondente e resultado de San Francisco, CA]
Assistente	[Uso da ferramenta get_weather com a seguinte entrada]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Usuário	[Resultado da ferramenta get_weather com id correspondente e resultado de “59°F (15°C), nublado”]
Assistente	Com base na sua localização atual em San Francisco, CA, o clima agora é de 59°F (15°C) e principalmente nublado. É um dia bastante fresco e nublado na cidade. Você pode querer levar um casaco leve se estiver saindo.

Este exemplo demonstra como o Claude pode encadear várias chamadas de ferramentas para responder a uma pergunta que requer a coleta de dados de diferentes fontes. As etapas principais são:

O Claude primeiro percebe que precisa da localização do usuário para responder à pergunta sobre o clima, 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, o Claude prossegue para 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, o Claude incorpora os dados meteorológicos em uma resposta em linguagem natural para a pergunta original.

Uso de ferramentas com cadeia de pensamento

Modo JSON

Você pode usar ferramentas para fazer o Claude produzir saída JSON que segue um esquema, mesmo que você não tenha 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 o uso de ferramentas) para instruir o modelo a usar explicitamente essa ferramenta
Lembre-se de que o modelo passará o 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 específico.

#!/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-20250514",
    "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	`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)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`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 dos modelos para os preços atuais por modelo.

Quando você envia um prompt de uso de ferramenta, assim como qualquer outra solicitação de 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 implementação em nossos cookbooks:

Ferramenta de Calculadora

Aprenda como integrar uma ferramenta de calculadora simples com o Claude para cálculos numéricos precisos.

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 o Claude e o uso de ferramentas podem extrair dados estruturados de texto não estruturado.

Primeiros passos

Explorar recursos

Modelos e preços

Saiba mais sobre Claude

Testar e avaliar

Centro Jurídico

Componentes do agente

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 de Calculadora

Agente de Atendimento ao Cliente

Extrator JSON

Primeiros passos

Explorar recursos

Modelos e preços

Saiba mais sobre Claude

Testar e avaliar

Centro Jurídico

Componentes do agente

​Como funciona o uso de ferramentas

​Ferramentas do cliente

​Ferramentas do servidor

​Exemplos de uso de ferramentas

​Preços

​Próximos Passos

Ferramenta de 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