Uso de ferramentas com Claude

O Claude é capaz de interagir com ferramentas e funções externas do lado do cliente, permitindo que você equipe o Claude com suas próprias ferramentas personalizadas para realizar uma variedade maior de tarefas.

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

​

Como funciona o uso de ferramentas

Integre ferramentas externas com o Claude nestas etapas:

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

​

Como implementar o uso de ferramentas

​

Escolhendo um modelo

Geralmente, use Claude 3.7 Sonnet, Claude 3.5 Sonnet ou Claude 3 Opus para ferramentas complexas e consultas ambíguas; eles lidam melhor com múltiplas ferramentas e buscam esclarecimentos quando necessário.

Use Claude 3.5 Haiku ou Claude 3 Haiku para ferramentas diretas, mas note que eles podem inferir parâmetros ausentes.

​

Especificando ferramentas

As ferramentas são especificadas no parâmetro de nível superior tools da requisição à API. Cada definição de ferramenta inclui:

{
  "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"]
  }
}

​

Prompt do sistema para uso de ferramentas

Quando você chama a API da Anthropic com o parâmetro tools, construímos um prompt especial do sistema a partir das definições de ferramentas, configuração de ferramentas e qualquer prompt do sistema especificado pelo usuário. O prompt construído é projetado para instruir o modelo a usar a(s) ferramenta(s) especificada(s) e fornecer o contexto necessário para a ferramenta operar adequadamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

Melhores práticas para definições de ferramentas

Para obter o melhor desempenho do Claude ao usar ferramentas, siga estas diretrizes:

• Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho da ferramenta. Suas descrições devem explicar cada detalhe sobre a ferramenta, incluindo:
  • O que a ferramenta faz
  • Quando deve ser usada (e quando não deve)
  • O que cada parâmetro significa e como afeta o comportamento da ferramenta
  • Quaisquer advertências ou limitações importantes, como quais informações a ferramenta não retorna se o nome da ferramenta não estiver claro. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Procure ter pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
• Priorize descrições sobre exemplos. Embora você possa incluir exemplos de como usar uma ferramenta em sua descrição ou no prompt que a acompanha, isso é menos importante do que ter uma explicação clara e abrangente do propósito e parâmetros da ferramenta. Só adicione exemplos depois de ter desenvolvido completamente a descrição.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

A boa descrição explica claramente o que a ferramenta faz, quando usá-la, quais dados ela retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa o Claude com muitas questões em aberto sobre o comportamento e uso da ferramenta.

​

Controlando a saída do Claude

​

Forçando o uso de ferramentas

Em alguns casos, você pode querer que o Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que o Claude ache que pode fornecer uma resposta sem usar uma ferramenta. Você pode fazer isso especificando a ferramenta no campo tool_choice assim:

tool_choice = {"type": "tool", "name": "get_weather"}

Ao trabalhar com o parâmetro tool_choice, temos quatro opções possíveis:

• auto permite que o Claude decida se deve chamar quaisquer ferramentas fornecidas ou não. Este é o valor padrão quando tools são fornecidas.
• any diz ao Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta específica.
• tool permite que forcemos o Claude a sempre usar uma ferramenta específica.
• none impede que o Claude use quaisquer ferramentas. Este é o valor padrão quando nenhuma tools é fornecida.

Este diagrama ilustra como cada opção funciona:

Note que quando você tem tool_choice como any ou tool, nós pré-preencheremos a mensagem do assistente para forçar o uso de uma ferramenta. Isso significa que os modelos não emitirão um bloco de conteúdo text de cadeia de pensamento antes dos blocos de conteúdo tool_use, mesmo se explicitamente solicitados a fazê-lo.

Nossos testes mostraram que isso não deve reduzir o desempenho. Se você quiser manter a cadeia de pensamento (particularmente com o Opus) enquanto ainda solicita que o modelo use uma ferramenta específica, você pode usar {"type": "auto"} para tool_choice (o padrão) e adicionar instruções explícitas em uma mensagem user. Por exemplo: What's the weather like in London? Use the get_weather tool in your response.

​

Saída JSON

As ferramentas não precisam necessariamente ser funções do lado do cliente — você pode usar ferramentas sempre que quiser que o modelo retorne saída JSON que siga um esquema fornecido. Por exemplo, você pode usar uma ferramenta record_summary com um esquema específico. Veja exemplos de uso de ferramentas para um exemplo completo funcional.

​

Cadeia de pensamento

Ao usar ferramentas, o Claude frequentemente mostrará sua “cadeia de pensamento”, ou seja, o raciocínio passo a passo que ele usa para decompor o problema e decidir quais ferramentas usar. O modelo Claude 3 Opus fará isso se tool_choice estiver definido como auto (este é o valor padrão, veja Forçando o uso de ferramentas), e Sonnet e Haiku podem ser induzidos a fazê-lo.

Por exemplo, dado o prompt “What’s the weather like in San Francisco right now, and what time is it there?”, o Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Esta cadeia de pensamento fornece insights sobre o processo de raciocínio do Claude e pode ajudar você a depurar comportamentos inesperados.

Com o modelo Claude 3 Sonnet, a cadeia de pensamento é menos comum por padrão, mas você pode induzir o Claude a mostrar seu raciocínio adicionando algo como "Before answering, explain your reasoning step-by-step in tags." à mensagem do usuário ou ao prompt do sistema.

É importante notar que, embora as tags <thinking> sejam uma convenção comum que o Claude usa para denotar sua cadeia de pensamento, o formato exato (como o nome dessa tag XML) pode mudar ao longo do tempo. Seu código deve tratar a cadeia de pensamento como qualquer outro texto gerado pelo assistente e não depender da presença ou formatação específica das tags <thinking>.

​

Desabilitando o uso paralelo de ferramentas

Por padrão, o Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar este comportamento definindo disable_parallel_tool_use=true no campo tool_choice.

• Quando o tipo de tool_choice é auto, isso garante que o Claude use no máximo uma ferramenta
• Quando o tipo de tool_choice é any ou tool, isso garante que o Claude use exatamente uma ferramenta

​

Manipulando blocos de conteúdo tool_use e tool_result

Quando o Claude decide usar uma das ferramentas que você forneceu, ele retornará uma resposta com um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use na resposta da API que incluem:

• id: Um identificador único para este bloco específico de uso de ferramenta. Isso será usado para corresponder aos resultados da ferramenta posteriormente.
• name: O nome da ferramenta sendo usada.
• input: Um objeto contendo a entrada sendo passada para a ferramenta, em conformidade com o input_schema da ferramenta.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to use the 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"}
    }
  ]
}

Quando você receber uma resposta de uso de ferramenta, você deve:

1. Extrair o name, id e input do bloco tool_use.
2. Executar a ferramenta real em seu código correspondente àquele nome de ferramenta, passando o input da ferramenta.
3. Continuar a conversa enviando uma nova mensagem com o role de user, e um bloco de content contendo o tipo tool_result e as seguintes informações:
   • tool_use_id: O id da requisição de uso de ferramenta para a qual este é um resultado.
   • content: O resultado da ferramenta, como uma string (ex.: "content": "15 degrees") ou lista de blocos de conteúdo aninhados (ex.: "content": [{"type": "text", "text": "15 degrees"}]). Estes blocos de conteúdo podem usar os tipos text ou image.
   • is_error (opcional): Definido como true se a execução da ferramenta resultou em um erro.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Após receber o resultado da ferramenta, o Claude usará essa informação para continuar gerando uma resposta ao prompt original do usuário.

​

Solucionando problemas de erros

Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com o Claude:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

​

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 ferramentas simples, e as descrições das ferramentas são mais curtas do que seria ideal para garantir o melhor desempenho.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "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"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "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!"
    }
  ]
}

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

​

Preços

As requisições de uso de ferramentas são precificadas da mesma forma que qualquer outra requisição à API do Claude, com base no número total de tokens de entrada enviados ao modelo (incluindo no parâmetro tools) e no número de tokens de saída gerados.”

Os tokens adicionais do uso de ferramentas vêm de:

• O parâmetro tools nas requisições à API (nomes de ferramentas, descrições e esquemas)
• Blocos de conteúdo tool_use nas requisições e respostas da API
• Blocos de conteúdo tool_result nas requisições à API

Quando você usa tools, nós também incluímos automaticamente um prompt especial do sistema para o modelo que habilita o uso de ferramentas. O número de tokens de uso de ferramenta necessários para cada modelo está listado abaixo (excluindo os tokens adicionais listados acima). Note que a tabela assume que pelo menos 1 ferramenta é fornecida. Se nenhuma tools for fornecida, então uma escolha de ferramenta de none usa 0 tokens adicionais de prompt do sistema.

Essas contagens de tokens são adicionadas aos seus tokens normais de entrada e saída para calcular o custo total de uma requisição. 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 requisição à 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: