Обработка вызовов инструментов

На этой странице описан жизненный цикл вызова инструмента: чтение блоков tool_use из ответа Claude, форматирование блоков tool_result в вашем ответе и сигнализация об ошибках. Об абстракции SDK, которая обрабатывает это автоматически, см. Tool Runner.

Ответ Claude различается в зависимости от того, использует ли он клиентский или серверный инструмент.

Обработка результатов клиентских инструментов

Ответ будет иметь stop_reason со значением tool_use и один или несколько блоков содержимого tool_use, которые включают:

• id: Уникальный идентификатор данного конкретного блока использования инструмента. Он будет использоваться позже для сопоставления с результатами инструмента.
• name: Имя используемого инструмента.
• input: Объект, содержащий входные данные, передаваемые инструменту, в соответствии с input_schema инструмента.

Блок tool_use для члена набора инструментов computer use (использование компьютера) или browser use (использование браузера) также содержит поле toolset_name ("computer" или "browser"). Его name — это инструмент-член набора, который вызывает Claude, например screenshot или navigate, поэтому диспетчеризуйте такие блоки по обоим полям.

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

Когда вы получаете ответ с использованием инструмента для клиентского инструмента, вам следует:

1. Извлечь name, id и input из блока tool_use.
2. Запустить в вашей кодовой базе фактический инструмент, соответствующий этому имени инструмента, передав ему input инструмента.
3. Продолжить разговор, отправив новое сообщение с role равным user и блоком content, содержащим тип tool_result и следующую информацию:
   • tool_use_id: id запроса на использование инструмента, для которого это результат.
   • content (необязательно): Результат инструмента в виде строки (например, "content": "15 degrees"), списка вложенных блоков содержимого (например, "content": [{"type": "text", "text": "15 degrees"}]) или списка блоков документов (например, "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Эти блоки содержимого могут использовать типы text, image, document или search_result.
   • is_error (необязательно): Установите в true, если выполнение инструмента завершилось ошибкой.

tool_result, отвечающий на блок члена набора computer use или browser use, также должен повторять то же значение toolset_name, что и блок tool_use; результат члена набора, в котором оно опущено, отклоняется. Его content также более ограничен: результат члена набора может содержать только блоки text и image, а результат browser use может добавить один блок browser_state (члены набора для управления вкладками возвращают только этот блок).

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

После получения результата инструмента Claude использует эту информацию, чтобы продолжить генерацию ответа на исходную подсказку пользователя.

Обработка результатов серверных инструментов

Claude выполняет инструмент внутренне и включает результаты непосредственно в свой ответ, не требуя дополнительного взаимодействия с пользователем.

Обработка ошибок с помощью is_error

Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с 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
    }
  ]
}

Следующие шаги