Claude é capaz de interagir com ferramentas e funções externas do lado do cliente, permitindo que você equipe Claude com suas próprias ferramentas personalizadas para realizar uma variedade maior de tarefas.

Beta público de uso de ferramentas

Estamos animados em anunciar que o uso de ferramentas agora está em beta público! Para acessar esse recurso, você precisará incluir o cabeçalho anthropic-beta: tools-2024-05-16 em suas solicitações de API.

Estaremos iterando neste beta aberto nas próximas semanas, então agradecemos todo o seu feedback. Por favor, compartilhe suas ideias e sugestões usando este formulário.

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: tools-2024-05-16" \
  -d '{
    "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"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Como está o tempo em São Francisco?"
      }
    ]
  }'

Por favor, observe que durante o período beta:

  • Embora o recurso esteja pronto para produção, podemos introduzir várias versões beta antes do lançamento final.
  • O uso de ferramentas ainda não está disponível em plataformas de terceiros como Vertex AI ou AWS Bedrock, mas estará em breve. Consulte Uso de ferramentas legado para obter orientações sobre como usar ferramentas no Vertex AI e AWS Bedrock agora.

Como funciona o uso de ferramentas

Usar ferramentas com Claude envolve as seguintes etapas:

  1. Forneça a Claude ferramentas e um prompt do usuário: (solicitação da API)
    • Defina o conjunto de ferramentas que você deseja que 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. Claude usa uma ferramenta: (resposta da API)
    • 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, também decide quais ferramentas usar e com quais entradas.
    • 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 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 de Claude.
    • Execute o código real da ferramenta no lado do cliente.
    • Retorne os resultados para Claude continuando a conversa com uma nova mensagem user contendo um bloco de conteúdo tool_result.
  4. Claude usa o resultado da ferramenta para formular uma resposta: (resposta da API)
    • Após receber os resultados da ferramenta, 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 por Claude é toda a informação que você precisa, e você pode não precisar retornar os resultados da ferramenta de volta para Claude.

Todas as ferramentas são fornecidas pelo usuário

É importante observar que Claude não tem acesso a nenhuma ferramenta integrada 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 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:

JSON
{
  "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 de 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 a Claude sobre suas ferramentas, melhor ela 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:

JSON
{
  "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:

JSON
{
  "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 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 Claude decide usar uma das ferramentas que você forneceu, ela 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:

JSON
{
  "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 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:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 graus"
    }
  ]
}

Imagens também são suportadas em content:

JSON
{
  "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:

JSON
{
  "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, 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:

JSON
{
  "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.

Neste 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 Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que 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 a Claude para usar a ferramenta get_weather, você pode incentivá-la 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 a Claude para usar qualquer uma das ferramentas fornecidas por meio de {"type": "any"}. O tool_choice padrão é {"type": "auto"}, que permite que Claude decida se deve ou não usar uma ferramenta.

Observe que quando você tem tool_choice como any ou tool, preencheremos previamente 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 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 um exemplo completo de funcionamento.


Tratamento de erros

Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com 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ê pode retornar a mensagem de erro no content junto com "is_error": true:

JSON
{
  "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
    }
  ]
}

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. Por favor, tente novamente mais tarde.”

Limite máximo de tokens excedido

Se a resposta de 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 maior para obter o uso completo da ferramenta.

Uso inválido de ferramenta

Se a tentativa de Claude de usar uma ferramenta for inválida (por exemplo, faltando parâmetros obrigatórios), geralmente significa que não havia informações suficientes para 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 Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:

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

Uso de ferramentas com cadeia de pensamento

Ao usar ferramentas, Claude geralmente mostrará sua “cadeia de pensamento”, ou seja, o raciocínio passo a passo que ela 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 fazer isso.

Por exemplo, dado o prompt “Como está o tempo em São Francisco agora e que horas são lá?”, Claude pode responder com:

JSON
{
  "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 dá uma visão do processo de raciocínio de 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 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 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 de uso de ferramentas

Ao usar ferramentas com Claude, tenha em mente as seguintes limitações e melhores práticas:

  • Use Claude 3 Opus para navegar em usos complexos de ferramentas, Haiku se estiver lidando com ferramentas simples: 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 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. 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 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, Claude pode trabalhar melhor com interfaces mais simples e ferramentas mais simples. Se Claude estiver tendo dificuldades para usar sua ferramenta corretamente, tente achatar o esquema de entrada para longe de objetos json profundamente aninhados e reduza o número de entradas.
  • Uso sequencial de ferramentas: 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 Claude use várias ferramentas em paralelo projetando cuidadosamente seu prompt e ferramentas, isso pode levar 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 de Claude.
  • Tentativas: Se a solicitação de uso de ferramenta de Claude for inválida ou estiver faltando parâmetros obrigatórios, você poderá retornar uma resposta de erro e Claude geralmente tentará novamente a solicitação com as informações ausentes preenchidas. No entanto, após 2-3 tentativas malsucedidas, 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 de Claude (se houver) para entender por que ela está fazendo as escolhas que está fazendo. Você também pode tentar solicitar que Claude use uma ferramenta específica para ver se isso leva ao comportamento esperado. Se 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.

Ao ter essas limitações e diretrizes em mente, você pode projetar orquestrações eficazes de ferramentas e agentes que estendem significativamente as capacidades de Claude para lidar com uma ampla variedade de tarefas.


Histórico de versões beta

  • tools-2024-05-16
    • Alteração do prompt do sistema para Opus 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 de Claude, conectando-o a fontes de dados e funcionalidades externas. Com um conjunto bem projetado de ferramentas, você pode permitir que 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 implementar, como:
  • Melhore a qualidade e a confiabilidade do uso de ferramentas: Itere e melhore suas descrições de ferramentas e prompts para obter um uso de ferramentas mais confiável e preciso de Claude
  • Expanda as capacidades de Claude:
    • Experimente diferentes ferramentas e esquemas para ver como 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 onde Claude possa concluir uma variedade de tarefas de ponta a ponta como se fosse um assistente.
    • Explore arquiteturas complexas de uso de ferramentas, como dar a Claude ferramentas para fazer pesquisa RAG ou chamar subagentes de modelo menores, como Haiku, para realizar tarefas em seu nome

Enquanto você constrói com o uso de ferramentas, adoraríamos ouvir seu feedback 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 animados para ver como você usa o uso de ferramentas para expandir os limites do que é possível com Claude. Feliz construção!