Почему ИИ-агент игнорирует подключённые инструменты — и как это починить

Если ИИ-агент в упор не пользуется подключёнными инструментами, дело почти никогда не в поломке. В девяти случаях из десяти агент просто не понял, когда этот инструмент нужен — и виновата формулировка, а не код. Расплывчатое описание инструмента, два похожих инструмента, которые путают модель, отсутствие правил в системном промпте, уверенность модели, что она и так знает ответ. Всё это чинится текстом за один вечер, и нетехнарю это полностью по силам. Оставшийся десятый случай — техника: протухший токен, упавший сервер, слишком сложная схема параметров, слишком слабая модель. Вот это промптом уже не вытащить — и дальше я честно скажу, где именно. А пока — восемь конкретных причин с примерами, три кейса с цифрами и чек-лист, который прогоняется за 15 минут.

Сначала поймите, что именно происходит

У слова «игнорирует» есть два очень разных смысла, и пока вы их не различили, чинить нечего.

Первый вариант: агент даже не пытается вызвать инструмент. Отвечает из головы, будто инструмента и нет.

Второй вариант: агент инструмент вызывает, тот падает или возвращает ошибку, а агент молча делает вид, что ничего не было, и продолжает разговор.

Это две разные болезни с разным лечением. Первая лечится формулировками, вторая — техникой. Перепутаете — будете месяц шлифовать описание инструмента, который на самом деле просто отвалился по токену.

Как увидеть, что именно у вас. Если работаете в конструкторе или в редакторе кода — откройте лог вызовов (его ещё называют трейсом): там видно каждое обращение агента к инструменту и каждый ответ. Если конструктор лога не показывает — есть приём, который почему-то почти никто не использует: спросите агента напрямую. «Почему ты не воспользовался инструментом для проверки остатков на складе?» Модели отвечают на удивление честно: «В его описании сказано, что он для складского учёта, а вы спросили про наличие товара — я не связал одно с другим». Бесплатная диагностика за десять секунд.

Причина первая и главная: агент не понимает, КОГДА звать инструмент

Вот что нужно принять раз и навсегда. Модель выбирает инструмент не по тому, что он умеет, а по тому, что написано в его описании. Описание инструмента — это не подпись в интерфейсе для красоты. Это должностная инструкция, и единственная, которую модель вообще прочитает.

Описание инструмента написано для вас, а не для модели

Самая частая причина из всех. Вы назвали инструмент process_data и в описании написали «обрабатывает данные». Вам понятно — вы знаете, что там внутри. Модель видит это впервые и не понимает ничего: какие данные, в какой момент, зачем. Так что она этот инструмент аккуратно обходит.

Это как взять стажёра и сказать ему: «Будешь заниматься документами». Каким? Когда? Стажёр не тупой — ему просто не объяснили, в каком ящике лежат бланки. Он постоит и пойдёт делать то, что понял.

Хорошее описание отвечает на три вопроса: что инструмент делает, когда его звать и когда не звать. Сравните. Было: «интеграция с учётной системой». Стало: «Загружает проверенный счёт в 1С. Вызывай после того, как сверил сумму и контрагента. Не вызывай для черновиков и для входящих писем без вложения». Второе модель понимает с первого раза.

Два инструмента дерутся за одну задачу

Вы подключили инструмент search_orders и инструмент find_order. Оба про заказы, описания похожи. Для вас это два разных инструмента. Для модели — два почти одинаковых, и она зависает: какой из них «настоящий»?

Ведёт себя модель в этот момент как два менеджера с пересекающимися обязанностями: каждый уверен, что задачу сделает другой, — и в итоге не делает никто. Либо агент хватается за первый попавшийся и промахивается.

Лечится двумя способами. Либо объедините похожие инструменты в один. Либо жёстко разведите их по описаниям и названиям: search_orders — поиск по списку, когда номер заказа неизвестен; а find_order переименуйте в get_order и опишите как «получить заказ, когда номер уже на руках». Граница должна быть такой, чтобы по ней мог пройти посторонний человек, не зная вашей кухни.

Модель уверена, что знает ответ сама

Вызов инструмента всегда конкурирует с уверенностью модели. Если модель «считает», что знает ответ, она ответит из памяти и никуда не полезет. Особенно на вопросах, которые выглядят как общие знания: цены, ставки, курсы, даты, статусы, остатки.

Это сотрудник, который не пошёл в архив, а ответил по памяти. Иногда угадал. В отчёте для налоговой «иногда угадал» — это не результат, это лотерея.

Лечится одной строкой в системном промпте: «Никогда не называй цифры, цены, ставки и статусы из памяти. Всегда сверяйся через инструмент. Если инструмент недоступен — так и скажи, не придумывай». Стоимость такой починки — одно предложение, а разница в поведении агента — между «вечно врёт» и «вечно прав».

Причина вторая: агенту технически тяжело вызвать инструмент

Бывает, агент понял, что инструмент нужен, — но физически не справился с вызовом. Снаружи это снова выглядит как «игнорирует».

Схема параметров слишком сложная

Чтобы вызвать инструмент, модель должна заполнить его параметры. Если параметров пятнадцать, восемь из них обязательные, а названия вроде param_a, flag_2 без единого пояснения — модель не понимает, что туда подставлять, и тихо пропускает вызов. Не потому что не хочет, а потому что не может корректно собрать запрос.

Решение скучное, но рабочее: меньше параметров, обязательных — по минимуму, у каждого человеческое название и пример значения. Инструмент должно быть так же легко вызвать, как нажать одну кнопку, а не заполнить анкету на визу.

Инструментов столько, что агент в них тонет

Подключили агенту двадцать инструментов — внимание модели размазывается, и она стабильно пользуется первыми пятью-шестью, а остальные будто не существуют.

Это двадцать пультов на журнальном столике. Нужный пульт там есть. Но вы тычете в три знакомых, а до остальных рука не доходит.

Надёжно одному агенту по силам примерно десяток инструментов — дальше внимание модели размывается. Точного предела нет, это практическое наблюдение, а не константа. Но если инструментов заметно больше десятка — это не повод уговаривать агента быть внимательнее, а сигнал, что пора менять архитектуру. Об этом честно скажу в разделе про то, чего промптом не починить.

Инструмент возвращает ответ, который ломает агента

Агент честно вызвал инструмент — а тот вернул ему JSON на восемь тысяч строк, или голую ошибку Error 500 без слов, или данные в формате, которого агент не ждал. Агент захлёбывается этим ответом, теряет нить — и в рамках диалога «делает вывод», что этот инструмент лучше не трогать.

Инструмент должен возвращать короткий, понятный, предсказуемый ответ. Не весь склад целиком, а «остаток: 12 шт». Не Error 500, а человеческими словами: «заказ с таким номером не найден». Агент — не телепат, он работает с тем, что ему дали на руки.

Причина третья: агент зовёт инструмент, но всё равно не работает

Здесь агент всё делает правильно. Проблема — снаружи него.

Инструмент один раз упал — и агент сдался

Агент вызвал инструмент, получил ошибку и решил больше не пробовать — даже если инструмент через секунду починился. В пределах одного диалога агенты «запоминают» неудачу и обходят больное место стороной.

Частично лечится инструкцией про повтор («если инструмент вернул ошибку — попробуй ещё раз, прежде чем сдаваться») и тем, чтобы инструмент отвечал на сбой по-человечески, а не пугающим кодом. Но если инструмент падает не разово, а постоянно — никакая инструкция не поможет, это уже следующий пункт.

Токен протух, доступ закрыт, сервер молчит

Самая обидная история. Агент всё делает безупречно — стучится в дверь, — а за дверью никого. Протух токен авторизации. Лёг сервер интеграции. У сервиса сменился адрес, а агенту об этом не сказали.

Снаружи это выглядит ровно как «агент тупит и игнорирует инструмент». На деле агент честно работает — сломана труба между ним и инструментом. И вот это формулировками уже не чинится.

Три кейса из реальной работы

Кейс 1. ИИ считал «в уме» — и фантазировал. В клубе разбирали задачу участницы: ИИ-агент работал с её таблицами, но цифры в ответах регулярно не сходились. Перепроверять за ним приходилось так часто, что это съедало больше времени, чем экономило. Причина из тех, что в этой статье уже разобраны: модель прикидывала числа сама, вместо того чтобы вызвать инструмент. Решение — собрали для неё отдельный MCP-сервер: теперь модель не считает на глаз, а передаёт расчёт настоящей программе-инструменту и возвращает уже посчитанный результат. Не «уговорили» агента быть внимательнее — дали ему инструмент, мимо которого не пройти.

Кейс 2. Три инструмента, пока один не сработал. Мой собственный кейс: нужно было автоматизировать модерацию контента на сайте. Первым взяла Manus — задачу не вытянул. Вторым n8n — тоже не справился. Заработало только с третьего захода: конструктор Dify со встроенным инструментом чтения сайтов Watercrawl. Вывод тут не про «тупой агент», а про то, что агент способен ровно настолько, насколько способен подключённый к нему инструмент. Иногда, чтобы найти рабочий, приходится перебрать два-три — и это нормальная часть работы, а не провал.

Кейс 3. Готовый GPT уверенно врал — подключили базу знаний. Пришла подписчица с задачей: нужен ИИ-помощник по узкой теме о здоровье. Готовые GPT по этой теме откровенно галлюцинировали — выдавали правдоподобные, но выдуманные ответы. Модель «знала сама» и ошибалась. Собрали отдельного агента со своей векторной базой знаний — связка n8n, Pinecone, OpenAI и Telegram, с памятью диалога и распознаванием голоса. По сути, подключили модели правильный источник вместо догадок. Рабочий прототип получился без программиста и с бюджетом 5–25 долларов.

Где это не лечится промптом — честно

Промпт — мощная штука, но это не сварка. Чинить им протухший токен — то же самое, что чинить кран уговорами. Вот четыре ситуации, где формулировки бессильны, и нужно другое.

• Слабая или слишком дешёвая модель. На совсем лёгких моделях надёжный вызов инструментов не получается в принципе — сегодня сработало, завтра нет. Никакая формулировка это не вылечит. Решение — модель посильнее, а не магия слов.
• Реально сломанная интеграция. Сервер лежит, токен протух, у API сменился адрес. Это инженерная починка: обновить доступ, добавить повторные попытки, поставить простой мониторинг. Работа руками, а не текстом.
• Инструментов объективно много — и все нужны. Если у вас честные 25 инструментов, ужать до десятка не выйдет. Тогда нужна архитектура: агент-роутер, который раздаёт задачи узким суб-агентам, у каждого — свой небольшой набор. Это уже не уговоры формулировками, а проектирование — ровно то, чему посвящён курс «ИИ-агенты + Вайбкодинг».
• Инструмент возвращает мусор. Если на той стороне кривые данные, агент не виноват и промпт не спасёт. Чинить нужно источник.

И ещё раз про пропорцию: «честно техническая» причина — это тот самый один случай из десяти. Девять из десяти — это текст, и текст вы поправите сами.

Чек-лист: диагностика за 15 минут

Прогоните по порядку, не перепрыгивая. Большинство «капризных» агентов чинятся где-то на третьем-четвёртом пункте.

• Откройте лог вызовов. Агент инструмент вызвал или не вызвал? Это развилка: вызвал и упал — техника, не вызвал — формулировки.
• Спросите агента напрямую: «Почему ты не воспользовался инструментом X?» Запишите ответ дословно — часто в нём уже лежит причина.
• Прочитайте описание инструмента глазами постороннего человека. Понятно, что он делает и когда его звать? Если нет — перепишите.
• Проверьте, нет ли двух инструментов с похожими описаниями. Есть — разведите границы или объедините.
• Посчитайте инструменты. Заметно больше десятка — режьте набор или выносите часть отдельному агенту.
• Загляните в схему параметров. Много обязательных полей с непонятными названиями — упрощайте.
• Добавьте в системный промпт прямое правило: когда инструмент звать обязательно и что цифры из памяти брать нельзя.
• Проверьте доступ: токен жив, сервер отвечает, адрес интеграции верный.

Если прошли все восемь пунктов и агент всё равно упрямится — почти наверняка вы в том самом «десятом случае»: слабая модель или сломанная интеграция. Это уже не про текст.

FAQ

Как понять, агент не вызывает инструмент или вызывает и падает?

Откройте лог вызовов (трейс) — в нём видно каждое обращение агента к инструменту. Если конструктор лога не показывает, спросите агента прямо: «Ты вызывал инструмент X?». Это развилка диагностики: если не вызывал — проблема в формулировках, если вызывал и получил ошибку — в технике.

Почему ИИ-агент придумывает ответ вместо вызова инструмента?

Потому что вызов инструмента конкурирует с уверенностью модели. Если модель «считает», что знает ответ, она отвечает из памяти. Особенно на вопросах про цены, ставки и статусы. Лечится строкой в системном промпте: цифры и статусы никогда не брать из памяти, только через инструмент.

Сколько инструментов можно подключить к одному ИИ-агенту?

Технически — много, но надёжно одному агенту по силам примерно десяток инструментов: дальше внимание модели размывается, и часть инструментов перестаёт использоваться. Жёсткой константы тут нет, это практический ориентир. Если инструментов объективно больше, нужен не один агент, а несколько узких плюс агент-роутер.

Можно ли починить tool calling одним промптом?

В большинстве случаев — да. Девять проблем из десяти — это формулировки: описание инструмента, границы между похожими инструментами, правила в системном промпте. Промптом не лечится только техника: слабая модель, протухший токен, упавший сервер, кривые данные на стороне инструмента.

Агент пользовался инструментом, а потом перестал — почему?

Чаще всего инструмент один раз вернул ошибку, и агент в рамках диалога «решил» больше его не трогать. Либо протух токен доступа или лёг сервер интеграции. Проверьте доступ и добавьте в инструкцию правило про повторную попытку при ошибке.

Можно ли настроить агента без программиста?

Описание инструментов, границы между ними и правила в системном промпте — это текст, и его правит нетехнарь за вечер. Программист нужен для другого: починить сломанную интеграцию, настроить повторные попытки, выстроить архитектуру из нескольких агентов.

С чего начать сейчас

Не пытайтесь починить всё разом. Возьмите один инструмент, который агент игнорирует чаще всего, и пройдите по нему первые четыре пункта чек-листа: лог, вопрос агенту, описание, поиск двойника. На этой неделе — один инструмент, один проход. Скорее всего, на нём же вы и увидите, что половина ваших агентов «капризничала» по одной и той же причине — кривому описанию.

А когда почините — не останавливайтесь на «вроде заработало». Соберите для себя короткий шаблон хорошего описания инструмента и системного промпта. В следующий раз агент будет слушаться с первого включения, и чинить уже не придётся.

Подпишитесь на канал, если хотите больше таких разборов: t.me/gruboprostiite