Lidar com chamadas de ferramentas

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

Esta página cobre o ciclo de vida da chamada de ferramenta: ler blocos tool_use da resposta de 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.

A resposta de Claude difere dependendo de usar 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 de uso de ferramenta específico. Ele 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 ferramentas 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 um bloco de resultado, a mensagem do usuário deve conter apenas blocos tool_result. Texto após os resultados encerra o turno antecipadamente; para uma ferramenta de servidor que Claude chamou diretamente, a solicitação então falha com um erro 400 que nomeia a ferramenta de servidor não resolvida. Consulte Razões 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, Claude usará essa informação para continuar gerando uma resposta ao prompt original do usuário.

Lidando com 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.

Lidando com erros usando is_error

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

Próximos passos

Uso paralelo de ferramentas

Lide com respostas em que 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 para você.

Definir ferramentas

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

Was this page helpful?

MessagesFerramentas

Lidar com chamadas de ferramentas

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

A resposta de Claude difere dependendo de usar 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 de uso de ferramenta específico. Ele 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 ferramentas 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 um bloco de resultado, a mensagem do usuário deve conter apenas blocos tool_result. Texto após os resultados encerra o turno antecipadamente; para uma ferramenta de servidor que Claude chamou diretamente, a solicitação então falha com um erro 400 que nomeia a ferramenta de servidor não resolvida. Consulte Razões 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, Claude usará essa informação para continuar gerando uma resposta ao prompt original do usuário.

Lidando com 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.

Lidando com erros usando is_error

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

Próximos passos

Uso paralelo de ferramentas

Lide com respostas em que 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 para você.

Definir ferramentas

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

Was this page helpful?

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