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

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

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

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

Проще с Tool Runner: Ручная обработка инструментов, описанная на этой странице, автоматически выполняется с помощью Tool Runner. Используйте эту страницу, когда вам нужен индивидуальный контроль над выполнением инструментов.

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

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

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

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

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

Извлечь name, id и input из блока tool_use.
Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав ему input инструмента.
Продолжить диалог, отправив новое сообщение с 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 должны идти ПЕРВЫМИ в массиве content. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
Если ход ассистента также вызвал серверный инструмент, у которого ещё нет блока результата, сообщение пользователя должно содержать только блоки tool_result. Текст после результатов преждевременно завершает ход; для серверного инструмента, который Claude вызвал напрямую, запрос затем завершается с ошибкой 400, в которой указывается неразрешённый серверный инструмент. См. Причины остановки и резервное поведение.

Например, это приведёт к ошибке 400:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

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

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

Если вы получаете ошибку вида «tool_use ids were found without tool_result blocks immediately after», проверьте, что ваши результаты инструментов отформатированы правильно.

Результаты инструментов часто содержат контент из источников, находящихся вне вашего контроля: веб-страницы, входящая электронная почта, загрузки пользователей, сторонние API. Относитесь к такому контенту как к недоверенному: злоумышленник, который может на него повлиять, может внедрить инструкции, пытающиеся перенаправить Claude (косвенная инъекция подсказок). Храните недоверенный контент внутри блоков tool_result, а не в подсказках system или обычных блоках text пользователя, и см. Предотвращение джейлбрейков и инъекций подсказок для дополнительного усиления защиты.

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

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

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

Ответ может содержать как клиентский блок tool_use, так и блок server_tool_use, у которого нет блока результата. Этот вызов серверного инструмента ещё не завершён, и его блок результата поступит в более позднем ответе. Ответьте сообщением пользователя, которое содержит только блоки tool_result для клиентских инструментов, и сохраните тот же массив tools; для серверного инструмента, который Claude вызвал напрямую, API выполняет его в рамках этого запроса, и следующий ответ начинается с его блока результата. См. Причины остановки и резервное поведение.

Отличия от других API

В отличие от API, которые выделяют использование инструментов отдельно или используют специальные роли, такие как tool или function, API Claude интегрирует инструменты непосредственно в структуру сообщений user и assistant.

Сообщения содержат массивы блоков text, image, tool_use и tool_result. Сообщения user включают клиентский контент и tool_result, тогда как сообщения assistant содержат сгенерированный ИИ контент и tool_use.

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

Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с Claude:

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

Параллельное использование инструментов

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

Tool Runner (SDK)

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

Определение инструментов

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

Was this page helpful?

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

id: Уникальный идентификатор для данного конкретного блока использования инструмента. Он будет использоваться для сопоставления результатов инструмента позже.

name: Имя используемого инструмента.

input: Объект, содержащий входные данные, передаваемые инструменту, соответствующие input_schema инструмента.

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

Извлечь name, id и input из блока tool_use.

Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав ему input инструмента.

Продолжить диалог, отправив новое сообщение с 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 должны идти ПЕРВЫМИ в массиве content. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
Если ход ассистента также вызвал серверный инструмент, у которого ещё нет блока результата, сообщение пользователя должно содержать только блоки tool_result. Текст после результатов преждевременно завершает ход; для серверного инструмента, который Claude вызвал напрямую, запрос затем завершается с ошибкой 400, в которой указывается неразрешённый серверный инструмент. См. Причины остановки и резервное поведение.

Например, это приведёт к ошибке 400:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

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

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

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

Отличия от других API

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

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

Пример ответа API с блоком контента `tool_use`

Пример успешного результата инструмента

Пример результата инструмента с изображениями

Пример пустого результата инструмента

Пример результата инструмента с документами

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

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

Ошибка выполнения инструмента

Недопустимое имя инструмента

Ошибки серверных инструментов

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

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

Пример ответа API с блоком контента `tool_use`

Пример успешного результата инструмента

Пример результата инструмента с изображениями

Пример пустого результата инструмента

Пример результата инструмента с документами

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

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

Ошибка выполнения инструмента

Недопустимое имя инструмента

Ошибки серверных инструментов

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

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

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

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

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

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

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

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

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