Lidar com chamadas de ferramentas

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.

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 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 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",
  "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.
   • 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 (os membros de gerenciamento de abas retornam apenas esse bloco).

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "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"
          }
        }
      ]
    }
  ]
}

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.

Tratando erros com is_error

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

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Próximos passos