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

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



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

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

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



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

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



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

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

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



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

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

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

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

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

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



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



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