Как реализовать использование инструментов
Руководство по реализации использования инструментов с Claude, включая выбор модели, определение инструментов и обработку результатов.
Выбор модели
Обычно используйте Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 или Claude Opus 3 для сложных инструментов и неоднозначных запросов; они лучше справляются с несколькими инструментами и при необходимости запрашивают уточнения.
Используйте Claude Haiku 3.5 или Claude Haiku 3 для простых инструментов, но учтите, что они могут выводить недостающие параметры.
Если вы используете Claude Sonnet 3.7 с использованием инструментов и расширенным мышлением, обратитесь к нашему руководству здесь для получения дополнительной информации.
Указание клиентских инструментов
Клиентские инструменты (как определенные Anthropic, так и определенные пользователем) указываются в параметре верхнего уровня tools
API-запроса. Каждое определение инструмента включает:
Параметр | Описание |
---|---|
name | Имя инструмента. Должно соответствовать регулярному выражению ^[a-zA-Z0-9_-]{1,64}$ . |
description | Подробное описание в виде обычного текста того, что делает инструмент, когда его следует использовать и как он ведет себя. |
input_schema | Объект JSON Schema, определяющий ожидаемые параметры для инструмента. |
Системный промпт для использования инструментов
Когда вы вызываете Anthropic API с параметром tools
, мы создаем специальный системный промпт из определений инструментов, конфигурации инструментов и любого пользовательского системного промпта. Созданный промпт предназначен для инструктирования модели использовать указанные инструменты и предоставления необходимого контекста для правильной работы инструмента:
Лучшие практики для определений инструментов
Чтобы получить лучшую производительность от Claude при использовании инструментов, следуйте этим рекомендациям:
- Предоставляйте крайне подробные описания. Это безусловно самый важный фактор в производительности инструментов. Ваши описания должны объяснять каждую деталь об инструменте, включая:
- Что делает инструмент
- Когда его следует использовать (и когда не следует)
- Что означает каждый параметр и как он влияет на поведение инструмента
- Любые важные предостережения или ограничения, такие как какую информацию инструмент не возвращает, если имя инструмента неясно. Чем больше контекста вы можете дать Claude о ваших инструментах, тем лучше он будет решать, когда и как их использовать. Стремитесь к минимум 3-4 предложениям на описание инструмента, больше, если инструмент сложный.
- Отдавайте приоритет описаниям над примерами. Хотя вы можете включить примеры того, как использовать инструмент в его описании или в сопроводительном промпте, это менее важно, чем наличие ясного и исчерпывающего объяснения цели и параметров инструмента. Добавляйте примеры только после того, как вы полностью проработали описание.
Хорошее описание четко объясняет, что делает инструмент, когда его использовать, какие данные он возвращает и что означает параметр ticker
. Плохое описание слишком краткое и оставляет Claude с множеством открытых вопросов о поведении и использовании инструмента.
Управление выводом Claude
Принуждение к использованию инструментов
В некоторых случаях вы можете захотеть, чтобы Claude использовал конкретный инструмент для ответа на вопрос пользователя, даже если Claude считает, что может дать ответ без использования инструмента. Вы можете сделать это, указав инструмент в поле tool_choice
следующим образом:
При работе с параметром tool_choice у нас есть четыре возможных варианта:
auto
позволяет Claude решать, вызывать ли любые предоставленные инструменты или нет. Это значение по умолчанию, когда предоставленыtools
.any
говорит Claude, что он должен использовать один из предоставленных инструментов, но не принуждает к конкретному инструменту.tool
позволяет нам принудить Claude всегда использовать конкретный инструмент.none
предотвращает использование Claude любых инструментов. Это значение по умолчанию, когдаtools
не предоставлены.
При использовании кэширования промптов, изменения в параметре tool_choice
аннулируют кэшированные блоки сообщений. Определения инструментов и системные промпты остаются кэшированными, но содержимое сообщений должно быть переобработано.
Эта диаграмма иллюстрирует, как работает каждый вариант:
Обратите внимание, что когда у вас tool_choice
как any
или tool
, мы предварительно заполним сообщение ассистента, чтобы принудить к использованию инструмента. Это означает, что модели не будут выдавать блок содержимого text
с цепочкой рассуждений перед блоками содержимого tool_use
, даже если явно попросить об этом.
При использовании расширенного мышления с использованием инструментов, tool_choice: {"type": "any"}
и tool_choice: {"type": "tool", "name": "..."}
не поддерживаются и приведут к ошибке. Только tool_choice: {"type": "auto"}
(по умолчанию) и tool_choice: {"type": "none"}
совместимы с расширенным мышлением.
Наше тестирование показало, что это не должно снижать производительность. Если вы хотите сохранить цепочку рассуждений (особенно с Opus), при этом все еще запрашивая, чтобы модель использовала конкретный инструмент, вы можете использовать {"type": "auto"}
для tool_choice
(по умолчанию) и добавить явные инструкции в сообщение user
. Например: Какая погода в Лондоне? Используйте инструмент get_weather в своем ответе.
Вывод JSON
Инструменты не обязательно должны быть клиентскими функциями — вы можете использовать инструменты в любое время, когда хотите, чтобы модель возвращала вывод JSON, который следует предоставленной схеме. Например, вы можете использовать инструмент record_summary
с конкретной схемой. См. Использование инструментов с Claude для полного рабочего примера.
Цепочка рассуждений
При использовании инструментов Claude часто будет показывать свою “цепочку рассуждений”, то есть пошаговое рассуждение, которое он использует для разбора проблемы и решения, какие инструменты использовать. Модель Claude Opus 3 будет делать это, если tool_choice
установлен в auto
(это значение по умолчанию, см. Принуждение к использованию инструментов), а Sonnet и Haiku можно побудить к этому.
Например, при запросе “Какая погода в Сан-Франциско прямо сейчас, и который там час?”, Claude может ответить:
Эта цепочка рассуждений дает понимание процесса рассуждения Claude и может помочь вам отладить неожиданное поведение.
С моделью Claude Sonnet 3 цепочка рассуждений менее распространена по умолчанию, но вы можете побудить Claude показать свое рассуждение, добавив что-то вроде "Перед ответом объясните свое рассуждение пошагово в тегах."
к пользовательскому сообщению или системному промпту.
Важно отметить, что хотя теги <thinking>
являются общепринятой конвенцией, которую Claude использует для обозначения своей цепочки рассуждений, точный формат (например, как называется этот XML-тег) может изменяться со временем. Ваш код должен обрабатывать цепочку рассуждений как любой другой текст, сгенерированный ассистентом, и не полагаться на наличие или конкретное форматирование тегов <thinking>
.
Параллельное использование инструментов
По умолчанию Claude может использовать несколько инструментов для ответа на пользовательский запрос. Вы можете отключить это поведение:
- Установив
disable_parallel_tool_use=true
, когда тип tool_choice равенauto
, что гарантирует, что Claude использует максимум один инструмент - Установив
disable_parallel_tool_use=true
, когда тип tool_choice равенany
илиtool
, что гарантирует, что Claude использует точно один инструмент
Максимизация параллельного использования инструментов
Хотя модели Claude 4 имеют отличные возможности параллельного использования инструментов по умолчанию, вы можете увеличить вероятность параллельного выполнения инструментов во всех моделях с помощью целевого промптинга:
Параллельное использование инструментов с Claude Sonnet 3.7
Claude Sonnet 3.7 может быть менее склонен к выполнению параллельных вызовов инструментов в ответе, даже когда вы не установили disable_parallel_tool_use
. Чтобы обойти это, мы рекомендуем включить токен-эффективное использование инструментов, что помогает поощрить Claude использовать параллельные инструменты. Эта бета-функция также снижает задержку и экономит в среднем 14% выходных токенов.
Если вы предпочитаете не подключаться к бета-версии токен-эффективного использования инструментов, вы также можете ввести “пакетный инструмент”, который может действовать как мета-инструмент для обертывания вызовов других инструментов одновременно. Мы обнаружили, что если этот инструмент присутствует, модель будет использовать его для одновременного вызова нескольких инструментов параллельно для вас.
См. этот пример в нашей кулинарной книге о том, как использовать этот обходной путь.
Обработка блоков содержимого использования инструментов и результатов инструментов
Ответ Claude отличается в зависимости от того, использует ли он клиентский или серверный инструмент.
Обработка результатов от клиентских инструментов
Ответ будет иметь stop_reason
равный tool_use
и один или несколько блоков содержимого tool_use
, которые включают:
id
: Уникальный идентификатор для этого конкретного блока использования инструмента. Он будет использоваться для сопоставления результатов инструмента позже.name
: Имя используемого инструмента.input
: Объект, содержащий входные данные, передаваемые инструменту, соответствующиеinput_schema
инструмента.
Когда вы получаете ответ об использовании инструмента для клиентского инструмента, вы должны:
- Извлечь
name
,id
иinput
из блокаtool_use
. - Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав
input
инструмента. - Продолжить разговор, отправив новое сообщение с
role
равнымuser
и блокомcontent
, содержащим типtool_result
и следующую информацию:tool_use_id
:id
запроса на использование инструмента, для которого это результат.content
: Результат инструмента в виде строки (например,"content": "15 градусов"
) или списка вложенных блоков содержимого (например,"content": [{"type": "text", "text": "15 градусов"}]
). Эти блоки содержимого могут использовать типыtext
илиimage
.is_error
(необязательно): Установите вtrue
, если выполнение инструмента привело к ошибке.
Важные требования к форматированию:
- Блоки результатов инструментов должны немедленно следовать за соответствующими блоками использования инструментов в истории сообщений. Вы не можете включать никаких сообщений между сообщением об использовании инструмента ассистента и сообщением с результатом инструмента пользователя.
- В пользовательском сообщении, содержащем результаты инструментов, блоки tool_result должны идти ПЕРВЫМИ в массиве содержимого. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
Например, это вызовет ошибку 400:
Это правильно:
Если вы получаете ошибку типа “tool_use ids were found without tool_result blocks immediately after”, проверьте, что ваши результаты инструментов отформатированы правильно.
После получения результата инструмента Claude будет использовать эту информацию для продолжения генерации ответа на исходный пользовательский промпт.
Обработка результатов от серверных инструментов
Claude выполняет инструмент внутренне и включает результаты непосредственно в свой ответ без требования дополнительного взаимодействия с пользователем.
Отличия от других API
В отличие от API, которые разделяют использование инструментов или используют специальные роли, такие как tool
или function
, API Anthropic интегрирует инструменты непосредственно в структуру сообщений user
и assistant
.
Сообщения содержат массивы блоков text
, image
, tool_use
и tool_result
. Сообщения user
включают клиентское содержимое и tool_result
, в то время как сообщения assistant
содержат содержимое, сгенер
Обработка причины остановки max_tokens
Если ответ Claude обрезан из-за достижения лимита max_tokens
, и обрезанный ответ содержит неполный блок использования инструмента, вам нужно будет повторить запрос с более высоким значением max_tokens
, чтобы получить полное использование инструмента.
Обработка причины остановки pause_turn
При использовании серверных инструментов, таких как веб-поиск, API может вернуть причину остановки pause_turn
, указывающую, что API приостановил долго выполняющийся ход.
Вот как обработать причину остановки pause_turn
:
При обработке pause_turn
:
- Продолжите разговор: Передайте приостановленный ответ как есть в последующем запросе, чтобы позволить Claude продолжить свой ход
- Измените при необходимости: Вы можете опционально изменить содержимое перед продолжением, если хотите прервать или перенаправить разговор
- Сохраните состояние инструмента: Включите те же инструменты в запрос на продолжение для поддержания функциональности
Устранение ошибок
Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с Claude: