Claude Platform Docs
СообщенияИнструменты

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

Разбор блоков tool_use, форматирование ответов tool_result и обработка ошибок с помощью is_error.

Когда ответ Claude содержит блоки tool_use, ваш код запускает каждый инструмент и отправляет обратно блоки tool_result, включая любые ошибки. Пишите этот код самостоятельно, когда вам нужен собственный контроль над выполнением инструментов. В противном случае используйте исполнитель инструментов SDK, который запускает инструменты и отправляет результаты за вас.

Ответ 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, поэтому диспетчеризуйте такие блоки по обоим полям.

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

  1. Для каждого блока tool_use запустите инструмент, указанный в этом блоке, передав ему его input.
  2. В новом запросе сохраните предыдущие сообщения и добавьте content ответа без изменений в виде сообщения assistant.
  3. Добавьте сообщение user с одним блоком tool_result для каждого блока tool_use в этом содержимом, даже если выполнение инструмента завершилось ошибкой.
  4. Отправьте запрос с теми же tools, что и в первом запросе. Claude использует результаты инструментов, чтобы продолжить свой ответ.
  5. Если stop_reason следующего ответа также равен tool_use, повторите эти шаги. Для других значений см. краткий справочник по причинам остановки.

Эти шаги в виде полноценных программ см. в разделе Руководство: создание агента, использующего инструменты.

Каждый блок tool_result имеет type со значением tool_result, а также следующие поля:

  • tool_use_id: id блока tool_use, на который отвечает этот результат.
  • content (необязательно): Результат инструмента в виде строки или списка блоков содержимого. Эти блоки содержимого могут использовать типы text, image, document или search_result.
  • is_error (необязательно): Установите в true, если выполнение инструмента завершилось ошибкой или вызов был недопустимым.

Например, успешный результат инструмента выглядит так:

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

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

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

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

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

Когда клиентский инструмент завершается ошибкой или вызов недопустим, отправьте блок tool_result с is_error, установленным в true. Затем Claude может снова вызвать инструмент с новым блоком tool_use, поэтому ограничьте количество повторных попыток, которое допускает ваш цикл.

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

Обрабатывайте ответы, в которых Claude вызывает несколько инструментов за один ход.

Позвольте SDK управлять циклом tool_use, форматированием результатов и повторными попытками за вас.

Пишите схемы и описания, которые направляют Claude к правильному инструменту.

Эта страница была полезной?