---
title: Lidar com chamadas de ferramentas
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls
description: Analise blocos tool_use, formate respostas tool_result e trate erros com is_error.
---
Esta página cobre o ciclo de vida de uma chamada de ferramenta: 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner).
**Mais simples com o Tool Runner:** O tratamento manual de ferramentas descrito nesta página é gerenciado automaticamente pelo [Tool Runner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner). Use esta página quando precisar de controle personalizado sobre a execução de ferramentas.
A resposta do Claude difere dependendo de ele usar uma [ferramenta de cliente ou de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview#how-tool-use-works).
## 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 ferramentas 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.
Um bloco `tool_use` para um membro do conjunto de ferramentas de [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) ou [uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) 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.
```json JSON
{
"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, você deve:
1. Extrair o `name`, o `id` e o `input` do bloco `tool_use`.
2. Executar a ferramenta real na sua base de código correspondente a esse nome de ferramenta, passando o `input` da ferramenta.
3. 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 ferramentas 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`](https://platform.claude.com/docs/pt-BR/build-with-claude/search-results).
* `is_error` (opcional): Defina como `true` se a execução da ferramenta resultou em um erro.
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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) (os [membros de gerenciamento de abas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-management-results) retornam apenas esse bloco).
**Requisitos importantes de formatação:**
* Os blocos de resultado de ferramenta devem seguir imediatamente seus blocos de uso de ferramentas correspondentes no histórico de mensagens. Você não pode incluir nenhuma mensagem entre a mensagem de uso de ferramentas 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) 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 antecipadamente; 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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use).
Por exemplo, isto causará um erro 400:
```json
{
"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:
```json
{
"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.
Os resultados de ferramentas frequentemente carregam conteúdo de fontes fora do seu controle: páginas da 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 ("indirect prompt injection", ou injeção indireta de prompt). Mantenha o 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](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) para reforço adicional.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"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..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"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"
}
}
]
}
]
}
```
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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use).
**Diferenças em relação a outras APIs**
Ao contrário de APIs que separam o uso de ferramentas ou usam papéis especiais como `tool` ou `function`, a Claude API integra as ferramentas diretamente na estrutura de mensagens `user` e `assistant`.
As mensagens contêm arrays de blocos `text`, `image`, `tool_use` e `tool_result`. As mensagens `user` incluem conteúdo do cliente e `tool_result`, enquanto as mensagens `assistant` contêm conteúdo gerado por IA e `tool_use`.
## Tratando erros com is\_error
Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com o Claude:
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`:
```json JSON
{
"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 então incorporará esse erro em sua resposta ao usuário. Por exemplo: "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."
Escreva mensagens de erro instrutivas. Em vez de erros genéricos como `"failed"`, inclua o que deu errado e o que o Claude deve tentar em seguida (por exemplo, `"Rate limit exceeded. Retry after 60 seconds."`). Isso dá ao Claude o contexto de que ele precisa para se recuperar ou se adaptar sem adivinhar.
Se a tentativa do Claude de usar uma ferramenta for inválida (por exemplo, parâmetros obrigatórios ausentes), isso geralmente significa que não havia informações suficientes para o Claude usar a ferramenta corretamente. Sua melhor opção durante o desenvolvimento é tentar a solicitação novamente com valores de `description` mais detalhados nas suas definições de ferramentas.
No entanto, você também pode continuar a conversa com um `tool_result` que indique o erro, e o Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
Se uma solicitação de ferramenta for inválida ou estiver com parâmetros ausentes, o Claude tentará novamente 2 a 3 vezes com correções antes de se desculpar com o usuário.
Para eliminar completamente chamadas de ferramentas inválidas, use o [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) com `strict: true` nas suas definições de ferramentas. Isso garante que as entradas das ferramentas sempre corresponderão exatamente ao seu schema, evitando parâmetros ausentes e incompatibilidades de tipo.
Quando ferramentas de servidor encontram erros (por exemplo, problemas de rede com a Web Search), o Claude tratará esses erros de forma transparente e tentará fornecer uma resposta alternativa ou explicação ao usuário. Ao contrário das ferramentas de cliente, você não precisa tratar resultados `is_error` para ferramentas de servidor.
Para a pesquisa na web especificamente, os possíveis códigos de erro incluem:
* `too_many_requests`: Limite de taxa excedido
* `invalid_input`: Parâmetro de consulta de pesquisa inválido
* `max_uses_exceeded`: Número máximo de usos da ferramenta de pesquisa na web excedido
* `query_too_long`: A consulta excede o comprimento máximo
* `unavailable`: Ocorreu um erro interno
## 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.