Агент затупив: як знайти причину і полагодити ШІ-агента

Що означає «агент затупив» простими словами

Машина заглухла. Далі - два типи людей. Перший бʼє по капоту, кричить «ну давай же!» і вдесяте крутить ключ у надії, що «само заведеться». Другий відкриває капот, світить ліхтариком - а там просто бензин закінчився.

Зі ШІ-агентом точнісінько та сама історія. Він «затупив» - зациклився, ходить по колу, сперечається чи меле дурниці. Новачок бʼє по капоту: перепитує те саме трохи іншими словами, злиться і врешті зносить увесь проєкт. А вайбкодер відкриває капот: ставить діагноз, знаходить причину і лікує саме її. Різниця - години часу і купа спалених токенів.

Навіщо вчитися діагностиці ШІ-агента

Бо агент буде тупити. Це так само неминуче, як затори в пʼятницю ввечері. Питання одне: що ти робиш у цей момент - панікуєш чи лагодиш?

• Немає навички діагностики - ти палиш токени (а отже, гроші) на марних перепитуваннях.
• Ти втрачаєш години, сперечаючись зі ШІ, хоча причину можна знайти за хвилину.
• У паніці ти здатен знести робочий код, хоча поломка була на копійку.

Цей урок - твоя «аптечка». У скілі ECC ECC (Engineering-Centric Coding) - набір передових робочих прийомів для роботи з агентами. agent-introspection-debugging - це «скіл самодіагностики»: учить агента розбирати свої збої покроково, перш ніж здаватися. він називається agent-introspection-debugging - структурний розбір збою замість сліпих повторів. Зараз розкладемо його на прості кроки.

Як полагодити агента: 4 кроки замість паніки

Запамʼятай одне правило: не повторюй те саме тричі, міняючи пару слів. Це і є найчастіший антипатерн. Хочеш результат - пройди по чотирьох фазах. Кожна займає пару хвилин, а разом вони економлять години.

Крок 1. Зафіксуй збій - зроби фото місця аварії

Перш ніж щось чіпати - запиши, що взагалі сталося. Не в голові, а словами:

• Що агент намагався зробити в момент поломки?
• Яка помилка вилізла (точний текст, якщо є)?
• Який був останній вдалий крок?
• Яка дія повторюється по колу?
• Що агент вважає правдою про світ - де він думає, що перебуває (папка, гілка, які файли є)?

Крок 2. Знайди причину - постав діагноз

Тепер зістав симптом із типовою причиною. Їх небагато, і в обличчя вони впізнавані:

А ось чотири питання-фільтри - вони відсікають зайве і називають тип поломки:

• Це логіка (агент неправильно думає), стан (світ не такий, як він думає), оточення (щось ззовні не працює) чи правило (йому не дали інструкцію)?
• Чи не загубив він мету і чи не полірує не ту задачу?
• Збій постійний чи випадковий - мигнув і минув?
• Яка найменша дія підтвердить, що я вгадав причину?

Крок 3. Лікуй маленькою дією

Жодних «переписати все наново». Бери найменшу дію, яка міняє картину:

Крок 4. Короткий звіт, щоб не наступити на ті самі граблі знову

Не фінішуй на «все, полагодив». Запиши коротко: що зламалося, у чому була причина, що я зробив, як зрозумів, що стало краще. Це твоя страховка. Наступного разу ти впізнаєш патерн за секунди, а не за пів години.

Коли тупить не модель, а обгортка (харнес)

Буває хитріше. Сама модель розумна - ти ганяв її «наживо», і все ок. А всередині твого застосунку вона тупить. Отже, хибить не кухар, а кухня навколо нього - обгортка, вона ж харнес. В ECC це розбирає скіл agent-architecture-audit.

Ідея проста. Між мозком моделі і тим, що бачиш ти, лежить багато шарів: системний промпт, історія, довга памʼять, вибір інструмента, його запуск, читання результату, відмалювання відповіді. І будь-який із них може непомітно зіпсувати хорошу відповідь.

Харнес Харнес (обгортка) - уся обвʼязка навколо моделі: інструменти, памʼять, правила, формат виводу. Модель одна на всіх, а обгортка в кожного застосунку своя - і саме вона найчастіше винна в «затупі». ламається кількома типовими способами:

Тримай швидкі питання-індикатори. Хоч на одне відповідь «так» - копай туди:

• Агент може пропустити обовʼязковий інструмент і все одно відповісти? Тобто правило живе лише в тексті, а не в коді.
• У нових розмовах спливає старий вміст? Памʼять забруднилася.
• Те саме лежить одразу в промпті, і в памʼяті, і в історії? Дублювання забиває стіл.
• Відповідь відрізняється між «всередині» і «на екрані»? Щось псує вивід дорогою.

Приклад із життя: агент лікує здорову ногу

Ти робиш телеграм-бота. Просиш агента «полагодь відправлення повідомлень». Він бадьоро править код, рапортує «готово!». Перевіряєш - тиша. Просиш знову - а він лізе в те саме місце і переписує його іншими словами. І ще раз. І ще. Токени тануть, бот мовчить, ти на межі.

А правда ось у чому: бот не запускався, бо не був увімкнений сам сервер (памʼятаєш причину «відмова зʼєднання»?). Агент лагодив код, якому й так було добре, - лікував здорову ногу, бо жодного разу не перевірив реальність.

Ось як скерувати його на правильний шлях із першого заходу:

Стоп. Не переписуй код наново. Спершу зроби діагностику покроково:

Опиши словами: що саме ти намагався зробити і яка помилка вилізла.
Назви останній крок, який точно спрацював.
Перевір реальність, а не свою памʼять: чи запущений сервер,
у якій я папці, в якій гілці, які файли реально існують.
Зістав симптом із причиною: це логіка, стан, оточення
чи немає правила? Назви одну найімовірнішу причину.
Запропонуй найменшу дію, яка доведе цю причину.
Зроби лише її. Решту коду не чіпай.
Наприкінці короткий звіт: що зламалося, причина, що зробив,
як зрозуміти, що стало краще.

Часті помилки при налагодженні агента

• Бити по капоту. Повторювати те саме різними словами - головний антипатерн. Спершу діагноз.
• Лікувати не ту хворобу. Агент править код, а проблема - у вимкненому сервері. Перевіряй реальність.
• Вірити памʼяті агента. Він «памʼятає» файл, якого немає. Дивись, що реально на диску.
• Одразу зносити все. Маленька дія майже завжди бʼє «перепишемо наново».
• Винити модель найпершою. Працювало в playground, а в тебе ні - копай обгортку, а не модель.
• Мовчки радіти «полагодив». Без короткого звіту ті самі граблі прилетять тобі в лоба за годину.