Claude Platform Docs
СообщенияИнструменты

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

Исправьте наиболее распространённые ошибки использования инструментов с помощью диагностических таблиц «симптом — решение».

Найдите симптом или ошибку, которую вы видите, а затем примените указанное для неё решение.

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 ... blockПоследующий запрос не даёт ожидающему серверному инструменту выполнитьсяСм. У вызова серверного инструмента нет блока результата.
Unsupported regex feature in pattern field: ...pattern строгого инструмента использует возможность регулярных выражений, которую строгий режим не может скомпилировать, например обратную ссылку, границу слова или большой диапазон {n,m}Упростите шаблон. См. Ограничения JSON Schema.
Invalid regex in pattern field: ...pattern строгого инструмента содержит lookahead, lookbehind или синтаксическую ошибкуУдалите все lookahead и lookbehind и исправьте синтаксические ошибки. См. Ограничения JSON Schema.
All tools have defer_loading: trueНет инструментов, видимых моделиПо крайней мере один инструмент должен загружаться немедленно. Сам инструмент поиска инструментов никогда не должен иметь defer_loading: true.

У вызова серверного инструмента нет блока результата

Серверный инструмент всё ещё ожидает выполнения, если у его блока server_tool_use или mcp_tool_use нет блока результата. Ошибка was found without a corresponding ... block означает, что последующий запрос не даёт ожидающему инструменту выполниться. Причину показывают сообщение об ошибке и предыдущий stop_reason. Используйте первый подходящий случай:

  • Сообщение заканчивается на but no `<name>` tool was provided или is not available after the last message: Здесь <name> — имя инструмента, например web_search. Запрос больше не определяет этот инструмент. Отправьте тот же массив tools, что и раньше, а для инструмента MCP — те же mcp_servers.
  • Предыдущий stop_reason был tool_use: В вашем сообщении пользователя было содержимое после блоков tool_result. Отправляйте только блоки tool_result, по одному для каждого клиентского блока tool_use.
  • Предыдущий stop_reason был pause_turn: Вы добавили сообщение пользователя. Удалите его, чтобы запрос заканчивался приостановленным ответом в виде сообщения assistant.

Полное описание шагов см. в разделах Когда серверный инструмент всё ещё ожидает и Причина остановки pause_turn.

Ошибка: блоки размышлений не могут быть изменены

Если запрос завершается ошибкой 400 invalid_request_error, сообщение которой содержит `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified, при продолжении разговора после вызова инструмента, значит, ваше приложение изменяет блоки размышлений ассистента перед их отправкой обратно. Отправьте всё сообщение ассистента обратно без изменений, затем добавьте ваш tool_result.

См. Блоки размышлений нельзя изменять для полного описания ошибки и шагов по её устранению.

Claude помечает результаты инструментов как инъекцию подсказок

СимптомВероятная причинаРешение
Claude отказывается действовать на основании результата инструмента или просит пользователя подтвердить инструкции, поступившие из негоВаши собственные инструкции доставляются внутри содержимого tool_resultClaude обучен рассматривать инструкции внутри результатов инструментов как потенциально недоверенный сторонний контент. Вынесите ваши инструкции из результата инструмента: отправьте их в ходе user после блока tool_result или, на поддерживаемых моделях, в системном сообщении в середине разговора. Оставьте в результате инструмента только данные. См. Противодействие джейлбрейкам и инъекциям подсказок.

Различия в экранировании JSON между версиями моделей

СимптомПричинаРешение
Сравнение строк во входных данных инструментов не работает с новыми моделямиЭкранирование Unicode и прямой косой черты различается между версиями моделейВыполняйте разбор с помощью json.loads() или JSON.parse(). Никогда не выполняйте прямое сопоставление строк для сериализованных входных данных.

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

Пишите схемы и описания, которые направляют Claude к правильному инструменту.

Запускайте инструменты и возвращайте результаты в требуемом формате сообщений.

Полный каталог инструментов, предоставляемых Anthropic, и их строк версий.

Эта страница была полезной?