Как работает использование инструментов
Разберитесь в цикле использования инструментов, в том, где выполняются инструменты, и в том, когда следует использовать инструменты вместо текстового ответа.
На этой странице объясняются концепции, лежащие в основе «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:
- Отправьте запрос с вашим массивом
toolsи сообщением пользователя. - Claude отвечает с
stop_reason: "tool_use"и одним или несколькими блокамиtool_use. - Выполните каждый инструмент. Оформите результаты в виде блоков
tool_result. - Отправьте новый запрос, содержащий исходные сообщения, ответ ассистента и сообщение пользователя с блоками
tool_result. - Повторяйте с шага 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, файловые системы. Использование инструментов — это мост между запросами на естественном языке и системами, которые их выполняют.
Явный признак того, что вам следует использовать инструменты: если вы пишете регулярное выражение для извлечения решения из вывода модели, это решение должно было быть вызовом инструмента. Разбор свободного текста для восстановления структурированного намерения — признак того, что структура должна находиться в схеме.
Использование инструментов не подходит, когда:
- Модель может ответить только на основе обучения. Суммаризация, перевод и вопросы на общие знания не требуют кругового обмена с инструментом.
- Взаимодействие представляет собой разовый вопрос-ответ без побочных эффектов. Если нечего запускать, инструменту нечего делать.
- Задержка вызова инструмента будет доминировать над тривиальным ответом. Каждый вызов инструмента — это как минимум один дополнительный круговой обмен; для лёгких задач накладные расходы могут превысить саму работу.
Выбор между подходами
| Подход | Когда использовать | Чего ожидать | Подробнее |
|---|---|---|---|
| Пользовательские клиентские инструменты | Пользовательская бизнес-логика, внутренние API, проприетарные данные | Вы обрабатываете выполнение и агентный цикл | Определение инструментов |
| Клиентские инструменты со схемой Anthropic | Стандартные операции разработки (bash, редактирование файлов, управление рабочим столом и браузером) | Вы обрабатываете выполнение; Claude надёжно вызывает инструмент, поскольку схема заложена при обучении | Справочник инструментов |
| Инструменты, выполняемые на сервере | Веб-поиск, песочница для кода, загрузка веб-страниц | Anthropic обрабатывает выполнение; вы читаете результаты, а не производите их | Серверные инструменты |
Следующие шаги
Создайте агента шаг за шагом — от одного вызова инструмента до продакшена.
Спецификация схемы, описания и tool_choice.
Каталог инструментов, предоставляемых Anthropic.
Эта страница была полезной?