--- title: Как работает использование инструментов url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/how-tool-use-works description: Разберитесь в цикле использования инструментов, в том, где выполняются инструменты и когда следует использовать инструменты вместо прозы. --- На этой странице объясняются концепции, лежащие в основе «tool use» (использования инструментов): где выполняются инструменты, как работает агентный цикл и когда использование инструментов является правильным подходом. Для практического руководства начните с учебного пособия [Создание агента, использующего инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/build-a-tool-using-agent) или руководства [Определение инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools). ## Контракт использования инструментов Использование инструментов — это контракт между вашим приложением и моделью. Вы указываете, какие операции доступны и какую форму имеют их входные и выходные данные; Claude определяет, когда и как их вызывать. Модель никогда ничего не выполняет самостоятельно. Она выдаёт структурированный запрос, ваш код (или серверы Anthropic) выполняет операцию, а результат возвращается обратно в разговор. Этот контракт заставляет модель вести себя не столько как генератор текста, сколько как функция, которую вы вызываете. Инженеры с опытом работы с классическими API могут интегрировать использование инструментов так же, как любой другой типизированный интерфейс: определить схему, обработать обратный вызов, вернуть результат. Разница в том, что вызывающая сторона на другом конце — это языковая модель, выбирающая, какую функцию вызвать, исходя из разговора. ## Где выполняются инструменты Основная ось, по которой различаются инструменты, — это место выполнения кода. Каждый инструмент попадает в одну из трёх категорий, и категория определяет, за что отвечает ваше приложение. ### Пользовательские инструменты (выполняются на клиенте) Вы пишете схему, вы выполняете код, вы возвращаете результаты. Это самый распространённый случай: подавляющая часть трафика использования инструментов — это [пользовательские инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools), вызывающие логику, специфичную для приложения. Когда Claude вызывает один из ваших инструментов, ответ API содержит блок `tool_use` с именем инструмента и JSON-объектом аргументов. Ваше приложение извлекает эти аргументы, выполняет операцию (запрос к базе данных, HTTP-вызов, запись в файл — всё, что делает инструмент) и отправляет вывод обратно в блоке `tool_result` в следующем запросе. Claude никогда не видит вашу реализацию; он видит только предоставленную вами схему и возвращённый вами результат. ### Инструменты со схемой Anthropic (выполняются на клиенте) Для нескольких распространённых операций (управление черновой памятью, выполнение команд оболочки, редактирование файлов, управление рабочим столом или браузером) Anthropic публикует схему инструмента, а ваше приложение обрабатывает выполнение. Инструменты в этой категории: [`memory`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool), [`bash`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/bash-tool), [`text_editor`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/text-editor-tool), [`computer`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/computer-use-tool) и [`browser`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/browser-use-tool). Модель выполнения идентична пользовательским инструментам: ответ содержит блок `tool_use`, ваш код выполняет операцию, и вы отправляете обратно `tool_result`. Причина использовать инструмент со схемой Anthropic вместо определения собственного эквивалента в том, что эти схемы заложены при обучении. Claude был оптимизирован на тысячах успешных траекторий, использующих именно эти сигнатуры инструментов, поэтому он вызывает их надёжнее и восстанавливается после ошибок изящнее, чем с пользовательским инструментом, делающим то же самое. Схема — это интерфейс, который модель уже ожидает. ### Инструменты, выполняемые на сервере Для [`web_search`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/web-search-tool), [`web_fetch`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/web-fetch-tool), [`code_execution`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool) и [`tool_search`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool) код выполняет Anthropic. Вы включаете инструмент в своём запросе, а сервер обрабатывает всё остальное. Вы никогда не формируете блок `tool_result` для этих инструментов. Когда ход вызывает только [серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools), серверный цикл выполняет операцию и передаёт вывод обратно модели до того, как ответ дойдёт до вас, — если только цикл не остановится до завершения, чаще всего из-за приостановки. Полученный вами ответ содержит блоки `server_tool_use`, показывающие, что было выполнено и что вернулось. В типичном случае выполнение уже завершено к тому моменту, когда вы их видите, и задача вашего приложения — включить инструмент и прочитать окончательный ответ, а не участвовать в цикле выполнения; основные исключения — приостановленный цикл ([`pause_turn`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/how-tool-use-works#the-server-side-loop)) и ход, который также вызывает клиентский инструмент. ## Агентный цикл (клиентские инструменты) Инструменты, выполняемые на клиенте (как пользовательские, так и со схемой Anthropic), требуют, чтобы ваше приложение управляло циклом. Модель не может выполнять ваш код, поэтому каждый вызов инструмента — это круговой обмен: модель запрашивает, вы выполняете, вы сообщаете результат, модель продолжает. Каноническая форма — цикл `while`, завязанный на `stop_reason`: 1. Отправьте запрос с вашим массивом `tools` и сообщением пользователя. 2. Claude отвечает с `stop_reason: "tool_use"` и одним или несколькими блоками `tool_use`. 3. Выполните каждый инструмент. Оформите выводы как блоки `tool_result`. 4. Отправьте новый запрос, содержащий исходные сообщения, ответ ассистента и сообщение пользователя с блоками `tool_result`. 5. Повторяйте с шага 2, пока `stop_reason` равен `"tool_use"`. На практике это читается так: пока `stop_reason == "tool_use"`, выполняйте инструменты и продолжайте разговор. Цикл завершается при любой другой причине остановки (`"end_turn"`, `"max_tokens"`, `"stop_sequence"` или `"refusal"`), что означает, что Claude либо выдал окончательный ответ, либо остановился по другой причине, которую ваше приложение должно обработать. О механике построения запросов, обработке параллельных вызовов инструментов и форматировании результатов см. [Обработка вызовов инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls). ## Серверный цикл Инструменты, выполняемые на сервере, запускают собственный цикл внутри инфраструктуры Anthropic. Один запрос от вашего приложения может вызвать несколько веб-поисков или выполнений кода, прежде чем вернётся ответ. Модель ищет, читает результаты, определяет, нужно ли искать снова, и повторяет итерации, пока не получит то, что ей нужно, — всё это без участия вашего приложения. У этого внутреннего цикла есть лимит итераций. Если модель всё ещё выполняет итерации, когда достигает предела, ответ возвращается с `stop_reason: "pause_turn"` вместо `"end_turn"`. Приостановленный ход означает, что работа не завершена; повторно отправьте разговор (включая приостановленный ответ), чтобы модель продолжила с того места, где остановилась. Шаблон продолжения см. в разделе [Серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools). Цикл также возвращает управление вам до запуска серверного инструмента, если Claude вызывает этот серверный инструмент и клиентский инструмент в одной группе параллельных вызовов инструментов. Тогда ответ возвращается с `stop_reason: "tool_use"` и блоком `server_tool_use`, у которого ещё нет блока результата; API выполнит его после того, как вы вернёте результаты клиентского инструмента. Точный контракт см. в разделе [Причины остановки и резервное поведение](https://platform.claude.com/docs/ru/build-with-claude/handling-stop-reasons#tool-use). ## Когда использовать инструменты (а когда нет) Использование инструментов подходит, когда задача требует чего-то, что модель не может сделать только на основе текста: * **Действия с побочными эффектами.** Отправка электронного письма, запись файла, обновление записи. Модель может описать эти действия, но выполнить их может только инструмент. * **Свежие или внешние данные.** Текущие цены, сегодняшняя погода, содержимое базы данных. Всё, что находится за пределами обучающих данных или специфично для вашей системы, требует инструмента для получения. * **Структурированные выводы гарантированной формы.** Когда вам нужен JSON-объект с конкретными полями, а не проза, которая случайно содержит нужную информацию, схема инструмента обеспечивает соблюдение формы. * **Обращение к существующим системам.** Базы данных, внутренние API, файловые системы. Использование инструментов — это мост между запросами на естественном языке и системами, которые их выполняют. Явный признак того, что вам следует использовать инструменты: если вы пишете регулярное выражение для извлечения решения из вывода модели, это решение должно было быть вызовом инструмента. Разбор свободного текста для восстановления структурированного намерения — признак того, что структура должна находиться в схеме. Использование инструментов не подходит, когда: * Модель может ответить только на основе обучения. Суммаризация, перевод и вопросы на общие знания не требуют кругового обмена с инструментом. * Взаимодействие представляет собой одноразовый вопрос-ответ без побочных эффектов. Если нечего выполнять, инструменту нечего делать. * Задержка вызова инструмента будет доминировать над тривиальным ответом. Каждый вызов инструмента — это как минимум один дополнительный круговой обмен; для лёгких задач накладные расходы могут превысить саму работу. ## Выбор между подходами | Подход | Когда использовать | Чего ожидать | Подробнее | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | Пользовательские клиентские инструменты | Пользовательская бизнес-логика, внутренние API, проприетарные данные | Вы обрабатываете выполнение и агентный цикл | [Определение инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools) | | Клиентские инструменты со схемой Anthropic | Стандартные операции разработки (bash, редактирование файлов, управление рабочим столом и браузером) | Вы обрабатываете выполнение; Claude надёжно вызывает инструмент, поскольку схема заложена при обучении | [Справочник инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference) | | Инструменты, выполняемые на сервере | Веб-поиск, песочница для кода, загрузка веб-страниц | Anthropic обрабатывает выполнение; вы читаете результаты, а не производите их | [Серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) | ## Следующие шаги Создайте агента шаг за шагом — от одного вызова инструмента до продакшена. Спецификация схемы, описания и `tool_choice`. Каталог инструментов, предоставляемых Anthropic.