Lidar com chamadas de ferramentas

Esta página cobre o ciclo de vida da chamada de ferramentas: ler blocos tool_use da resposta do Claude, formatar blocos tool_result em sua resposta e sinalizar erros. Para a abstração do SDK que lida com isso automaticamente, consulte Tool Runner.

A resposta do Claude difere dependendo se ele usa uma ferramenta de cliente ou servidor.

Tratamento de resultados de ferramentas de cliente

A resposta terá um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:

• id: Um identificador único para este bloco de uso de ferramenta específico. Isso será usado para corresponder aos 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.

Quando você recebe uma resposta de uso de ferramenta para uma ferramenta de cliente, você deve:

1. Extrair o name, id e input do bloco tool_use.
2. Executar a ferramenta real em sua base de código correspondente ao nome da ferramenta, passando a input da ferramenta.
3. 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 esta é uma resultado.
   • content: O resultado da ferramenta, como uma string (por exemplo, ), uma lista de blocos de conteúdo aninhados (por exemplo, ), ou uma lista de blocos de documento (por exemplo, ). Esses blocos de conteúdo podem usar os tipos , ou .

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

Após receber o resultado da ferramenta, Claude usará essas informações para continuar gerando uma resposta ao prompt do usuário original.

Tratamento de resultados de ferramentas de servidor

Claude executa a ferramenta internamente e incorpora os resultados diretamente em sua resposta sem exigir interação adicional do usuário.

Tratamento de erros com is_error

Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com Claude:

Próximas etapas

• Para executar múltiplas ferramentas em um turno, consulte Parallel tool use.
• Para a abstração do SDK que automatiza este loop, consulte Tool Runner.
• Para o fluxo de trabalho completo de uso de ferramentas, consulte Define tools.

Isto está correto:

Se você receber um erro como "tool_use ids were found without tool_result blocks immediately after", verifique se seus resultados de ferramentas estão formatados corretamente.