Aqui estão alguns exemplos de código demonstrando 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. Veja especificando ferramentas para mais informações.

​
Ferramenta única

Este exemplo mostra uma situação básica de ferramenta única, usando uma 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-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtenha 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"]
        }
    }],
    "messages": [{"role": "user", "content": "Como está o tempo em São Francisco?"}]
}'

Claude retornará uma resposta semelhante a:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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"}
    }
  ]
}

Você então precisaria executar a função get_weather com a entrada fornecida e retornar o resultado em uma nova mensagem de 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-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtenha 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"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Como está o tempo em São Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>Preciso usar 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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 graus"
                }
            ]
        }
    ]
}'

Isso imprimirá a resposta final de Claude, incorporando os dados do clima:

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

​
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 3 Opus tem muito mais probabilidade de reconhecer que um parâmetro está faltando e pedir por ele. O Claude 3 Sonnet pode perguntar, especialmente quando solicitado a pensar antes de gerar uma solicitação de ferramenta. Mas também pode fazer o possível 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, o Claude, particularmente o Claude 3 Sonnet, pode tentar adivinhar as entradas das ferramentas:

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

Esse comportamento não é garantido, especialmente para prompts mais ambíguos e para modelos menos inteligentes que o Claude 3 Opus. Se o Claude 3 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.

​
Múltiplas ferramentas

Você pode fornecer ao Claude várias 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-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtenha 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"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtenha a hora atual em um determinado fuso horário",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "O nome do fuso horário IANA, por exemplo, America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "Como está o tempo agora em Nova York? E que horas são lá?"
    }]
}'

Nesse 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 gerar 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 de user.

​
Ferramentas sequenciais

Algumas tarefas podem exigir a chamada de várias ferramentas em sequência, usando a saída de uma ferramenta como entrada para outra. Nesse caso, o Claude chamará uma ferramenta por vez. Se solicitado a chamar todas as ferramentas de uma vez, o Claude provavelmente adivinhará os parâmetros para ferramentas mais adiante se eles 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-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Obtenha a localização atual do usuário com base no endereço IP. Esta ferramenta não tem parâmetros ou argumentos.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "name": "get_weather",
            "description": "Obtenha 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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "Como está o tempo onde eu estou?"
    }]
}'

Nesse caso, o 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, o Claude então chamaria get_weather com essa localização para obter a resposta final.

A conversa completa pode ser assim:

FunçãoConteúdo
UsuárioComo está o tempo onde eu estou?
Assistente<thinking>Para responder 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 descobrir o clima atual lá.</thinking>[Uso da ferramenta para get_location]
Usuário[Resultado da ferramenta para get_location com id correspondente e resultado de São Francisco, CA]
Assistente[Uso da ferramenta para get_weather com a seguinte entrada]{ “location”: “São 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 São Francisco, CA, o clima agora é de 59°F (15°C) e principalmente nublado. É um dia bastante frio e nublado na cidade. Você pode querer levar uma jaqueta leve se for sair.

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:

  1. 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.
  2. O usuário (ou seja, o código do cliente) executa a função get_location real e retorna o resultado “São Francisco, CA” em um bloco tool_result.
  3. Com a localização agora conhecida, o Claude prossegue para chamar a ferramenta get_weather, passando “São 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 do clima em outro bloco tool_result.
  5. Finalmente, o Claude incorpora os dados do clima em uma resposta em linguagem natural à pergunta original.

​
Uso de ferramentas com cadeia de pensamento

Por padrão, o Claude 3 Opus é solicitado a pensar antes de responder a uma consulta de uso de ferramenta para melhor determinar se uma ferramenta é necessária, qual ferramenta usar e os parâmetros apropriados. O Claude 3 Sonnet e o Claude 3 Haiku são solicitados a tentar usar ferramentas o máximo possível e têm mais probabilidade de chamar uma ferramenta desnecessária ou inferir parâmetros ausentes. Para solicitar que o Sonnet ou o Haiku avaliem melhor a consulta do usuário antes de fazer chamadas de ferramentas, o seguinte prompt pode ser usado:

Prompt de cadeia de pensamento

Responda à solicitação do usuário usando ferramentas relevantes (se estiverem disponíveis). Antes de chamar uma ferramenta, faça uma análise dentro das tags \<thinking>\</thinking>. Primeiro, pense sobre qual das ferramentas fornecidas é a ferramenta relevante para responder à solicitação do usuário. Segundo, percorra cada um dos parâmetros necessá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 necessários estiverem presentes ou puderem ser razoavelmente inferidos, feche a tag de pensamento e prossiga com a chamada da ferramenta. MAS, se um dos valores para um parâmetro necessário estiver faltando, 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 forem fornecidos.

​
Modo JSON

Você pode usar ferramentas para fazer com que o Claude produza uma saída JSON que segue um esquema, mesmo que não tenha intenção de executar essa saída por meio de uma ferramenta ou função.

Ao usar ferramentas dessa maneira:

  • Você geralmente deseja fornecer uma única ferramenta
  • Você deve definir tool_choice (consulte Forçando o uso de ferramentas) 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 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-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Registre um resumo de uma imagem usando JSON bem estruturado.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "valor vermelho [0.0, 1.0]" },
"g": { "type": "number", "description": "valor verde [0.0, 1.0]" },
"b": { "type": "number", "description": "valor azul [0.0, 1.0]" },
"name": { "type": "string", "description": "Nome da cor legível por humanos em snake_case, por exemplo, \"verde_oliva\" ou \"turquesa\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Cores principais na imagem. Limite a menos de quatro."
                },
                "description": {
                    "type": "string",
                    "description": "Descrição da imagem. Uma ou duas frases no máximo."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Ano estimado em que a imagem foi tirada, se for uma foto. Defina isso apenas se a imagem parecer não ser fictícia. Estimativas aproximadas são aceitáveis!"
                }
            },
            "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": "Descreva esta imagem."}
        ]}
    ]
}'
Visão geralPreços e tokens de uso de ferramentas