---
title: Обработка вызовов инструментов
url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls
description: Разбор блоков tool_use, форматирование ответов tool_result и обработка ошибок с помощью is_error.
---
На этой странице описан жизненный цикл вызова инструмента: чтение блоков `tool_use` из ответа Claude, форматирование блоков `tool_result` в вашем ответе и сигнализация об ошибках. Об абстракции SDK, которая обрабатывает это автоматически, см. [Tool Runner](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner).
**Проще с Tool Runner:** Ручная обработка инструментов, описанная на этой странице, автоматически выполняется [Tool Runner](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner). Используйте эту страницу, когда вам нужен собственный контроль над выполнением инструментов.
Ответ Claude различается в зависимости от того, использует ли он [клиентский или серверный инструмент](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/overview#how-tool-use-works).
## Обработка результатов клиентских инструментов
Ответ будет иметь `stop_reason` со значением `tool_use` и один или несколько блоков содержимого `tool_use`, которые включают:
* `id`: Уникальный идентификатор данного конкретного блока использования инструмента. Он будет использоваться позже для сопоставления с результатами инструмента.
* `name`: Имя используемого инструмента.
* `input`: Объект, содержащий входные данные, передаваемые инструменту, в соответствии с `input_schema` инструмента.
Блок `tool_use` для члена набора инструментов [computer use](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/computer-use-tool) (использование компьютера) или [browser use](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/browser-use-tool) (использование браузера) также содержит поле `toolset_name` (`"computer"` или `"browser"`). Его `name` — это инструмент-член набора, который вызывает Claude, например `screenshot` или `navigate`, поэтому диспетчеризуйте такие блоки по обоим полям.
```json JSON
{
"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`](https://platform.claude.com/docs/ru/build-with-claude/search-results).
* `is_error` (необязательно): Установите в `true`, если выполнение инструмента завершилось ошибкой.
`tool_result`, отвечающий на блок члена набора computer use или browser use, также должен повторять то же значение `toolset_name`, что и блок `tool_use`; результат члена набора, в котором оно опущено, отклоняется. Его `content` также более ограничен: результат члена набора может содержать только блоки `text` и `image`, а результат browser use может добавить один блок [`browser_state`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) ([члены набора для управления вкладками](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/browser-use-tool#tab-management-results) возвращают только этот блок).
**Важные требования к форматированию:**
* Блоки результатов инструментов должны следовать непосредственно за соответствующими блоками использования инструментов в истории сообщений. Вы не можете включать какие-либо сообщения между сообщением ассистента с использованием инструмента и сообщением пользователя с результатом инструмента.
* В сообщении пользователя, содержащем результаты инструментов, блоки tool\_result должны идти ПЕРВЫМИ в массиве content. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
* Если ход ассистента также вызвал [серверный инструмент](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools), для которого ещё нет блока результата, сообщение пользователя должно содержать только блоки `tool_result`. Текст после результатов преждевременно завершает ход; для серверного инструмента, который Claude вызвал напрямую, запрос затем завершается ошибкой 400, в которой указан неразрешённый серверный инструмент. См. [Причины остановки и резервное поведение](https://platform.claude.com/docs/ru/build-with-claude/handling-stop-reasons#tool-use).
Например, это вызовет ошибку 400:
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}
```
Это правильно, когда ход ассистента вызывает только клиентские инструменты:
```json
{
"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 («indirect prompt injection» — косвенная инъекция подсказок). Храните недоверенный контент внутри блоков `tool_result`, а не в подсказках `system` или обычных пользовательских блоках `text`, и см. [Противодействие джейлбрейкам и инъекциям подсказок](https://platform.claude.com/docs/ru/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) для дополнительного усиления защиты.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"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..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"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 выполняет инструмент внутренне и включает результаты непосредственно в свой ответ, не требуя дополнительного взаимодействия с пользователем.
Ответ может содержать как клиентский блок `tool_use`, так и блок `server_tool_use`, у которого нет блока результата. Этот вызов серверного инструмента ещё не завершён, и его блок результата придёт в более позднем ответе. Ответьте сообщением пользователя, содержащим только блоки `tool_result` для клиентских инструментов, и сохраните тот же массив `tools`; для серверного инструмента, который Claude вызвал напрямую, API выполнит его в этом запросе, и следующий ответ начнётся с его блока результата. См. [Причины остановки и резервное поведение](https://platform.claude.com/docs/ru/build-with-claude/handling-stop-reasons#tool-use).
**Отличия от других API**
В отличие от API, которые отделяют использование инструментов или используют специальные роли, такие как `tool` или `function`, Claude API интегрирует инструменты непосредственно в структуру сообщений `user` и `assistant`.
Сообщения содержат массивы блоков `text`, `image`, `tool_use` и `tool_result`. Сообщения `user` включают клиентский контент и `tool_result`, а сообщения `assistant` содержат сгенерированный ИИ контент и `tool_use`.
## Обработка ошибок с помощью is\_error
Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с Claude:
Если сам инструмент выдаёт ошибку во время выполнения (например, сетевая ошибка при получении данных о погоде), вы можете вернуть сообщение об ошибке в `content` вместе с `"is_error": true`:
```json JSON
{
"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 включит эту ошибку в свой ответ пользователю. Например: «Извините, мне не удалось получить текущую погоду, так как API погодного сервиса недоступен. Пожалуйста, попробуйте позже.»
Пишите информативные сообщения об ошибках. Вместо общих ошибок вроде `"failed"` указывайте, что пошло не так и что Claude следует попробовать дальше (например, `"Rate limit exceeded. Retry after 60 seconds."`). Это даёт Claude контекст, необходимый для восстановления или адаптации без догадок.
Если попытка Claude использовать инструмент недопустима (например, отсутствуют обязательные параметры), это обычно означает, что у Claude было недостаточно информации для правильного использования инструмента. Лучшее, что можно сделать во время разработки, — повторить запрос с более подробными значениями `description` в определениях ваших инструментов.
Однако вы также можете продолжить разговор с `tool_result`, указывающим на ошибку, и Claude попытается использовать инструмент снова, заполнив недостающую информацию:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
Если запрос инструмента недопустим или в нём отсутствуют параметры, Claude повторит попытку 2–3 раза с исправлениями, прежде чем извиниться перед пользователем.
Чтобы полностью исключить недопустимые вызовы инструментов, используйте [строгое использование инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/strict-tool-use) с `strict: true` в определениях ваших инструментов. Это гарантирует, что входные данные инструментов всегда будут точно соответствовать вашей схеме, предотвращая отсутствие параметров и несоответствие типов.
Когда серверные инструменты сталкиваются с ошибками (например, сетевые проблемы с Web Search), Claude прозрачно обработает эти ошибки и попытается предоставить пользователю альтернативный ответ или объяснение. В отличие от клиентских инструментов, вам не нужно обрабатывать результаты `is_error` для серверных инструментов.
Конкретно для веб-поиска возможные коды ошибок включают:
* `too_many_requests`: Превышено ограничение скорости
* `invalid_input`: Недопустимый параметр поискового запроса
* `max_uses_exceeded`: Превышено максимальное количество использований инструмента веб-поиска
* `query_too_long`: Запрос превышает максимальную длину
* `unavailable`: Произошла внутренняя ошибка
## Следующие шаги
Обрабатывайте ответы, в которых Claude вызывает несколько инструментов за один ход.
Позвольте SDK управлять циклом `tool_use`, форматированием результатов и повторными попытками за вас.
Пишите схемы и описания, которые направляют Claude к правильному инструменту.