Uso de ferramentas (chamada de funções)

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.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": "Obter o clima atual em um determinado local",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "A cidade e estado, ex. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "A unidade de temperatura, 'celsius' ou 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

Prompt do sistema para uso de ferramentas

Quando você chama a API 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:

Neste ambiente você tem acesso a um conjunto de ferramentas que pode usar para responder à pergunta do usuário.
{{ INSTRUÇÕES DE FORMATAÇÃO }}
Parâmetros de string e escalares devem ser especificados como estão, enquanto listas e objetos devem usar o formato JSON. Note que os espaços para valores de string não são removidos. A saída não precisa ser XML válido e é analisada com expressões regulares.
Aqui estão as funções disponíveis no formato JSONSchema:
{{ DEFINIÇÕES DE FERRAMENTAS EM JSON SCHEMA }}
{{ PROMPT DO SISTEMA DO USUÁRIO }}
{{ CONFIGURAÇÃO DE FERRAMENTAS }}

​

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 ressalvas 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": "Recupera o preço atual da ação para um determinado símbolo ticker. O símbolo ticker deve ser um símbolo válido para uma empresa de capital aberto em uma grande bolsa de valores dos EUA como NYSE ou NASDAQ. A ferramenta retornará o preço da última negociação em USD. Deve ser usada quando o usuário perguntar sobre o preço atual ou mais recente de uma ação específica. Não fornecerá nenhuma outra informação sobre a ação ou empresa.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "O símbolo ticker da ação, ex. AAPL para Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Obtém o preço da ação para um 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 três opções possíveis:

• auto permite que o Claude decida se deve chamar quaisquer ferramentas fornecidas ou não. Este é o valor padrão.
• 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.

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: Como está o clima em Londres? Use a ferramenta get_weather em sua resposta.

​

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 “Como está o clima em San Francisco agora, e que horas são lá?”, o Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Para responder a esta pergunta, eu vou: 1. Usar a ferramenta get_weather para obter o clima atual em San Francisco. 2. Usar a ferramenta get_time para obter a hora atual no fuso horário America/Los_Angeles, que cobre San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Esta cadeia de pensamento dá insight 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 "Antes de responder, explique seu raciocínio passo a passo em tags." à mensagem do usuário ou 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 de uso de ferramentas e resultados de ferramentas

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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Preciso usar o get_weather, e o usuário quer SF, que provavelmente é 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. [opcional] 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 graus") ou lista de blocos de conteúdo aninhados (ex. "content": [{"type": "text", "text": "15 graus"}]). 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 graus"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 graus"},
        {
          "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: o serviço de clima API não está disponível (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Faltando parâmetro obrigatório 'location'",
      "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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Preciso chamar a função get_weather, e o usuário quer SF, que provavelmente é 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-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "O clima atual em San Francisco é 15 graus Celsius (59 graus Fahrenheit). É um dia fresco na cidade da baía!"
    }
  ]
}

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

​

Preços

Requisições de uso de ferramentas são precificadas da mesma forma que qualquer outra requisição à API do Claude, baseado no número total de tokens de entrada enviados ao modelo (incluindo no parâmetro tools) e o 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ão listados abaixo (excluindo os tokens adicionais listados acima):

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 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 tanto de entrada quanto de saída como parte das métricas de usage reportadas.

​

Próximos Passos

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