Uso de ferramentas (chamada de função)

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 executar uma variedade maior de tarefas.

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

​

Como funciona o uso de ferramentas

Integre ferramentas externas com o Claude seguindo estas etapas:

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 os resultados de volta para o Claude.

​

Como implementar o uso de ferramentas

​

Escolhendo um modelo

Geralmente, use o Claude 3 Opus para ferramentas complexas e consultas ambíguas; ele lida melhor com várias ferramentas e busca esclarecimentos quando necessário.

Use o Haiku para ferramentas simples, mas observe que ele pode inferir parâmetros ausentes.

​

Especificando ferramentas

As ferramentas são especificadas no parâmetro de nível superior tools da solicitaçã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 o estado, por exemplo, São Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "A unidade de temperatura, 'celsius' ou 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

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 todos os detalhes sobre a ferramenta, incluindo:
  • O que a ferramenta faz
  • Quando ela deve ser usada (e quando não deve)
  • O que cada parâmetro significa e como ele 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 for claro. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Tente escrever pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
• Priorize descrições em vez de 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 dos parâmetros da ferramenta. Adicione exemplos somente 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 de ticker. O símbolo do 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. Ela deve ser usada quando o usuário perguntar sobre o preço atual ou mais recente de uma ação específica. Ela 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 do ticker da ação, por exemplo, 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 significa o parâmetro ticker. A descrição ruim é muito breve e deixa o Claude com muitas perguntas abertas sobre o comportamento e o 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 pense 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 ou não as ferramentas fornecidas. 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 nos permite forçar o Claude a sempre usar uma ferramenta específica.

Este diagrama ilustra como cada opção funciona:

Observe que quando você tem tool_choice como any ou tool, 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 solicitado.

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 tempo 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 uma saída JSON que segue 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 de funcionamento.

​

Cadeia de pensamento

Ao usar ferramentas, o Claude geralmente 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, consulte Forçando o uso de ferramentas), e o Sonnet e o Haiku podem ser solicitados a fazer isso.

Por exemplo, dado o prompt “Como está o tempo em São 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 São Francisco. 2. Usar a ferramenta get_time para obter a hora atual no fuso horário America/Los_Angeles, que abrange São Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "São Francisco, CA"}
    }
  ]
}

Essa 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 solicitar que o Claude mostre seu raciocínio adicionando algo como "Antes de responder, explique seu raciocínio passo a passo em tags." à mensagem do usuário ou ao prompt do sistema.

É importante observar 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>.

​

Lidando com blocos de conteúdo de uso de ferramenta e resultado de ferramenta

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 combinar os 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-20240620",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Preciso usar o get_weather, e o usuário quer SF, que provavelmente é São Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "São 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 a esse nome de ferramenta, passando a 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 solicitação de uso de ferramenta para a qual este é um resultado.
   • content: O resultado da ferramenta, como uma string (por exemplo, "content": "15 graus") ou uma lista de blocos de conteúdo aninhados (por exemplo, "content": [{"type": "text", "text": "15 graus"}]). Esses blocos de conteúdo podem usar os tipos text ou image.
   • is_error (opcional): Defina 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á essas informações 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: a API do serviço meteorológico não está disponível (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Parâmetro obrigatório 'location' ausente",
      "is_error": true
    }
  ]
}

​

Exemplos de uso de ferramentas

Aqui estão alguns exemplos de código que demonstram vários padrões e técnicas de uso de ferramentas. Por uma 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-20240620",
  "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 é São Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9", 
      "name": "get_weather",
      "input": {"location": "São Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "O clima atual em São Francisco é de 15 graus Celsius (59 graus Fahrenheit). É um dia frio na cidade à beira da baía!"
    }
  ]
}

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

​

Preços

As solicitações de uso de ferramentas são precificadas da mesma forma que qualquer outra solicitaçã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 solicitações à API (nomes de ferramentas, descrições e esquemas)
• Blocos de conteúdo tool_use nas solicitações e respostas da API
• Blocos de conteúdo tool_result nas solicitações à API

Quando você usa tools, também incluímos automaticamente um prompt de sistema especial para o modelo que habilita o uso de ferramentas. O número de tokens de uso de ferramentas necessários para cada modelo está listado 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 solicitaçã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 solicitação à API, a resposta irá gerar 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 livros de receitas: