Устранение неполадок при использовании инструментов
Исправьте наиболее распространённые ошибки использования инструментов с помощью диагностических таблиц «симптом — решение».
Найдите симптом или ошибку, которую вы видите, а затем примените указанное для неё решение.
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_result | Claude обучен рассматривать инструкции внутри результатов инструментов как потенциально недоверенный сторонний контент. Вынесите ваши инструкции из результата инструмента: отправьте их в ходе user после блока tool_result или, на поддерживаемых моделях, в системном сообщении в середине разговора. Оставьте в результате инструмента только данные. См. Противодействие джейлбрейкам и инъекциям подсказок. |
Различия в экранировании JSON между версиями моделей
| Симптом | Причина | Решение |
|---|---|---|
| Сравнение строк во входных данных инструментов не работает с новыми моделями | Экранирование Unicode и прямой косой черты различается между версиями моделей | Выполняйте разбор с помощью json.loads() или JSON.parse(). Никогда не выполняйте прямое сопоставление строк для сериализованных входных данных. |
Следующие шаги
Пишите схемы и описания, которые направляют Claude к правильному инструменту.
Запускайте инструменты и возвращайте результаты в требуемом формате сообщений.
Полный каталог инструментов, предоставляемых Anthropic, и их строк версий.
Эта страница была полезной?