Обработка вызовов инструментов
Разбор блоков 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, поэтому диспетчеризуйте такие блоки по обоим полям.
{
"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" }
}
]
}Когда вы получаете ответ с использованием инструмента для клиентского инструмента, выполните следующие шаги:
- Для каждого блока
tool_useзапустите инструмент, указанный в этом блоке, передав ему егоinput. - В новом запросе сохраните предыдущие сообщения и добавьте
contentответа без изменений в виде сообщенияassistant. - Добавьте сообщение
userс одним блокомtool_resultдля каждого блокаtool_useв этом содержимом, даже если выполнение инструмента завершилось ошибкой. - Отправьте запрос с теми же
tools, что и в первом запросе. Claude использует результаты инструментов, чтобы продолжить свой ответ. - Если
stop_reasonследующего ответа также равенtool_use, повторите эти шаги. Для других значений см. краткий справочник по причинам остановки.
Эти шаги в виде полноценных программ см. в разделе Руководство: создание агента, использующего инструменты.
Каждый блок tool_result имеет type со значением tool_result, а также следующие поля:
tool_use_id:idблокаtool_use, на который отвечает этот результат.content(необязательно): Результат инструмента в виде строки или списка блоков содержимого. Эти блоки содержимого могут использовать типыtext,image,documentилиsearch_result.is_error(необязательно): Установите вtrue, если выполнение инструмента завершилось ошибкой или вызов был недопустимым.
Например, успешный результат инструмента выглядит так:
{
"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 (члены набора для управления вкладками возвращают только этот блок).
{
"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"
}
}
]
}
]
}Например, это вызывает ошибку 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
]
}Обработка результатов серверных инструментов
Claude запускает инструмент внутри системы и включает результаты непосредственно в свой ответ, не требуя дополнительного взаимодействия с пользователем.
Обработка ошибок с помощью is_error
Когда клиентский инструмент завершается ошибкой или вызов недопустим, отправьте блок tool_result с is_error, установленным в true. Затем Claude может снова вызвать инструмент с новым блоком tool_use, поэтому ограничьте количество повторных попыток, которое допускает ваш цикл.
Если сам инструмент выдаёт ошибку во время выполнения (например, сетевая ошибка при получении данных о погоде), вы можете вернуть сообщение об ошибке в content вместе с "is_error": true:
{
"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
}
]
}Затем Claude может снова вызвать инструмент или сообщить пользователю, что произошло. Например, Claude может сказать: «Извините, мне не удалось получить текущую погоду, так как API погодного сервиса недоступен. Пожалуйста, попробуйте позже.»
Если попытка Claude использовать инструмент недопустима (например, отсутствуют обязательные параметры), обычно это означает, что у Claude было недостаточно информации для правильного использования инструмента. Лучший подход во время разработки — повторить запрос с более подробными значениями description в определениях ваших инструментов.
Однако вы также можете продолжить диалог с tool_result, указывающим на ошибку:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Затем Claude может снова вызвать инструмент, заполнив недостающую информацию.
В отличие от клиентских инструментов, для серверных инструментов вы не отправляете результаты is_error. Когда серверный инструмент сталкивается с ошибкой, например с сетевой проблемой при веб-поиске, API возвращает ошибку внутри блока результата инструмента. В большинстве случаев Claude затем продолжает, используя другой подход, или предоставляет пользователю объяснение.
Коды ошибок веб-поиска см. в разделе Ошибки инструмента веб-поиска.
Следующие шаги
Обрабатывайте ответы, в которых Claude вызывает несколько инструментов за один ход.
Позвольте SDK управлять циклом tool_use, форматированием результатов и повторными попытками за вас.
Пишите схемы и описания, которые направляют Claude к правильному инструменту.
Эта страница была полезной?