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

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

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

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

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

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

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

1. Извлечь name, id и input из блока tool_use.
2. Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав входные данные инструмента.
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.
   • is_error (опционально): установите значение true, если выполнение инструмента привело к ошибке.

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

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

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

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

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

При использовании инструментов с Claude может возникнуть несколько различных типов ошибок:

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

• Для запуска нескольких инструментов за один ход см. Parallel tool use.
• Для абстракции SDK, которая автоматизирует этот цикл, см. Tool Runner.
• Для полного рабочего процесса использования инструмента см. Define tools.