Este formato de uso de ferramentas está desatualizado

Nós recomendamos fortemente que você mude o quanto antes para nossa estrutura aprimorada de uso de ferramentas, que é mais confiável e permite um desempenho de maior qualidade, especialmente para tarefas mais complexas de uso de ferramentas.

Este formato de uso de ferramentas não é otimizado para o Claude 3 e pode resultar em desempenho inferior comparado ao nosso formato atualizado de uso de ferramentas.

Nota: O novo formato de uso de ferramentas ainda não está disponível no Vertex AI ou Amazon Bedrock, mas chegará em breve a essas plataformas.


Como funciona o uso de ferramentas legadas

Com o uso de ferramentas legadas, as funções são definidas dentro do próprio prompt. Quando você fornece ao Claude descrições de ferramentas e funções que ele pode usar, o Claude é capaz de decidir de forma inteligente quando e como usar essas ferramentas para ajudar a responder perguntas e completar tarefas.

Por exemplo, digamos que você forneça ao Claude (no prompt) uma função chamada get_weather(location) que recupera o clima atual para um local específico. Se um usuário então perguntar “Como está o tempo em Londres agora?”, o Claude reconhecerá que pode usar a função get_weather que você forneceu para encontrar a resposta.

Nos bastidores, este é um processo de várias etapas:

  1. As definições de função e a pergunta do usuário são passadas ao Claude em um único prompt
    • O Claude não apenas precisa das ferramentas e suas descrições para decidir com sucesso se deve usar as ferramentas, mas provavelmente também de exemplos de situações em que tais ferramentas devem ser usadas, dependendo da complexidade do caso de uso e das ferramentas.
  2. O Claude avalia a pergunta do usuário e decide quais funções chamar e com quais argumentos
  3. O Claude constrói uma chamada de função formatada corretamente
  4. A chamada de função é interceptada via código do cliente com uma stop_sequence clara, e a função real é executada no lado do cliente
  5. O resultado da função é passado de volta para o Claude
  6. O Claude usa o resultado da função para formular sua resposta final ao usuário

Esta técnica permite que o Claude aproveite conhecimentos e capacidades externas, mantendo ainda uma interface conversacional.


Definindo funções

As funções são definidas fornecendo ao Claude uma descrição da função envolvida em tags XML. A descrição deve incluir:

  • O nome da função
  • Uma explicação em texto simples do que a função faz
  • Os parâmetros esperados, seus tipos e descrições
  • Os valores de retorno e tipos
  • Quaisquer exceções que possam ser levantadas

Aqui está um exemplo de definição de função:

XML
<tool_description>
<tool_name>get_weather</tool_name>
<description>
Recupera o clima atual para um local especificado.
Retorna um dicionário com dois campos:
- temperature: float, a temperatura atual em Fahrenheit
- conditions: string, uma breve descrição das condições climáticas atuais
Levanta ValueError se o local fornecido não puder ser encontrado.
</description>
<parameters>
<parameter>
<name>location</name>
<type>string</type>
<description>A cidade e estado, por exemplo, São Francisco, CA</description>
</parameter>
</parameters>
</tool_description>

Algumas dicas para escrever boas descrições de funções:

  • Seja claro e conciso, mas forneça detalhes suficientes para que o Claude entenda quando a função deve ser usada
  • Especifique os tipos dos parâmetros e valores de retorno
  • Mencione quaisquer exceções relevantes que possam ser levantadas
  • Use descrições em texto simples, não sintaxe de código

Formato legado de uso de ferramentas

Para que o Claude chame uma função, ele precisa gerar um bloco XML formatado de maneira muito específica. O formato se parece com isto:

XML
<function_calls>
<invoke>
<tool_name>function_name</tool_name>
<parameters>
<param1>value1</param1>
<param2>value2</param2>
</parameters>
</invoke>
</function_calls>

O bloco <function_calls> pode conter vários blocos <invoke> se o Claude estiver chamando mais de uma função ao mesmo tempo. Cada <invoke> contém o nome da função sendo chamada e os parâmetros sendo passados.

Você deve passar </function_calls> em sua chamada de API como uma stop_sequence para garantir que o Claude pare de gerar texto assim que chamar uma função.

Após um bloco <function_calls>, e supondo que você tenha a sequência de parada adequada, o Claude irá parar de gerar e esperar que o resultado da função seja passado de volta em um bloco <function_results> que se parece com isto:

XML
<function_results>
<result>
<tool_name>function_name</tool_name>
<stdout>
o resultado da função vai aqui
</stdout>
</result>
</function_results>

O resultado da função deve ser colocado dentro das tags <stdout>. Se a função levantar uma exceção, isso deve ser retornado assim:

XML
<function_results>
<error>
mensagem de erro vai aqui
</error>
</function_results>

O resultado completo da função deve ser passado de volta para o Claude como uma mensagem que continua a conversa de antes. Após receber os resultados da função, o Claude continuará gerando para incorporar os resultados em sua resposta.


Exemplo de prompt de uso de ferramentas legadas

Aqui está um exemplo completo de um prompt que fornece ao Claude duas funções e uma pergunta que requer usá-las:

Conteúdo
SistemaNeste ambiente, você tem acesso a um conjunto de ferramentas que pode usar para responder à pergunta do usuário.

Você pode chamá-las assim:
<function_calls>
<invoke>
<tool_name>$TOOL_NAME</tool_name>
<parameters>
<$PARAMETER_NAME>$PARAMETER_VALUE</$PARAMETER_NAME>

</parameters>
</invoke>
</function_calls>

Aqui estão as ferramentas disponíveis:
<tools>
<tool_description>
<tool_name>get_current_stock_price
</tool_name><description>Obtém o preço atual da ação de uma empresa. Retorna float: O preço atual da ação.
Levanta ValueError: se o símbolo de entrada for inválido/desconhecido.</description>
<parameters>
<parameter>
<name>symbol</name>
<type>string</type>
<description>O símbolo da ação da empresa para obter o preço.</description>
</parameter>
</parameters>
</tool_description>

<tool_description>
<tool_name>get_ticker_symbol</tool_name>
<description>Obtém o símbolo da ação para uma empresa pesquisada pelo nome. Retorna str: O símbolo da ação para a ação da empresa. Levanta TickerNotFound: se nenhum símbolo correspondente for encontrado.
</description>
<parameters>
<parameter>
<name>company_name</name>
<type>string</type>
<description>O nome da empresa.</description>
</parameter>
</parameters>
</tool_description></tools>
UsuárioQual é o preço atual da ação da General Motors?

Aqui está como o Claude responderia:

Conteúdo
Assistente<scratchpad>
Para responder a esta pergunta, eu precisarei:

1. Obter o símbolo da ação para a General Motors usando a função get_ticker_symbol().
2. Usar o símbolo da ação retornado para obter o preço atual da ação usando a função get_current_stock_price().</scratchpad>

<function_calls>
<invoke>
<tool_name>get_ticker_symbol</tool_name>
<parameters>
<company_name>General Motors</company_name>
</parameters>
</invoke>
</function_calls>

O Claude primeiro chama get_ticker_symbol para recuperar o símbolo da ação para a General Motors. Podemos reconhecer que o Claude quer chamar uma função através da sequência de parada </function calls>. Extraímos os dados relevantes entre as tags XML relevantes e executamos a função em nome do Claude. Em seguida, passamos os resultados de volta para o Claude em tags <function_results>.

Conteúdo
Usuário<function_results>
<result>
<tool_name>get_ticker_symbol</tool_name>
<stdout>
GM
</stdout>
</result>
</function_results>

Agora que sabe o símbolo da ação, o Claude subsequentemente decidirá que precisa chamar get_current_stock_price e obter o preço atual.

Conteúdo
Assistente<function_calls>
<invoke>
<tool_name>get_current_stock_price</tool_name>
<parameters>
<symbol>GM</symbol>
</parameters>
</invoke>
</function_calls>

Nós também passamos esses resultados de volta.

Conteúdo
Usuário<function_results>
<result>
<tool_name>get_current_stock_price</tool_name>
<stdout>
38.50
</stdout>
</result>
</function_results>

Com toda essa cadeia de conversa fornecendo ao Claude todos os detalhes de que ele precisa, o Claude será capaz de fornecer uma resposta ao usuário como sua saída final.

Conteúdo
<answer>
O preço atual da ação da General Motors é $38,50.
</answer>

Perguntas frequentes sobre o uso de ferramentas legadas

Quantas ferramentas posso passar para o Claude em uma determinada interação?

Você pode definir qualquer número de ferramentas e funções para o Claude usar, embora atualmente recomendemos que você não exceda 3-5 para esta estrutura legada de uso de ferramentas, dependendo da complexidade do seu caso de uso e das funções em questão.

O Claude tem alguma ferramenta integrada que ele conhece?

Não. Quaisquer ferramentas que você queira que o Claude use, você terá que definir você mesmo dentro de um prompt de uso de ferramentas. O Claude não tem uma lista predeterminada de funções e definições que funcionam melhor.

Quando o novo formato de uso de ferramentas chegará ao Vertex AI ou Amazon Bedrock?

Em um futuro próximo!