MessagesИнструменты
Устранение неполадок при использовании инструментов
Исправьте наиболее распространённые ошибки использования инструментов с помощью диагностических таблиц «симптом — решение».
Таблицы «симптом — решение» для наиболее распространённых ошибок использования инструментов (tool use). Каждое решение содержит перекрёстную ссылку на страницу, посвящённую соответствующей функции.
Claude вызывает не тот инструмент
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Claude вызывает инструмент A, когда вам нужен был инструмент B | Неоднозначность описания | Уточните описания. Различайте инструменты по тому, КОГДА их использовать, а не только по тому, ЧТО они делают. См. Определение инструментов. |
| Claude никогда не вызывает ваш инструмент | Конфликт имён инструментов или слишком общая схема | Проверьте наличие дублирующихся имён в вашем списке инструментов. Добавьте input_examples, чтобы сделать предполагаемое использование конкретным. |
| Claude вызывает инструмент с неверными типами параметров | Модель угадывает при неоднозначной схеме | Добавьте strict: true (если ваша схема входит в поддерживаемое подмножество) или добавьте input_examples. |
Claude выдумывает параметры инструментов
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Параметр, которого нет в вашей схеме | Избыточная генерация модели без строгого режима | Добавьте strict: true, если ваша схема входит в поддерживаемое подмножество. |
| Значения параметров вне вашего enum | Отсутствие строгого режима или слишком большой enum | Сократите enum или добавьте input_examples, показывающие допустимые варианты. |
Параллельные вызовы инструментов не работают
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Claude вызывает инструменты последовательно, когда параллельный вызов был бы лучше | Форматирование истории сообщений | Отправляйте несколько блоков tool_result в ОДНОМ сообщении пользователя, а не по одному за ход. См. Параллельное использование инструментов. |
disable_parallel_tool_use, похоже, игнорируется | Установлен слишком поздно в разговоре | Должен быть установлен в запросе, который возвращает tool_use. Установка его в более позднем запросе не влияет на более ранние вызовы инструментов. |
Кэш постоянно инвалидируется
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Каждый запрос — промах кэша | tool_choice, конфигурация мышления или output_config.effort меняются между запросами | Сохраняйте tool_choice стабильным или размещайте точку останова cache_control перед точкой изменения; удерживайте конфигурацию мышления и уровень усилий постоянными на протяжении всего кэшированного разговора. См. Использование инструментов с кэшированием подсказок и Мышление и кэширование подсказок. |
| Добавление инструмента в середине разговора ломает кэш | Инструмент добавлен в начало массива tools | Используйте defer_loading: true с поиском инструментов, чтобы добавить инструмент встроенно, вместо изменения начала массива. |
Ошибки во время запроса
| Ошибка | Причина | Решение |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | Отсутствует tool_result для некоторых идентификаторов tool_use, или tool_result не является первым блоком содержимого в сообщении пользователя | Возвращайте один tool_result для каждого блока tool_use в ответе ассистента. Размещайте блоки tool_result перед любым текстом. См. Обработка вызовов инструментов и Параллельное использование инструментов. |
was found without a corresponding <name>_tool_result block | Предыдущий ход ассистента содержит блок server_tool_use без блока результата (чаще всего Claude вызвал его вместе с клиентским инструментом), и либо ваше следующее сообщение пользователя завершило этот ход (например, текстом после блоков tool_result), либо запрос на возобновление больше не определяет этот серверный инструмент (тогда сообщение заканчивается на but no <name> tool was provided) | Отправьте сообщение пользователя, содержащее только блоки tool_result для клиентских идентификаторов tool_use, и сохраните тот же массив tools. См. Причины остановки и резервное поведение. |
Unsupported regex feature in pattern field: ... | pattern в input_schema строгого инструмента использует возможность регулярных выражений, которую строгий режим не может скомпилировать, например обратную ссылку, lookaround, границу слова или большой диапазон {n,m} | Упростите шаблон. Поддерживаются якорные шаблоны с базовыми квантификаторами, классами символов и группами; см. Ограничения JSON Schema. |
All tools have defer_loading: true | Нет инструментов, видимых модели | По крайней мере один инструмент должен загружаться немедленно. Сам инструмент поиска инструментов никогда не должен иметь defer_loading: true. |
Ошибка: блоки мышления не могут быть изменены
Если запрос завершается ошибкой 400 invalid_request_error, сообщение которой содержит `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified, при продолжении разговора после вызова инструмента, значит, ваше приложение изменяет блоки мышления ассистента перед их отправкой обратно. Отправьте всё сообщение ассистента обратно без изменений, затем добавьте ваш tool_result.
См. Блоки мышления не могут быть изменены для полного описания ошибки и шагов по её устранению.
Claude помечает результаты инструментов как инъекцию подсказок
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Claude отказывается действовать на основании результата инструмента или просит пользователя подтвердить инструкции, поступившие из него | Ваши собственные инструкции доставляются внутри содержимого tool_result | Claude обучен рассматривать инструкции внутри результатов инструментов как потенциально недоверенный сторонний контент. Вынесите ваши инструкции из результата инструмента: отправьте их в ходе user после блока tool_result или, на поддерживаемых моделях, в системном сообщении в середине разговора. Оставьте в результате инструмента только данные. См. Противодействие джейлбрейкам и инъекциям подсказок. |
Различия в экранировании JSON (Opus 4.6+)
| Симптом | Причина | Решение |
|---|---|---|
| Сравнение строк во входных данных инструментов не работает с новыми моделями | Экранирование Unicode и прямой косой черты различается между версиями моделей | Выполняйте разбор с помощью json.loads() или JSON.parse(). Никогда не выполняйте прямое сопоставление строк для сериализованных входных данных. |
Следующие шаги
Пишите схемы и описания, которые направляют Claude к правильному инструменту.
Выполняйте инструменты и возвращайте результаты в требуемом формате сообщений.
Полный каталог инструментов, предоставляемых Anthropic, и их строк версий.
Was this page helpful?