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 realizar uma variedade maior de tarefas.
O uso de ferramentas agora está geralmente disponível em toda a família de modelos Claude 3 para desenvolvedores que usam a API Anthropic Messages, Amazon Bedrock e Google Vertex AI! Continue compartilhando suas ideias e sugestões usando este formulário.
Aqui está um exemplo de como fornecer ferramentas ao Claude usando a API Messages:
Como funciona o uso de ferramentas
O uso de ferramentas com o Claude envolve as seguintes etapas:
- Forneça ao Claude ferramentas e um prompt do usuário: (solicitação da API)
- Defina o conjunto de ferramentas às quais você deseja que o Claude tenha acesso, incluindo seus nomes, descrições e esquemas de entrada.
- Forneça um prompt do usuário que possa exigir o uso de uma ou mais dessas ferramentas para responder, como “Como está o tempo em São Francisco?“.
- O Claude usa uma ferramenta: (resposta da API)
- O Claude avalia o prompt do usuário e decide se alguma das ferramentas disponíveis ajudaria na consulta ou tarefa do usuário. Se sim, ele também decide quais ferramentas usar e com quais entradas.
- O Claude constrói uma solicitação de uso de ferramenta formatada corretamente.
- A resposta da API terá um
stop_reason
detool_use
, indicando que o Claude deseja usar uma ferramenta externa.
- Extraia a entrada da ferramenta, execute o código e retorne os resultados: (solicitação da API)
- No lado do cliente, você deve extrair o nome da ferramenta e a entrada da solicitação de uso da ferramenta do Claude.
- Execute o código real da ferramenta no lado do cliente.
- Retorne os resultados ao Claude, continuando a conversa com uma nova mensagem
user
contendo um bloco de conteúdotool_result
.
- O Claude usa o resultado da ferramenta para formular uma resposta: (resposta da API)
- Após receber os resultados da ferramenta, o Claude usará essas informações para formular sua resposta final ao prompt original do usuário.
As etapas (3) e (4) são opcionais - para alguns fluxos de trabalho, o uso da ferramenta pelo Claude é toda a informação de que você precisa, e você pode não precisar retornar os resultados da ferramenta de volta ao Claude.
Todas as ferramentas são fornecidas pelo usuário
É importante observar que o Claude não tem acesso a nenhuma ferramenta interna do lado do servidor. Todas as ferramentas devem ser explicitamente fornecidas por você, o usuário, em cada solicitação da API. Isso lhe dá controle total e flexibilidade sobre as ferramentas que o Claude pode usar.
Especificando ferramentas
As ferramentas são especificadas no parâmetro de nível superior tools
da solicitação da API. Cada definição de ferramenta inclui:
name
: O nome da ferramenta. Deve corresponder à expressão regular^[a-zA-Z0-9_-]{1,64}$
.description
: Uma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.input_schema
: Um objeto JSON Schema que define os parâmetros esperados para a ferramenta.
Aqui está um exemplo de definição de ferramenta simples:
{
"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"]
}
}
Esta ferramenta, chamada get_weather
, espera um objeto de entrada com uma string location
obrigatória e uma string unit
opcional que deve ser “celsius” ou “fahrenheit”.
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 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 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.
Aqui está um exemplo de uma boa descrição de ferramenta:
{
"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. 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 do ticker da ação, por exemplo, AAPL para Apple Inc."
}
},
"required": ["ticker"]
}
}
Em contraste, aqui está um exemplo de uma descrição de ferramenta ruim:
{
"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 em aberto sobre o comportamento e o uso da ferramenta.
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 oinput_schema
da ferramenta.
Aqui está um exemplo de resposta da API com um bloco de conteúdo tool_use
:
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-3-opus-20240229",
"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:
- Extrair o
name
,id
einput
do blocotool_use
. - Executar a ferramenta real em seu código correspondente a esse nome de ferramenta, passando a
input
da ferramenta. - [opcional] Continuar a conversa enviando uma nova mensagem com o
role
deuser
e um bloco decontent
contendo o tipotool_result
e as seguintes informações:tool_use_id
: Oid
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 tipostext
ouimage
.is_error
(opcional): Defina comotrue
se a execução da ferramenta resultou em um erro.
Aqui está um exemplo de retorno de um resultado de ferramenta bem-sucedido:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 graus"
}
]
}
Imagens também são suportadas em content
:
{
"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...",
}
}
]
}
]
}
E aqui está um exemplo de retorno de um resultado de erro:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: a API do serviço de clima não está disponível (HTTP 500)",
"is_error": true
}
]
}
Após receber o resultado da ferramenta, o Claude usará essas informações para continuar gerando uma resposta ao prompt original do usuário.
Você também pode retornar um resultado de ferramenta não errado com content
vazio, indicando que a ferramenta foi executada com sucesso sem nenhuma saída:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
}
]
}
Diferenças de outras APIs
Você pode estar familiarizado com outras APIs que retornam o uso de ferramentas separadamente da saída principal do modelo, ou que usam uma role
de mensagem especial tool
ou function
.
Em contraste, os modelos e a API da Anthropic são construídos em torno de mensagens alternadas user
e assistant
, onde cada mensagem é uma matriz de blocos de conteúdo ricos: text
, image
, tool_use
e tool_result
.
Nesse formato, as mensagens user
representam conteúdo gerenciado pelo cliente e pelo usuário/humano, e as mensagens assistant
representam conteúdo gerenciado pelo servidor e pela IA. Como tal, não há uma role
de mensagem especial tool
ou function
, e você deve incluir blocos tool_result
no content
de suas mensagens user
.
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 dizer explicitamente ao Claude para usar a ferramenta get_weather
, você pode incentivá-lo a usar a ferramenta que deseja. Essa técnica pode ser útil para testar e depurar suas integrações de ferramentas, ou quando você sabe que a ferramenta deve sempre ser usada, independentemente da entrada.
Você também pode dizer ao Claude para usar qualquer uma das ferramentas fornecidas por meio de {"type": "any"}
. O tool_choice
padrão é {"type": "auto"}
, que permite que o Claude decida se deve ou não usar uma ferramenta.
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 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 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. Consulte exemplos de uso de ferramentas para obter um exemplo completo de funcionamento.
Tratamento de erros
Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com o Claude:
Erro de execução da ferramenta
Se a própria ferramenta lançar um erro durante a execução (por exemplo, um erro de rede ao buscar dados meteorológicos), você poderá retornar a mensagem de erro no content
junto com "is_error": true
:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: a API do serviço de clima não está disponível (HTTP 500)",
"is_error": true
}
]
}
O Claude então incorporará esse erro em sua resposta ao usuário, por exemplo, “Desculpe, não foi possível recuperar o clima atual porque a API do serviço de clima não está disponível. Tente novamente mais tarde.”
Máximo de tokens excedido
Se a resposta do Claude for cortada devido ao limite max_tokens
, e a resposta truncada contiver um bloco de uso de ferramenta incompleto, você precisará tentar novamente a solicitação com um valor max_tokens
mais alto para obter o uso completo da ferramenta.
Uso inválido de ferramenta
Se a tentativa de uso de uma ferramenta pelo Claude for inválida (por exemplo, faltando parâmetros obrigatórios), geralmente significa que não havia informações suficientes para o Claude usar a ferramenta corretamente. Sua melhor aposta durante o desenvolvimento é tentar a solicitação novamente com valores description
mais detalhados nas definições de suas ferramentas.
No entanto, você também pode continuar a conversa com um tool_result
que indica o erro, e o Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Erro: Parâmetro 'location' obrigatório ausente",
"is_error": true
}
]
}
Uso de ferramentas com 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 Sonnet e Haiku podem ser solicitados a fazê-lo.
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 ajudá-lo 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. Para um exemplo mais aprofundado, consulte exemplo de uso de ferramenta com cadeia de pensamento.
É 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>
.
Melhores práticas e limitações do uso de ferramentas
Ao usar ferramentas com o Claude, tenha em mente as seguintes limitações e melhores práticas:
- Use o Claude 3 Opus para navegar em usos complexos de ferramentas, Haiku se estiver lidando com ferramentas simples: O Opus é capaz de lidar com o maior número de ferramentas simultâneas e é melhor em detectar argumentos ausentes em comparação com outros modelos. É mais provável que ele peça esclarecimentos em casos ambíguos em que um argumento não é explicitamente fornecido ou quando uma ferramenta pode não ser necessária para concluir a solicitação do usuário. O Haiku tenta usar ferramentas com mais frequência por padrão (mesmo que não sejam relevantes para a consulta) e inferirá parâmetros ausentes se eles não forem explicitamente fornecidos.
- Número de ferramentas: Todos os modelos Claude 3 podem manter >90% de precisão mesmo ao trabalhar com centenas de ferramentas simples e um número menor de ferramentas complexas. Uma ferramenta “complexa” seria aquela com um grande número de parâmetros ou parâmetros com esquemas complexos (por exemplo, objetos aninhados).
- Ferramentas complexas e profundamente aninhadas: Assim como um humano, o Claude pode trabalhar melhor com interfaces mais simples e ferramentas mais simples. Se o Claude estiver tendo dificuldades para usar sua ferramenta corretamente, tente achatar o esquema de entrada, afastando-se de objetos json profundamente aninhados, e reduza o número de entradas.
- Uso sequencial de ferramentas: O Claude geralmente prefere usar uma ferramenta de cada vez e, em seguida, usar a saída dessa ferramenta para informar sua próxima ação. Embora você possa solicitar que o Claude use várias ferramentas em paralelo, projetando cuidadosamente seu prompt e ferramentas, isso pode levar o Claude a preencher valores fictícios para parâmetros que dependem dos resultados do uso anterior da ferramenta. Para obter melhores resultados, projete seu fluxo de trabalho e ferramentas para obter e trabalhar com uma série de usos sequenciais de ferramentas do Claude.
- Tentativas: Se a solicitação de uso de ferramenta do Claude for inválida ou estiver faltando parâmetros obrigatórios, você poderá retornar uma resposta de erro e o Claude geralmente tentará novamente a solicitação com as informações ausentes preenchidas. No entanto, após 2-3 tentativas malsucedidas, o Claude pode desistir e retornar um pedido de desculpas ao usuário em vez de tentar novamente.
- Depuração: Ao depurar comportamentos inesperados de uso de ferramentas, preste atenção na saída da cadeia de pensamento do Claude (se houver) para entender por que ele está tomando as decisões que está tomando. Você também pode tentar solicitar que o Claude use uma ferramenta específica para ver se isso leva ao comportamento esperado. Se o Claude estiver usando uma ferramenta incorretamente, verifique novamente se as descrições e esquemas de suas ferramentas são claros e não ambíguos.
- Tags <search_quality_reflection>: Às vezes, ao usar ferramentas de pesquisa, o modelo pode retornar tags XML <search_quality_reflection> e uma pontuação de qualidade de pesquisa em sua resposta. Para impedir que o modelo faça isso, adicione a frase “Não reflita sobre a qualidade dos resultados de pesquisa retornados em sua resposta.” ao final do seu prompt.
Tendo em mente essas limitações e diretrizes, você pode projetar ferramentas eficazes e orquestrações de agentes que ampliam significativamente as capacidades do Claude para lidar com uma ampla variedade de tarefas.
Histórico da versão beta (legado)
O uso de ferramentas não está mais em beta e está geralmente disponível a partir de 30 de maio de 2024.
tools-2024-05-16
- Alteração do prompt do sistema para Opus para lidar melhor com cenários em que vários usos de ferramentas podem ser necessários em uma única vez
tools-2024-04-04
: Lançamento beta inicial para uso de ferramentas
Próximos passos
O uso de ferramentas é uma técnica poderosa para estender as capacidades do Claude, conectando-o a fontes de dados e funcionalidades externas. Com um conjunto bem projetado de ferramentas, você pode permitir que o Claude aborde uma enorme variedade de tarefas que seriam impossíveis apenas com seu conhecimento básico.
Alguns possíveis próximos passos a explorar:
- Navegue em nossos livros de receitas de uso de ferramentas: explore nosso repositório de exemplos de código de uso de ferramentas prontos para implementação, como:
- Melhore a qualidade e a confiabilidade do uso de ferramentas: Itere e melhore as descrições e prompts de suas ferramentas para obter um uso de ferramentas mais confiável e preciso do Claude
- Expanda as capacidades do Claude:
- Experimente diferentes ferramentas e esquemas para ver como o Claude lida com diferentes tipos de formatos de entrada e saída.
- Encadeie várias ferramentas para decompor tarefas complexas em uma série de etapas mais simples.
- Construa orquestrações de agentes em que o Claude possa concluir uma variedade de tarefas de ponta a ponta como se fosse um assistente.
- Explore arquiteturas complexas de uso de ferramentas, como fornecer ao Claude ferramentas para fazer pesquisas RAG ou chamar subagentes de modelo menores, como o Haiku, para realizar tarefas em seu nome
À medida que você constrói com o uso de ferramentas, adoraríamos ouvir seus comentários e ver o que você cria! Junte-se ao nosso Discord de desenvolvedores para compartilhar seus projetos e discutir dicas e técnicas com outros desenvolvedores.
Estamos ansiosos para ver como você usa o uso de ferramentas para expandir os limites do que é possível com o Claude. Feliz construção!