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.

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:

1. 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?“.
2. 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 de tool_use, indicando que o Claude deseja usar uma ferramenta externa.
3. 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údo tool_result.
4. 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.

​

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 o input_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:

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.

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

​

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:
  • Usando uma ferramenta de calculadora com o Claude
  • Criando um agente de atendimento ao cliente com ferramentas do lado do cliente
  • Extraindo JSON estruturado usando o Claude e o uso de ferramentas
• 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!