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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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