Lidar com chamadas de ferramentas
Analise blocos tool_use, formate respostas tool_result e trate erros com is_error.
Quando a resposta do Claude contém blocos tool_use, seu código executa cada ferramenta e envia de volta blocos tool_result, incluindo quaisquer erros. Escreva esse código você mesmo quando precisar de controle personalizado sobre a execução de ferramentas. Caso contrário, use o tool runner do SDK, que executa as ferramentas e envia os resultados para você.
A resposta do Claude difere dependendo de ele usar uma ferramenta de cliente ou de servidor.
Lidando com resultados de ferramentas de cliente
A resposta tem um stop_reason igual a tool_use e um ou mais blocos de conteúdo tool_use que incluem:
id: Um identificador único para este bloco específico de “tool use” (uso de ferramentas). Ele é usado para associar os 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 oinput_schemada ferramenta.
Um bloco tool_use para um membro do conjunto de ferramentas de uso de computador ou uso de navegador também carrega um campo toolset_name ("computer" ou "browser"). Seu name é a ferramenta membro que o Claude está chamando, como screenshot ou navigate, portanto despache esses blocos com base em ambos os campos.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}Quando você recebe uma resposta de uso de ferramentas para uma ferramenta de cliente, siga estes passos:
- Para cada bloco
tool_use, execute a ferramenta que o bloco nomeia, passando seuinput. - Em uma nova solicitação, mantenha as mensagens anteriores e adicione o
contentda resposta, sem alterações, como uma mensagemassistant. - Adicione uma mensagem
usercom um blocotool_resultpara cada blocotool_usenesse conteúdo, mesmo que a ferramenta tenha falhado. - Envie a solicitação com as mesmas
toolsda primeira solicitação. O Claude usa os resultados das ferramentas para continuar sua resposta. - Se o
stop_reasonda próxima resposta também fortool_use, repita esses passos. Para outros valores, consulte a referência rápida de motivos de parada.
Para esses passos como programas completos, consulte Tutorial: Construa um agente que usa ferramentas.
Cada bloco tool_result tem type definido como tool_result, além destes campos:
tool_use_id: Oiddo blocotool_useao qual este resultado responde.content(opcional): O resultado da ferramenta como uma string ou uma lista de blocos de conteúdo. Esses blocos de conteúdo podem usar os tipostext,image,documentousearch_result.is_error(opcional): Defina comotruese a ferramenta falhou ou a chamada foi inválida.
Por exemplo, um resultado de ferramenta bem-sucedido tem esta aparência:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}Um tool_result que responde a um bloco membro de uso de computador ou uso de navegador também deve repetir o mesmo valor de toolset_name do bloco tool_use; um resultado de membro que o omite é rejeitado. Seu content também é mais restrito: um resultado de membro pode conter apenas blocos text e image, e um resultado de uso de navegador pode adicionar um bloco browser_state (os membros de gerenciamento de abas retornam apenas esse bloco).
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}Por exemplo, isto causa 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
]
}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.
Tratando erros com is_error
Quando uma ferramenta de cliente falha ou uma chamada é inválida, envie um bloco tool_result com is_error definido como true. O Claude pode então chamar a ferramenta novamente com um novo bloco tool_use, portanto limite quantas novas tentativas seu loop permite.
Se a própria ferramenta lançar um erro durante a execução (por exemplo, um erro de rede ao buscar dados meteorológicos), você pode retornar a mensagem de erro no content junto com "is_error": true:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}O Claude pode então chamar a ferramenta novamente ou informar ao usuário o que aconteceu. Por exemplo, o Claude pode dizer “Desculpe, não consegui obter o clima atual porque a API do serviço meteorológico não está disponível. Por favor, tente novamente mais tarde.”
Se a tentativa de Claude de usar uma ferramenta for inválida (por exemplo, faltando parâmetros obrigatórios), geralmente significa que não havia informações suficientes para Claude usar a ferramenta corretamente. A melhor abordagem durante o desenvolvimento é tentar a solicitação novamente com valores de description mais detalhados nas definições das suas ferramentas.
No entanto, você também pode dar continuidade à conversa com um tool_result que indique o erro:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude pode então chamar a ferramenta novamente com as informações ausentes preenchidas.
Ao contrário das ferramentas de cliente, você não envia resultados is_error para ferramentas de servidor. Quando uma ferramenta de servidor encontra um erro, como um problema de rede durante a pesquisa na web, a API retorna o erro dentro do bloco de resultado da ferramenta. Na maioria dos casos, Claude então continua com outra abordagem ou uma explicação para o usuário.
Para os códigos de erro da pesquisa na web, consulte Erros da ferramenta de pesquisa na web.
Próximos passos
Lide com respostas em que o Claude chama várias ferramentas em um único turno.
Deixe o SDK gerenciar o loop de tool_use, a formatação de resultados e as novas tentativas para você.
Escreva schemas e descrições que direcionem o Claude para a ferramenta certa.
Esta página foi útil?