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

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/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](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 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 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.

<Accordion title="Exemplo de resposta da API com um bloco de conteúdo `tool_use`">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

Quando você recebe uma resposta de uso de ferramentas para uma ferramenta de cliente, siga estes passos:

1. Para cada bloco `tool_use`, execute a ferramenta que o bloco nomeia, passando seu `input`.
2. Em uma nova solicitação, mantenha as mensagens anteriores e adicione o `content` da resposta, sem alterações, como uma mensagem `assistant`.
3. Adicione uma mensagem `user` com um bloco `tool_result` para cada bloco `tool_use` nesse conteúdo, mesmo que a ferramenta tenha falhado.
4. Envie a solicitação com as mesmas `tools` da primeira solicitação. O Claude usa os resultados das ferramentas para continuar sua resposta.
5. Se o `stop_reason` da próxima resposta também for `tool_use`, repita esses passos. Para outros valores, consulte a [referência rápida de motivos de parada](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#quick-reference).

Para esses passos como programas completos, consulte [Tutorial: Construa um agente que usa ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/build-a-tool-using-agent).

Cada bloco `tool_result` tem `type` definido como `tool_result`, além destes campos:

* `tool_use_id`: O `id` do bloco `tool_use` ao 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 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 ferramenta falhou ou a chamada foi inválida.

Por exemplo, um resultado de ferramenta bem-sucedido tem esta aparência:

```json JSON
{
  "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`](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).

<Note>
  **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 que contém 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).

  Se você receber um erro como “tool\_use ids were found without tool\_result blocks immediately after”, verifique se os resultados das suas ferramentas estão formatados corretamente.
</Note>

<Warning>
  Resultados de ferramentas frequentemente trazem 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 capaz de influenciá-lo pode incorporar instruções que tentam redirecionar Claude (injeção de prompt indireta). 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 proteções adicionais.
</Warning>

<AccordionGroup>
  <Accordion title="Exemplo de resultado de ferramenta com imagens">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemplo de resultado de ferramenta vazio">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemplo de resultado de ferramenta com documentos">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemplo de texto antes e depois de um resultado de ferramenta">
    Por exemplo, isto causa 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  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 está concluída, e seu bloco de resultado chega em uma resposta posterior. Responda com uma mensagem do usuário que contenha apenas os blocos `tool_result` das ferramentas de cliente e mantenha o mesmo array `tools`; para uma ferramenta de servidor que 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).
</Note>

<Tip>
  **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`. Mensagens `user` incluem conteúdo do cliente e `tool_result`, enquanto mensagens `assistant` contêm conteúdo gerado por IA e `tool_use`.
</Tip>

## 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.

<AccordionGroup>
  <Accordion title="Erro de execução da ferramenta">
    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 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.”

    <Tip>
      Escreva mensagens de erro instrutivas. Em vez de erros genéricos como `"failed"`, inclua o que deu errado e o que Claude deve tentar em seguida (por exemplo, `"Rate limit exceeded. Retry after 60 seconds."`). Isso dá a Claude o contexto necessário para se recuperar ou se adaptar sem precisar adivinhar.
    </Tip>
  </Accordion>

  <Accordion title="Chamada de ferramenta inválida">
    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:

    ```json JSON
    {
      "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.

    <Tip>
      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 definições das suas ferramentas. Isso garante que as entradas das ferramentas sempre correspondam exatamente ao seu schema, evitando parâmetros ausentes e incompatibilidades de tipo.
    </Tip>
  </Accordion>

  <Accordion title="Erros de ferramentas de servidor">
    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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Uso paralelo de ferramentas" icon="grid" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use">
    Lide com respostas em que o Claude chama várias ferramentas em um único turno.
  </Card>

  <Card title="Tool runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner">
    Deixe o SDK gerenciar o loop de `tool_use`, a formatação de resultados e as novas tentativas para você.
  </Card>

  <Card title="Definir ferramentas" icon="hammer" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools">
    Escreva schemas e descrições que direcionem o Claude para a ferramenta certa.
  </Card>
</CardGroup>
