MessagesИнструменты

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

Copy page



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

На этой странице объясняются концепции, лежащие в основе «tool use» (использования инструментов): где выполняются инструменты, как работает агентный цикл и когда использование инструментов является правильным подходом. Для практического руководства начните с учебного пособия Создание агента, использующего инструменты или руководства Определение инструментов.

Контракт использования инструментов

Использование инструментов — это контракт между вашим приложением и моделью. Вы указываете, какие операции доступны и какую форму имеют их входные и выходные данные; Claude определяет, когда и как их вызывать. Модель никогда ничего не выполняет самостоятельно. Она выдаёт структурированный запрос, ваш код (или серверы Anthropic) выполняет операцию, а результат возвращается обратно в разговор.

Этот контракт заставляет модель вести себя не столько как генератор текста, сколько как функция, которую вы вызываете. Инженеры с опытом работы с классическими API могут интегрировать использование инструментов так же, как любой другой типизированный интерфейс: определить схему, обработать обратный вызов, вернуть результат. Разница в том, что вызывающая сторона на другом конце — это языковая модель, выбирающая, какую функцию вызвать, исходя из разговора.

Где выполняются инструменты

Основная ось, по которой различаются инструменты, — это место выполнения кода. Каждый инструмент попадает в одну из трёх категорий, и категория определяет, за что отвечает ваше приложение.

Пользовательские инструменты (выполняются на клиенте)

Вы пишете схему, вы выполняете код, вы возвращаете результаты. Это самый распространённый случай: подавляющая часть трафика использования инструментов — это пользовательские инструменты, вызывающие логику, специфичную для приложения.

Когда Claude вызывает один из ваших инструментов, ответ API содержит блок tool_use с именем инструмента и JSON-объектом аргументов. Ваше приложение извлекает эти аргументы, выполняет операцию (запрос к базе данных, HTTP-вызов, запись в файл — всё, что делает инструмент) и отправляет вывод обратно в блоке tool_result в следующем запросе. Claude никогда не видит вашу реализацию; он видит только предоставленную вами схему и возвращённый вами результат.

Инструменты со схемой Anthropic (выполняются на клиенте)

Для нескольких распространённых операций (управление черновой памятью, выполнение команд оболочки, редактирование файлов, управление рабочим столом или браузером) Anthropic публикует схему инструмента, а ваше приложение обрабатывает выполнение. Инструменты в этой категории: memory, bash, text_editor, computer и browser.

Модель выполнения идентична пользовательским инструментам: ответ содержит блок tool_use, ваш код выполняет операцию, и вы отправляете обратно tool_result. Причина использовать инструмент со схемой Anthropic вместо определения собственного эквивалента в том, что эти схемы заложены при обучении. Claude был оптимизирован на тысячах успешных траекторий, использующих именно эти сигнатуры инструментов, поэтому он вызывает их надёжнее и восстанавливается после ошибок изящнее, чем с пользовательским инструментом, делающим то же самое. Схема — это интерфейс, который модель уже ожидает.

Инструменты, выполняемые на сервере

Для web_search, web_fetch, code_execution и tool_search код выполняет Anthropic. Вы включаете инструмент в своём запросе, а сервер обрабатывает всё остальное. Вы никогда не формируете блок tool_result для этих инструментов. Когда ход вызывает только серверные инструменты, серверный цикл выполняет операцию и передаёт вывод обратно модели до того, как ответ дойдёт до вас, — если только цикл не остановится до завершения, чаще всего из-за приостановки.

Полученный вами ответ содержит блоки server_tool_use, показывающие, что было выполнено и что вернулось. В типичном случае выполнение уже завершено к тому моменту, когда вы их видите, и задача вашего приложения — включить инструмент и прочитать окончательный ответ, а не участвовать в цикле выполнения; основные исключения — приостановленный цикл (pause_turn) и ход, который также вызывает клиентский инструмент.

Агентный цикл (клиентские инструменты)

Инструменты, выполняемые на клиенте (как пользовательские, так и со схемой 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 либо выдал окончательный ответ, либо остановился по другой причине, которую ваше приложение должно обработать.

О механике построения запросов, обработке параллельных вызовов инструментов и форматировании результатов см. Обработка вызовов инструментов.

Серверный цикл

Инструменты, выполняемые на сервере, запускают собственный цикл внутри инфраструктуры Anthropic. Один запрос от вашего приложения может вызвать несколько веб-поисков или выполнений кода, прежде чем вернётся ответ. Модель ищет, читает результаты, определяет, нужно ли искать снова, и повторяет итерации, пока не получит то, что ей нужно, — всё это без участия вашего приложения.

У этого внутреннего цикла есть лимит итераций. Если модель всё ещё выполняет итерации, когда достигает предела, ответ возвращается с stop_reason: "pause_turn" вместо "end_turn". Приостановленный ход означает, что работа не завершена; повторно отправьте разговор (включая приостановленный ответ), чтобы модель продолжила с того места, где остановилась. Шаблон продолжения см. в разделе Серверные инструменты.

Цикл также возвращает управление вам до запуска серверного инструмента, если Claude вызывает этот серверный инструмент и клиентский инструмент в одной группе параллельных вызовов инструментов. Тогда ответ возвращается с stop_reason: "tool_use" и блоком server_tool_use, у которого ещё нет блока результата; API выполнит его после того, как вы вернёте результаты клиентского инструмента. Точный контракт см. в разделе Причины остановки и резервное поведение.

Когда использовать инструменты (а когда нет)

Использование инструментов подходит, когда задача требует чего-то, что модель не может сделать только на основе текста:

• Действия с побочными эффектами. Отправка электронного письма, запись файла, обновление записи. Модель может описать эти действия, но выполнить их может только инструмент.
• Свежие или внешние данные. Текущие цены, сегодняшняя погода, содержимое базы данных. Всё, что находится за пределами обучающих данных или специфично для вашей системы, требует инструмента для получения.
• Структурированные выводы гарантированной формы. Когда вам нужен JSON-объект с конкретными полями, а не проза, которая случайно содержит нужную информацию, схема инструмента обеспечивает соблюдение формы.
• Обращение к существующим системам. Базы данных, внутренние API, файловые системы. Использование инструментов — это мост между запросами на естественном языке и системами, которые их выполняют.

Явный признак того, что вам следует использовать инструменты: если вы пишете регулярное выражение для извлечения решения из вывода модели, это решение должно было быть вызовом инструмента. Разбор свободного текста для восстановления структурированного намерения — признак того, что структура должна находиться в схеме.

Использование инструментов не подходит, когда:

• Модель может ответить только на основе обучения. Суммаризация, перевод и вопросы на общие знания не требуют кругового обмена с инструментом.
• Взаимодействие представляет собой одноразовый вопрос-ответ без побочных эффектов. Если нечего выполнять, инструменту нечего делать.
• Задержка вызова инструмента будет доминировать над тривиальным ответом. Каждый вызов инструмента — это как минимум один дополнительный круговой обмен; для лёгких задач накладные расходы могут превысить саму работу.

Выбор между подходами

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