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, "content": "15 degrees"), uma lista de blocos de conteúdo aninhados (por exemplo, "content": [{"type": "text", "text": "15 degrees"}]), ou uma lista de blocos de documento (por exemplo, "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Esses blocos de conteúdo podem usar os tipos text, image ou document.
   • is_error (opcional): Defina como true se a execução da ferramenta resultou em um erro.

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

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

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.