Claude Platform Docs
MensagensFerramentas

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 o input_schema da 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.

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.

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: 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.
  • 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
{
  "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).

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.

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?