---
title: Обработка вызовов инструментов
url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls
description: Разбор блоков tool_use, форматирование ответов tool_result и обработка ошибок с помощью is_error.
---

Когда ответ Claude содержит блоки `tool_use`, ваш код запускает каждый инструмент и отправляет обратно блоки `tool_result`, включая любые ошибки. Пишите этот код самостоятельно, когда вам нужен собственный контроль над выполнением инструментов. В противном случае используйте [исполнитель инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner) SDK, который запускает инструменты и отправляет результаты за вас.

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

<Accordion title="Пример ответа API с блоком содержимого `tool_use`">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

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

1. Для каждого блока `tool_use` запустите инструмент, указанный в этом блоке, передав ему его `input`.
2. В новом запросе сохраните предыдущие сообщения и добавьте `content` ответа без изменений в виде сообщения `assistant`.
3. Добавьте сообщение `user` с одним блоком `tool_result` для каждого блока `tool_use` в этом содержимом, даже если выполнение инструмента завершилось ошибкой.
4. Отправьте запрос с теми же `tools`, что и в первом запросе. Claude использует результаты инструментов, чтобы продолжить свой ответ.
5. Если `stop_reason` следующего ответа также равен `tool_use`, повторите эти шаги. Для других значений см. [краткий справочник по причинам остановки](https://platform.claude.com/docs/ru/build-with-claude/handling-stop-reasons#quick-reference).

Эти шаги в виде полноценных программ см. в разделе [Руководство: создание агента, использующего инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/build-a-tool-using-agent).

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

* `tool_use_id`: `id` блока `tool_use`, на который отвечает этот результат.
* `content` (необязательно): Результат инструмента в виде строки или списка блоков содержимого. Эти блоки содержимого могут использовать типы `text`, `image`, `document` или [`search_result`](https://platform.claude.com/docs/ru/build-with-claude/search-results).
* `is_error` (необязательно): Установите в `true`, если выполнение инструмента завершилось ошибкой или вызов был недопустимым.

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

```json 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`](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) возвращают только этот блок).

<Note>
  **Важные требования к форматированию:**

  * Блоки результатов инструментов должны следовать непосредственно за соответствующими блоками использования инструментов в истории сообщений. Вы не можете включать какие-либо сообщения между сообщением ассистента с использованием инструмента и сообщением пользователя с результатом инструмента.
  * В сообщении пользователя, содержащем результаты инструментов, блоки `tool_result` должны идти ПЕРВЫМИ в массиве содержимого. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
  * Если ход ассистента также вызвал [серверный инструмент](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).

  Если вы получаете ошибку вида «tool\_use ids were found without tool\_result blocks immediately after», проверьте, правильно ли отформатированы результаты ваших инструментов.
</Note>

<Warning>
  Результаты инструментов часто содержат данные из источников, которые вы не контролируете: веб-страниц, входящей электронной почты, загрузок пользователей, сторонних API. Считайте такое содержимое недоверенным: злоумышленник, способный на него повлиять, может внедрить инструкции, пытающиеся перенаправить Claude (косвенное внедрение подсказок). Храните недоверенное содержимое внутри блоков `tool_result`, а не в системных подсказках `system` или обычных пользовательских блоках `text`, и см. [Смягчение джейлбрейков и внедрения подсказок](https://platform.claude.com/docs/ru/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) для дополнительного усиления защиты.
</Warning>

<AccordionGroup>
  <Accordion title="Пример результата инструмента с изображениями">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Пример пустого результата инструмента">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Пример результата инструмента с документами">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Пример текста до и после результата инструмента">
    Например, это вызывает ошибку 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

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

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

<Note>
  Ответ может содержать как клиентский блок `tool_use`, так и блок `server_tool_use`, у которого нет блока результата. Такой вызов серверного инструмента ещё не завершён, и его блок результата придёт в одном из следующих ответов. Ответьте сообщением пользователя, содержащим только блоки `tool_result` для клиентских инструментов, и сохраните тот же массив `tools`; для серверного инструмента, который Claude вызвал напрямую, API запускает его в этом запросе, и следующий ответ начинается с его блока результата. См. [Причины остановки и резервный вариант](https://platform.claude.com/docs/ru/build-with-claude/handling-stop-reasons#tool-use).
</Note>

<Tip>
  **Отличия от других API**

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

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

## Обработка ошибок с помощью is\_error

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

<AccordionGroup>
  <Accordion title="Ошибка выполнения инструмента">
    Если сам инструмент выдаёт ошибку во время выполнения (например, сетевая ошибка при получении данных о погоде), вы можете вернуть сообщение об ошибке в `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 может снова вызвать инструмент или сообщить пользователю, что произошло. Например, Claude может сказать: «Извините, мне не удалось получить текущую погоду, так как API погодного сервиса недоступен. Пожалуйста, попробуйте позже.»

    <Tip>
      Пишите информативные сообщения об ошибках. Вместо общих ошибок, таких как `"failed"`, укажите, что пошло не так и что Claude следует попробовать дальше (например, `"Rate limit exceeded. Retry after 60 seconds."`). Это даёт Claude контекст, необходимый для восстановления или адаптации без догадок.
    </Tip>
  </Accordion>

  <Accordion title="Недопустимый вызов инструмента">
    Если попытка Claude использовать инструмент недопустима (например, отсутствуют обязательные параметры), обычно это означает, что у Claude было недостаточно информации для правильного использования инструмента. Лучший подход во время разработки — повторить запрос с более подробными значениями `description` в определениях ваших инструментов.

    Однако вы также можете продолжить диалог с `tool_result`, указывающим на ошибку:

    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "Error: Missing required 'location' parameter",
          "is_error": true
        }
      ]
    }
    ```

    Затем Claude может снова вызвать инструмент, заполнив недостающую информацию.

    <Tip>
      Чтобы полностью исключить недопустимые вызовы инструментов, используйте [строгое использование инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/strict-tool-use) с `strict: true` в определениях ваших инструментов. Это гарантирует, что входные данные инструментов всегда точно соответствуют вашей схеме, предотвращая отсутствие параметров и несоответствие типов.
    </Tip>
  </Accordion>

  <Accordion title="Ошибки серверных инструментов">
    В отличие от клиентских инструментов, для серверных инструментов вы не отправляете результаты `is_error`. Когда серверный инструмент сталкивается с ошибкой, например с сетевой проблемой при веб-поиске, API возвращает ошибку внутри блока результата инструмента. В большинстве случаев Claude затем продолжает, используя другой подход, или предоставляет пользователю объяснение.

    Коды ошибок веб-поиска см. в разделе [Ошибки инструмента веб-поиска](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

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

<CardGroup cols={3}>
  <Card title="Параллельное использование инструментов" icon="grid" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/parallel-tool-use">
    Обрабатывайте ответы, в которых Claude вызывает несколько инструментов за один ход.
  </Card>

  <Card title="Исполнитель инструментов (SDK)" icon="wrench" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner">
    Позвольте SDK управлять циклом `tool_use`, форматированием результатов и повторными попытками за вас.
  </Card>

  <Card title="Определение инструментов" icon="hammer" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools">
    Пишите схемы и описания, которые направляют Claude к правильному инструменту.
  </Card>
</CardGroup>
