Выбор модели
Мы рекомендуем использовать последнюю модель Claude Sonnet (4.5) или Claude Opus (4.1) для сложных инструментов и неоднозначных запросов; они лучше справляются с несколькими инструментами и запрашивают уточнения при необходимости. Используйте модели Claude Haiku для простых инструментов, но имейте в виду, что они могут выводить отсутствующие параметры.Указание клиентских инструментов
Клиентские инструменты (как определённые Anthropic, так и определённые пользователем) указываются в параметреtools верхнего уровня запроса API. Каждое определение инструмента включает:
| Параметр | Описание |
|---|---|
name | Имя инструмента. Должно соответствовать регулярному выражению ^[a-zA-Z0-9_-]{1,64}$. |
description | Подробное описание на простом языке того, что делает инструмент, когда его следует использовать и как он себя ведёт. |
input_schema | Объект JSON Schema, определяющий ожидаемые параметры для инструмента. |
Пример простого определения инструмента
Пример простого определения инструмента
get_weather ожидает входной объект с обязательной строкой location и необязательной строкой unit, которая должна быть либо “celsius”, либо “fahrenheit”.Системный запрос для использования инструментов
Когда вы вызываете API Claude с параметромtools, мы создаём специальный системный запрос из определений инструментов, конфигурации инструментов и любого указанного пользователем системного запроса. Созданный запрос предназначен для инструктирования модели использовать указанный инструмент (инструменты) и предоставить необходимый контекст для правильной работы инструмента:
Лучшие практики для определений инструментов
Чтобы получить лучшую производительность от Claude при использовании инструментов, следуйте этим рекомендациям:- Предоставляйте чрезвычайно подробные описания. Это, безусловно, наиболее важный фактор в производительности инструмента. Ваши описания должны объяснять каждую деталь инструмента, включая:
- Что делает инструмент
- Когда его следует использовать (и когда не следует)
- Что означает каждый параметр и как он влияет на поведение инструмента
- Любые важные предостережения или ограничения, такие как информация, которую инструмент не возвращает, если имя инструмента неясно. Чем больше контекста вы можете дать Claude о ваших инструментах, тем лучше он будет решать, когда и как их использовать. Стремитесь к минимум 3-4 предложениям на описание инструмента, больше, если инструмент сложный.
- Приоритизируйте описания над примерами. Хотя вы можете включить примеры использования инструмента в его описание или в сопровождающий запрос, это менее важно, чем наличие чёткого и полного объяснения назначения и параметров инструмента. Добавляйте примеры только после того, как вы полностью разработали описание.
Пример хорошего описания инструмента
Пример хорошего описания инструмента
Пример плохого описания инструмента
Пример плохого описания инструмента
ticker. Плохое описание слишком краткое и оставляет Claude с множеством открытых вопросов о поведении и использовании инструмента.
Средство запуска инструментов (бета)
Средство запуска инструментов предоставляет готовое решение для выполнения инструментов с Claude. Вместо ручной обработки вызовов инструментов, результатов инструментов и управления беседой, средство запуска инструментов автоматически:- Выполняет инструменты, когда Claude их вызывает
- Обрабатывает цикл запроса/ответа
- Управляет состоянием беседы
- Обеспечивает безопасность типов и валидацию
Базовое использование
@beta_tool для определения инструментов и client.beta.messages.tool_runner() для их выполнения.@beta_tool на @beta_async_tool и определите функцию с async def.@beta_tool будет проверять аргументы функции и строку документации для извлечения представления json schema данной функции, в приведённом выше примере calculate_sum будет преобразован в:Управление выводом Claude
Принудительное использование инструментов
В некоторых случаях вы можете захотеть, чтобы Claude использовал конкретный инструмент для ответа на вопрос пользователя, даже если Claude думает, что может предоставить ответ без использования инструмента. Вы можете сделать это, указав инструмент в полеtool_choice следующим образом:
autoпозволяет Claude решить, вызывать ли какие-либо предоставленные инструменты или нет. Это значение по умолчанию, когда предоставленыtools.anyговорит Claude, что он должен использовать один из предоставленных инструментов, но не принуждает к использованию конкретного инструмента.toolпозволяет нам принудить Claude всегда использовать конкретный инструмент.noneпредотвращает использование Claude любых инструментов. Это значение по умолчанию, когдаtoolsне предоставлены.
tool_choice будут инвалидировать кэшированные блоки сообщений. Определения инструментов и системные запросы остаются кэшированными, но содержимое сообщения должно быть переобработано.
tool_choice как any или tool, мы предварительно заполним сообщение помощника, чтобы принудить использование инструмента. Это означает, что модели не будут выдавать естественный языковой ответ или объяснение перед блоками содержимого tool_use, даже если об этом явно попросить.
tool_choice: {"type": "any"} и tool_choice: {"type": "tool", "name": "..."} не поддерживаются и приведут к ошибке. Совместимы только tool_choice: {"type": "auto"} (по умолчанию) и tool_choice: {"type": "none"}.{"type": "auto"} для tool_choice (по умолчанию) и добавить явные инструкции в сообщение user. Например: What's the weather like in London? Use the get_weather tool in your response.
Вывод JSON
Инструменты не обязательно должны быть клиентскими функциями — вы можете использовать инструменты в любое время, когда хотите, чтобы модель возвращала вывод JSON, который следует предоставленной схеме. Например, вы можете использовать инструментrecord_summary с определённой схемой. См. Использование инструментов с Claude для полного рабочего примера.
Ответы модели с инструментами
При использовании инструментов Claude часто комментирует то, что он делает, или естественно отвечает пользователю перед вызовом инструментов. Например, при наличии запроса “What’s the weather like in San Francisco right now, and what time is it there?”, Claude может ответить:<examples> в ваших запросах.
Важно отметить, что Claude может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен рассматривать эти ответы как любой другой текст, сгенерированный помощником, и не полагаться на определённые соглашения форматирования.
Параллельное использование инструментов
По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение, выполнив следующие действия:- Установка
disable_parallel_tool_use=trueкогда тип tool_choice являетсяauto, что гарантирует, что Claude использует максимум один инструмент - Установка
disable_parallel_tool_use=trueкогда тип tool_choice являетсяanyилиtool, что гарантирует, что Claude использует ровно один инструмент
Полный пример параллельного использования инструментов
Полный пример параллельного использования инструментов
Полный тестовый скрипт для параллельных инструментов
Полный тестовый скрипт для параллельных инструментов
- Как правильно форматировать параллельные вызовы инструментов и результаты
- Как проверить, что параллельные вызовы выполняются
- Правильную структуру сообщений, которая способствует будущему параллельному использованию инструментов
- Распространённые ошибки, которых следует избегать (например, текст перед результатами инструментов)
Максимизация параллельного использования инструментов
Хотя модели Claude 4 имеют отличные возможности параллельного использования инструментов по умолчанию, вы можете увеличить вероятность параллельного выполнения инструментов во всех моделях с помощью целевого запроса:Системные запросы для параллельного использования инструментов
Системные запросы для параллельного использования инструментов
Запрос пользовательского сообщения
Запрос пользовательского сообщения
disable_parallel_tool_use. Чтобы обойти это, мы рекомендуем включить эффективное использование инструментов по токенам, что помогает поощрять Claude использовать параллельные инструменты. Эта бета-функция также снижает задержку и экономит в среднем 14% выходных токенов.Если вы предпочитаете не использовать бета-версию эффективного использования инструментов по токенам, вы также можете ввести “пакетный инструмент”, который может действовать как мета-инструмент для обёртывания вызовов других инструментов одновременно. Мы обнаружили, что если этот инструмент присутствует, модель будет использовать его для одновременного вызова нескольких инструментов параллельно для вас.См. этот пример в нашей кулинарной книге для того, как использовать этот обходной путь.Обработка блоков содержимого использования инструментов и результатов инструментов
Обработка результатов от клиентских инструментов
Ответ будет иметьstop_reason из tool_use и один или несколько блоков содержимого tool_use, которые включают:
id: Уникальный идентификатор для этого конкретного блока использования инструмента. Это будет использоваться для сопоставления результатов инструмента позже.name: Имя используемого инструмента.input: Объект, содержащий входные данные, передаваемые инструменту, соответствующиеinput_schemaинструмента.
Пример ответа API с блоком содержимого `tool_use`
Пример ответа API с блоком содержимого `tool_use`
- Извлечь
name,idиinputиз блокаtool_use. - Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав входные данные инструмента.
- Продолжить беседу, отправив новое сообщение с
roleизuserи блокомcontent, содержащим типtool_resultи следующую информацию:tool_use_id:idзапроса использования инструмента, для которого это результат.content: Результат инструмента, как строка (например,"content": "15 degrees"), список вложенных блоков содержимого (например,"content": [{"type": "text", "text": "15 degrees"}]) или список блоков документов (например,"content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Эти блоки содержимого могут использовать типыtext,imageилиdocument.is_error(необязательно): Установите значениеtrue, если выполнение инструмента привело к ошибке.
- Блоки результатов инструментов должны немедленно следовать за соответствующими блоками использования инструментов в истории сообщений. Вы не можете включать какие-либо сообщения между сообщением использования инструмента помощника и сообщением результата инструмента пользователя.
- В пользовательском сообщении, содержащем результаты инструментов, блоки tool_result должны идти ПЕРВЫМИ в массиве содержимого. Любой текст должен идти ПОСЛЕ всех результатов инструментов.
Пример успешного результата инструмента
Пример успешного результата инструмента
Пример результата инструмента с изображениями
Пример результата инструмента с изображениями
Пример пустого результата инструмента
Пример пустого результата инструмента
Пример результата инструмента с документами
Пример результата инструмента с документами
Обработка результатов от серверных инструментов
Claude выполняет инструмент внутри и включает результаты непосредственно в свой ответ без необходимости дополнительного взаимодействия с пользователем.tool или function, API Claude интегрирует инструменты непосредственно в структуру сообщений user и assistant.Сообщения содержат массивы блоков text, image, tool_use и tool_result. Сообщения user включают содержимое клиента и tool_result, а сообщения assistant содержат содержимое, сгенерированное AI, и tool_use.Обработка причины остановки max_tokens
Если ответ Claude обрезан из-за достижения лимита max_tokens, и обрезанный ответ содержит неполный блок использования инструмента, вам нужно будет повторить запрос с более высоким значением max_tokens, чтобы получить полное использование инструмента.
Обработка причины остановки pause_turn
При использовании серверных инструментов, таких как веб-поиск, API может вернуть причину остановки pause_turn, указывающую, что API приостановил долгоживущий ход.
Вот как обработать причину остановки pause_turn:
pause_turn:
- Продолжите беседу: Передайте приостановленный ответ как есть в последующем запросе, чтобы позволить Claude продолжить свой ход
- Измените при необходимости: Вы можете опционально изменить содержимое перед продолжением, если хотите прервать или перенаправить беседу
- Сохраните состояние инструмента: Включите те же инструменты в запрос продолжения, чтобы сохранить функциональность
Устранение неполадок ошибок
Ошибка выполнения инструмента
Ошибка выполнения инструмента
content вместе с "is_error": true:Неверное имя инструмента
Неверное имя инструмента
description в определениях инструментов.Однако вы также можете продолжить беседу вперёд с tool_result, который указывает на ошибку, и Claude попытается использовать инструмент снова с заполненной отсутствующей информацией:Теги <search_quality_reflection>
Теги <search_quality_reflection>
Ошибки серверных инструментов
Ошибки серверных инструментов
is_error для серверных инструментов.Для веб-поиска в частности, возможные коды ошибок включают:too_many_requests: Превышен лимит скоростиinvalid_input: Неверный параметр поискового запросаmax_uses_exceeded: Превышено максимальное количество использований инструмента веб-поискаquery_too_long: Запрос превышает максимальную длинуunavailable: Произошла внутренняя ошибка
Параллельные вызовы инструментов не работают
Параллельные вызовы инструментов не работают
- ❌ Неправильно: Отправка отдельных пользовательских сообщений для каждого результата инструмента
- ✅ Правильно: Все результаты инструментов должны быть в одном пользовательском сообщении
- Claude Opus 4.1, Opus 4 и Sonnet 4: Отлично справляются с параллельным использованием инструментов с минимальным запросом
- Claude Sonnet 3.7: Может потребоваться более сильный запрос или эффективное использование инструментов по токенам
- Claude Haiku: Менее вероятно использовать параллельные инструменты без явного запроса