MensagensFerramentas

Lidar com chamadas de ferramentas

Analise blocos tool_use, formate respostas tool_result e lide com erros usando is_error.

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

Mais simples com o Tool Runner: O tratamento manual de ferramentas descrito nesta página é gerenciado automaticamente pelo Tool Runner. Use esta página quando precisar de controle personalizado sobre a execução de ferramentas.

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

Lidando com 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 específico de uso de ferramenta. 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ê receber uma resposta de uso de ferramenta para uma ferramenta de cliente, você deve:

Extrair o name, id e input do bloco tool_use.
Executar a ferramenta real no seu código correspondente a esse nome de ferramenta, passando o input da ferramenta.
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 (opcional): 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, document ou search_result.
- is_error (opcional): Defina como true se a execução da ferramenta resultou em um erro.

Requisitos importantes de formatação:

Os blocos de resultado de ferramenta devem seguir imediatamente seus blocos de uso de ferramenta correspondentes no histórico de mensagens. Você não pode incluir nenhuma mensagem entre a mensagem de uso de ferramenta do assistente e a mensagem de resultado de ferramenta do usuário.
Na mensagem do usuário contendo resultados de ferramentas, os blocos tool_result devem vir PRIMEIRO no array de conteúdo. Qualquer texto deve vir DEPOIS de todos os resultados de ferramentas.
Se o turno do assistente também chamou uma ferramenta de servidor que ainda não tem bloco de resultado, a mensagem do usuário deve conter apenas blocos tool_result. Texto após os resultados encerra o turno prematuramente; para uma ferramenta de servidor que o Claude chamou diretamente, a solicitação então falha com um erro 400 que nomeia a ferramenta de servidor não resolvida. Consulte Motivos de parada e fallback.

Por exemplo, isto causará um erro 400:

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

Isto está correto quando o turno do assistente chama apenas ferramentas de cliente:

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

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.

Resultados de ferramentas frequentemente carregam conteúdo de fontes fora do seu controle: páginas web, e-mails recebidos, uploads de usuários, APIs de terceiros. Trate esse conteúdo como não confiável: um invasor que possa influenciá-lo pode incorporar instruções que tentam redirecionar o Claude (injeção indireta de prompt). Mantenha conteúdo não confiável dentro de blocos tool_result em vez de prompts system ou blocos text simples do usuário, e consulte Mitigar jailbreaks e injeções de prompt para reforço adicional.

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

Lidando com resultados de ferramentas de servidor

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

Uma resposta pode conter tanto um bloco tool_use de cliente quanto um bloco server_tool_use que não tem bloco de resultado. Essa chamada de ferramenta de servidor ainda não foi concluída, e seu bloco de resultado chega em uma resposta posterior. Responda com uma mensagem de usuário que contenha apenas os blocos tool_result para as ferramentas de cliente e mantenha o mesmo array tools; para uma ferramenta de servidor que o Claude chamou diretamente, a API a executa nessa solicitação e a próxima resposta começa com seu bloco de resultado. Consulte Motivos de parada e fallback.

Diferenças em relação a outras APIs

Diferentemente de APIs que separam o uso de ferramentas ou usam roles especiais como tool ou function, a API do Claude integra ferramentas diretamente na estrutura de mensagens user e assistant.

As mensagens contêm arrays de blocos text, image, tool_use e tool_result. Mensagens user incluem conteúdo do cliente e tool_result, enquanto mensagens assistant contêm conteúdo gerado por IA e tool_use.

Lidando com erros usando is_error

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

Próximos passos

Uso paralelo de ferramentas

Lide com respostas em que o Claude chama várias ferramentas em um único turno.

Tool Runner (SDK)

Deixe o SDK gerenciar o loop de tool_use, a formatação de resultados e as novas tentativas por você.

Definir ferramentas

Escreva schemas e descrições que direcionem o Claude para a ferramenta certa.

Was this page helpful?

Lidando com 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 específico de uso de ferramenta. 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ê receber uma resposta de uso de ferramenta para uma ferramenta de cliente, você deve:

Extrair o name, id e input do bloco tool_use.

Executar a ferramenta real no seu código correspondente a esse nome de ferramenta, passando o input da ferramenta.

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 (opcional): 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, document ou search_result.
is_error (opcional): Defina como true se a execução da ferramenta resultou em um erro.

Requisitos importantes de formatação:

Os blocos de resultado de ferramenta devem seguir imediatamente seus blocos de uso de ferramenta correspondentes no histórico de mensagens. Você não pode incluir nenhuma mensagem entre a mensagem de uso de ferramenta do assistente e a mensagem de resultado de ferramenta do usuário.
Na mensagem do usuário contendo resultados de ferramentas, os blocos tool_result devem vir PRIMEIRO no array de conteúdo. Qualquer texto deve vir DEPOIS de todos os resultados de ferramentas.
Se o turno do assistente também chamou uma ferramenta de servidor que ainda não tem bloco de resultado, a mensagem do usuário deve conter apenas blocos tool_result. Texto após os resultados encerra o turno prematuramente; para uma ferramenta de servidor que o Claude chamou diretamente, a solicitação então falha com um erro 400 que nomeia a ferramenta de servidor não resolvida. Consulte Motivos de parada e fallback.

Por exemplo, isto causará um erro 400:

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

Isto está correto quando o turno do assistente chama apenas ferramentas de cliente:

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

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.

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

Lidando com resultados de ferramentas de servidor

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

Diferenças em relação a outras APIs

Lidando com resultados de ferramentas de cliente

Exemplo de resposta da API com um bloco de conteúdo `tool_use`

Exemplo de resultado de ferramenta bem-sucedido

Exemplo de resultado de ferramenta com imagens

Exemplo de resultado de ferramenta vazio

Exemplo de resultado de ferramenta com documentos

Lidando com resultados de ferramentas de servidor

Lidando com erros usando is_error

Erro de execução de ferramenta

Nome de ferramenta inválido

Erros de ferramentas de servidor

Próximos passos

Lidando com resultados de ferramentas de cliente

Exemplo de resposta da API com um bloco de conteúdo `tool_use`

Exemplo de resultado de ferramenta bem-sucedido

Exemplo de resultado de ferramenta com imagens

Exemplo de resultado de ferramenta vazio

Exemplo de resultado de ferramenta com documentos

Lidando com resultados de ferramentas de servidor

Lidando com erros usando is_error

Erro de execução de ferramenta

Nome de ferramenta inválido

Erros de ferramentas de servidor

Próximos passos

Lidando com resultados de ferramentas de cliente

Lidando com resultados de ferramentas de servidor

Lidando com erros usando is_error

Próximos passos

Lidando com resultados de ferramentas de cliente

Lidando com resultados de ferramentas de servidor

Lidando com erros usando is_error

Próximos passos