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

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

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

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

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

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

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

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

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