Harness Engineering: Повний посібник зі створення AI-агентів, які працюють стабільно

Більшість людей намагаються вдосконалити AI-агентів на неправильному рівні.

Коли агент зазнає невдачі, вони переписують підказку.

Коли він знову зазнає невдачі, вони додають більше інструкцій.

Перед тим, як ми почнемо:

Підпишіться на мій Substack, щоб отримувати свіжу AI-альфу, робочі процеси агентів та покрокові інструкції до того, як вони з'являться на X: [https://substack.com/@lunarresearcher

Потім вони змінюють моделі, додають більше інструментів, збільшують контекстне вікно і сподіваються, що наступний запуск буде іншим.

Але багато невдач агентів — це не помилки міркування.

Це помилки середовища.

Агент не знав, які файли мають значення.

Він використав правильний інструмент у неправильному місці.

Він втратив рішення, прийняті в попередньому сеансі.

Він заявив про успіх, не виконавши перевірок.

Він повторив дію після часткової невдачі.

Він мав дозвіл на те, що мало вимагати схвалення.

Модель не обов'язково була проблемою. Система навколо моделі була неповною.

Ця система — це обв'язка (harness).

І її проєктування стає окремою інженерною дисципліною.

Інженерія обв'язки — це практика побудови середовища, яке перетворює інтелект моделі на надійну роботу.

Підказка змінює одну спробу.

Обв'язка змінює кожну спробу.

Цей посібник пояснює, як побудувати таку обв'язку.

1. Модель — це не агент

Модель може міркувати, генерувати, порівнювати та обирати.

Але агент також повинен взаємодіяти з реальним середовищем.

Йому потрібно:

• розуміти завдання
• знаходити відповідний контекст
• вибирати та використовувати інструменти
• зберігати стан
• дотримуватися дозволів
• перевіряти результат
• відновлюватися після невдачі
• доводити, що робота завершена

Модель — це рушій міркувань всередині цієї системи.

Обв'язка — це все, що робить міркування операційними.

1запит користувача
2     |
3     v
4+-----------------------------+
5|          ОБВ'ЯЗКА           |
6| контракт | контекст | політика |
7| інструменти | стан | перевірки |
8| траси | відновлення          |
9+-----------------------------+
10     |
11     v
12    модель
13     |
14     v
15реальне середовище

Потужна модель у слабкій обв'язці — це все ще слабкий агент.

Вона може створювати вражаючі окремі відповіді, але поводитиметься непослідовно під час тривалих завдань, у мінливих середовищах та при часткових невдачах.

Мета інженерії обв'язки — не усунути невизначеність з моделі.

Вона полягає в тому, щоб утримувати цю невизначеність у системі, яка може спостерігати, перевіряти та відновлювати.

2. Почніть з контракту на завдання

Більшість завдань агентів починаються як розпливчастий намір:

Покращити процес онбордингу.

Цього речення може бути достатньо для розмови.

Його недостатньо для автономного виконання.

Перш ніж агент почне діяти, обв'язка повинна перетворити запит на контракт завдання.

Корисний контракт відповідає на п'ять запитань:

1. Який результат має існувати?
2. Що входить в обсяг?
3. Що не повинно змінюватися?
4. Які докази підтверджують завершення?
5. Які дії вимагають схвалення людини?

1мета: зменшити відтік під час онбордингу
2
3обсяг:
4  - процес реєстрації
5  - аналітика онбордингу
6
7обмеження:
8  - не змінювати автентифікацію
9  - зберегти існуючу поведінку на мобільних пристроях
10
11приймання:
12  - тести проходять
13  - подія аналітики надсилається
14  - скріншоти охоплюють десктоп та мобільні пристрої
15
16вимагає_схвалення:
17  - розгортання на продакшені
18  - міграція бази даних

Це змінює питання агента з:

Що мені робити далі?

на:

Яка дія наближає середовище до обумовленого результату?

Без контракту агент оптимізує для правдоподібної активності.

З контрактом він може оптимізувати для підтвердженого завершення.

3. Дайте агенту карту, а не інструкцію

Скидання всього репозиторію, набору документації та історії розмов у контекст — це не хороша інженерія контексту.

Це затоплення контекстом.

Обв'язка повинна спочатку надати невелику карту, а потім дозволити агенту отримувати деталі, коли вони стануть актуальними.

1КАРТА ПРОЄКТУ
2
3правила продукту     -> docs/product/
4архітектура          -> docs/architecture.md
5фронтенд             -> apps/web/
6бекенд               -> services/api/
7тести                -> tests/
8команди              -> docs/commands.md
9правила релізу       -> docs/release.md

Це прогресивне розкриття:

1завдання
2  -> карта проєкту
3      -> відповідна підсистема
4          -> точні файли
5              -> локальні інструкції

Контекст повинен розширюватися, тому що цього вимагає завдання, а не тому, що інформація існує.

Хороший компілятор контексту вирішує:

• що потрібно завжди
• що можна отримати пізніше
• що стало застарілим
• що можна підсумувати
• що має залишитися дослівно

Мета — не максимальний контекст.

Це максимальний сигнал на токен.

4. Побудуйте шлюз інструментів, а не купу інструментів

Надання агенту двадцяти інструментів не робить його здатнішим.

Це дає агенту двадцять способів зробити помилку.

Кожен інструмент повинен мати чіткий контракт:

1ІНСТРУМЕНТ: edit_file
2
3вхідні дані:
4  шлях
5  патч
6
7передумови:
8  шлях існує
9  шлях знаходиться в дозволеній робочій області
10
11доказ успіху:
12  патч застосовано
13  отримано результуючий diff
14
15поведінка при невдачі:
16  без часткового перезапису
17  повернуто структуровану помилку
18
19клас ризику:
20  зворотний

Обв'язка повинна контролювати, як інструменти надаються та використовуються.

Вона може:

• приховувати нерелевантні інструменти
• перевіряти аргументи
• обмежувати шляхи та домени
• прикріплювати тайм-аути
• робити повторні спроби ідемпотентними
• нормалізувати вихідні дані
• вимагати підтвердження для ризикованих дій
• повертати докази, а не просто "успіх"

Це створює важливе розділення:

1модель визначає намір
2шлюз перевіряє дію
3інструмент змінює середовище
4сенсор спостерігає результат

Модель може запропонувати дію.

Шлюз інструментів вирішує, чи є ця дія достатньо дійсною для виконання.

5. Розділіть мозок, руки та історію

Багато крихких агентів змішують все в один зростаючий транскрипт.

Міркування, виклики інструментів, файли, рішення, помилки та старі спостереження — все конкурує за одне й те саме контекстне вікно.

Сильніша система розділяє три обов'язки:

1МОЗОК
2планує, міркує, обирає
3
4РУКИ
5виконують інструменти в контрольованому середовищі
6
7ІСТОРІЯ
8зберігає стійкі факти, рішення та стан запуску

Моделі не потрібна кожна необроблена подія в активному контексті.

Їй потрібен правильний поточний стан.

Пісочниці не потрібно розуміти всю мету.

Їй потрібно безпечно виконати обмежену дію.

Журналу сеансу не потрібно міркувати.

Йому потрібно зберегти те, що сталося після зникнення поточного контексту.

Це розділення полегшує відновлення, перевірку та ремонт довготривалих агентів.

Воно також дозволяє замінити одну частину без перебудови всієї системи.

6. Пам'ять має стати стійким станом

Історія розмови — це не надійна пам'ять.

Це потік подій.

Корисну пам'ять слід перетворювати на явний стан.

Як мінімум, зберігайте чотири категорії:

1ФАКТИ
2стабільна інформація, виявлена про середовище
3
4РІШЕННЯ
5зроблений вибір та причина, що стоїть за ним
6
7ПРОГРЕС
8завершена, активна, заблокована та решта роботи
9
10УРОКИ
11невдачі, які повинні змінити майбутню поведінку

Наприклад:

1факти:
2  - валідація оформлення замовлення знаходиться в services/orders
3
4рішення:
5  - використати існуючий конвеєр валідації
6  - причина: уникає другого джерела істини
7
8прогрес:
9  завершено:
10    - додано правило на стороні сервера
11  залишилося:
12    - оновити інтеграційний тест
13
14уроки:
15  - локальна тестова команда вимагає TEST_DB_URL

Це набагато корисніше, ніж відтворювати п'ятдесят сторінок транскрипту, сподіваючись, що модель помітить важливий рядок.

Зберігайте необроблену історію для аудиту.

Компілюйте стійкий стан для виконання.

7. Завершення вимагає доказів

Твердження агента "готово" не є доказом того, що завдання виконано.

Це лише ще один вихід моделі.

Завершення має визначатися спостережуваними змінами в середовищі.

1твердження                     доказ
2--------------------------------------------------
3"баг виправлено"               несправний тест тепер проходить
4"сторінка працює"              браузерний потік завершено
5"міграція безпечна"            сухий прогін та відкат проходять
6"звіт правильний"              значення збігаються з вихідними даними
7"завдання виконано"            кожна перевірка приймання проходить

Обв'язка повинна спочатку виконувати найдешевші детерміновані перевірки.

1синтаксис
2  -> типи
3      -> цільові тести
4          -> інтеграційні тести
5              -> візуальний або семантичний огляд
6                  -> схвалення людини

Не використовуйте іншу модель там, де компілятор, схема, контрольна сума, запит або тест можуть відповісти на питання.

Використовуйте моделі для неоднозначності.

Використовуйте код для інфраструктури.

Модель може припустити, що завдання виконано.

Лише середовище може це довести.

8. Верифікація повинна атакувати результат

Виконавці та оцінювачі не повинні мати однакову мету.

Виконавець намагається створити найсильніше рішення.

Оцінювач намагається знайти причину, чому його слід відхилити.

1виконавець
2  -> створює кандидата
3
4верифікатор
5  -> перевіряє контракт
6  -> шукає пропущені випадки
7  -> тестує непідтверджені твердження
8  -> намагається зламати результат
9
10витримує
11  -> прийняти
12
13не витримує
14  -> повернути цільові докази

Ця асиметрія має значення.

Якщо ви попросите того самого агента, в тому самому контексті, "перевірити свою роботу", він часто збереже припущення, які створили помилку.

Корисний етап верифікації повинен мати:

• явний критерій відхилення
• доступ до створеного артефакту
• доступ до контракту приймання
• незалежні інструменти або свіжий контекст, коли це необхідно
• дозвіл відхиляти без виправлення

Верифікація — це не друга думка.

Це спроба спростування.

9. Модель пропонує, політика авторизує

Деякі правила ніколи не повинні залежати від того, чи пам'ятає їх модель.

1ніколи не публікувати без схвалення
2ніколи не розкривати секрет
3ніколи не писати за межами робочої області
4ніколи не перевищувати ліміт витрат
5ніколи не позначати тести як пройдені, якщо вони не виконувалися

Це не пропозиції в підказці.

Це політика.

Найбезпечніший дизайн тримає політику поза циклом міркувань.

1НИЗЬКИЙ РИЗИК
2читати файли, шукати, перевіряти
3-> автоматично
4
5ЗВОРОТНА ЗМІНА
6редагувати робочу область, запускати тести
7-> автоматично з трасуванням
8
9ЗОВНІШНІЙ ВПЛИВ
10надіслати повідомлення, розгорнути, придбати
11-> явне схвалення
12
13НЕЗВОРОТНА АБО ЧУТЛИВА
14видалити дані, змінити облікові дані, опублікувати глобально
15-> жорсткий шлюз або заборона

Чим сильніший наслідок, тим жорсткіший шлюз.

Автономність — це не відсутність контролю.

Це здатність вільно діяти в чітко визначених межах.

10. Відновлення має бути спрямоване на клас невдачі

Найпоширеніша стратегія відновлення:

Щось не вдалося. Спробуй ще раз.

Це не відновлення.

Це повторення.

Обв'язка повинна класифікувати невдачу, перш ніж вибрати наступну дію.

1тайм-аут інструменту
2-> повторити з відстрочкою
3
4недійсні аргументи
5-> виправити виклик інструменту
6
7відсутній контекст
8-> отримати конкретне джерело
9
10невдалий тест
11-> перевірити несправну поведінку
12
13відмовлено в дозволі
14-> запитати схвалення або обрати безпечний шлях
15
16суперечливі вимоги
17-> передати людині
18
19повторна незмінна невдача
20-> зупинити цикл

Повторна спроба повинна змінити принаймні одну відповідну умову.

Інакше система платить за відтворення тієї самої невдачі.

Обмежений цикл агента виглядає так:

1спостерігати
2  -> вирішити
3      -> діяти
4          -> виміряти
5              -> прийняти
6              -> виправити
7              -> передати
8              -> зупинити

Кожен цикл потребує бюджету:

• максимальна кількість спроб
• максимальний час
• максимальні витрати
• максимальний деструктивний обсяг
• умова передачі

Надійні агенти знають, як продовжувати.

Вони також знають, коли продовження більше не є раціональним.

11. Інструкції мають стати інфраструктурою

Інструкції агента корисні, коли вони пояснюють локальну реальність.

Але самі по собі інструкції — це слабке забезпечення виконання.

Якщо правило має значення неодноразово, перемістіть його вниз по стеку.

1"використовуй форматувальник"
2-> запускати форматувальник автоматично
3
4"не імпортуй між шарами"
5-> додати архітектурний тест
6
7"включи відкат міграції"
8-> вимагати файл відкату в CI
9
10"не змінюй згенеровані файли"
11-> блокувати запис у згенеровані шляхи
12
13"цитуй кожне зовнішнє твердження"
14-> перевіряти охоплення цитування

Це створює драбину інструкцій:

1пояснення
2  -> контрольний список
3      -> шаблон
4          -> автоматизована перевірка
5              -> обов'язкова політика

Переміщуйте важливі знання якомога нижче по цій драбині, наскільки це практично.

Підказка повинна пояснювати судження.

Обв'язка повинна забезпечувати інваріанти.

12. Спостерігайте за запуском, а не лише за кінцевою відповіддю

Чистий кінцевий артефакт може приховувати жахливий процес.

Агент міг:

• отримати доступ до неправильних даних
• проігнорувати невдалу команду
• двічі повторити зовнішню дію
• витратити в десять разів більше очікуваного бюджету
• дійти правильної відповіді з неправильної причини

Вам потрібні траси, які роблять запуск відтворюваним.

109:14  контракт створено
209:15  завантажено джерело контексту: architecture.md
309:17  відредаговано файл: checkout.ts
409:18  цільовий тест не пройшов: дублікат купона
509:21  реалізацію виправлено
609:22  цільовий тест пройшов
709:24  інтеграційний тест пройшов
809:25  зовнішнє розгортання заблоковано: потрібне схвалення

Корисний запис траси фіксує:

• переходи станів
• джерела контексту
• вхідні та вихідні дані інструментів
• зміни середовища
• результати верифікації
• причини повторних спроб
• рішення про схвалення
• вартість та затримку

Мета — не спостереження.

Мета — локальний ремонт.

Коли запуск не вдається на кроці 18, ви повинні мати можливість перезапуститися з надійної контрольної точки замість відтворення всього завдання.

13. Кожен запуск потребує квитанції про зміни

Довгі транскрипти агентів важко перевіряти.

Наприкінці запуску обв'язка повинна скласти коротку квитанцію про зміни.

1МЕТА
2Виправити застосування дубліката купона під час оформлення замовлення.
3
4ЗМІНЕНО
5- логіку валідації оформлення замовлення
6- цільовий регресійний тест
7
8ПЕРЕВІРЕНО
9- лінтер пройшов
10- модульні тести пройшли
11- інтеграційний тест оформлення замовлення пройшов
12
13НЕ ПЕРЕВІРЕНО
14- продакшн-платіжний провайдер
15
16РІШЕННЯ
17- збережено існуючий порядок пріоритету купонів
18
19РИЗИКИ
20- застарілий мобільний клієнт не був доступний локально
21
22ПОТРІБНЕ СХВАЛЕННЯ
23- розгорнути на стейджингу

Квитанція — це не підсумок того, що сказала модель.

Це підсумок того, що система може довести.

Це дає людям компактну поверхню для перевірки та надає наступному сеансу агента надійну відправну точку.

Найкраща передача — це не "ось розмова".

Це "ось стан, докази та невирішений ризик".

14. Кожна невдача має вдосконалювати обв'язку

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

Найсильніші команди також виправляють систему, яка це дозволила.

Після невдачі запитайте:

1Чи був контракт завдання неоднозначним?
2Чи була важлива інформація невидимою?
3Чи був наданий неправильний інструмент?
4Чи була відсутня передумова?
5Чи був результат неверифікованим?
6Чи залишилася політика всередині підказки?
7Чи було відновлення надто широким?
8Чи було трасування недостатнім?

Потім перетворіть урок на повторно використовуване вдосконалення.

1невдача
2  -> діагностика
3      -> новий сенсор, правило, карта, тест або контракт інструменту
4          -> майбутні запуски покращуються автоматично

Це маховик обв'язки.

Система стає надійнішою, тому що невдачі залишають після себе інфраструктуру.

Виправлена відповідь допомагає одному запуску.

Виправлена обв'язка допомагає кожному майбутньому запуску.

15. Обв'язки також застарівають

Більше обв'язки — не завжди краще.

Моделі вдосконалюються. Інструменти вдосконалюються. Завдання змінюються. Старі запобіжники можуть стати непотрібним тертям.

Обхідний шлях, створений для вчорашньої моделі, може завадити сьогоднішній моделі використовувати кращу стратегію.

Це створює застарівання обв'язки:

1обмеження старої моделі
2  -> обхідний шлях в обв'язці
3      -> модель вдосконалюється
4          -> обхідний шлях залишається
5              -> система стає повільнішою або менш здатною

Ставтеся до компонентів обв'язки як до продакшн-коду.

Вимірюйте, чи вони все ще забезпечують приріст.

Для кожного маршрутизатора, оцінювача, шару пам'яті та правила повтору запитайте:

• Яку невдачу це запобігає?
• Як часто ця невдача все ще трапляється?
• Яку затримку та складність це додає?
• Чи можна тепер досягти того самого результату простіше?
• Що станеться, якщо ми це видалимо?

Найкраща обв'язка — не найбільша.

Це найменша система, яка надійно закриває розрив між наміром і доказом.

Будуйте, щоб видаляти.

16. Мінімально життєздатна обв'язка

Вам не потрібна оркестраційна платформа, щоб почати.

Будуйте обв'язку шарами.

Рівень 1: Обмежене завдання

• мета
• обсяг
• обмеження
• перевірки приймання

Рівень 2: Зрозуміле середовище

• карта проєкту
• команди
• локальні інструкції
• відомі залежності

Рівень 3: Контрольовані дії

• типізовані інструменти
• перевірка аргументів
• межі шляхів та дозволів
• структуровані результати

Рівень 4: Стійке виконання

• явний стан запуску
• контрольні точки
• рішення
• уроки

Рівень 5: Докази

• детерміновані перевірки
• змагальна верифікація
• квитанція про зміни

Рівень 6: Відновлення та навчання

• класифікація невдач
• обмежені повторні спроби
• передача
• оновлення обв'язки від повторюваних невдач

Побудуйте найменший шар, який усуває невдачу, яка у вас є.

Не починайте з багатоагентної архітектури, тому що одна підказка іноді потребує уточнення.

Складність має бути зароблена спостережуваною невдачею.

17. Специфікація багаторазової обв'язки

Перш ніж надати агенту значну автономію, визначте це:

1СПЕЦИФІКАЦІЯ ОБВ'ЯЗКИ АГЕНТА
2
31. КОНТРАКТ
4   мета:
5   обсяг:
6   обмеження:
7   докази приймання:
8
92. КОНТЕКСТ
10   завжди завантажена карта:
11   джерела отримання:
12   локальні інструкції:
13   правила свіжості:
14
153. ІНСТРУМЕНТИ
16   дозволені інструменти:
17   передумови:
18   побічні ефекти:
19   докази успіху:
20   політика тайм-ауту та повтору:
21
224. СТАН
23   факти:
24   рішення:
25   прогрес:
26   уроки:
27   формат контрольної точки:
28
295. ПОЛІТИКА
30   автоматичні дії:
31   дії, що вимагають схвалення:
32   заборонені дії:
33   бюджетні ліміти:
34
356. ВЕРИФІКАЦІЯ
36   детерміновані перевірки:
37   змагальні перевірки:
38   правило приймання:
39
407. ВІДНОВЛЕННЯ
41   класи невдач:
42   ліміти повторних спроб:
43   умови передачі:
44   безпечний відкат:
45
468. СПОСТЕРЕЖУВАНІСТЬ
47   події трасування:
48   метрики:
49   фінальна квитанція про зміни:

Якщо ці поля не визначені, агент не є автономним.

Він імпровізує.

18. Вимірюйте систему на правильному рівні

Кількість токенів — не кінцева метрика.

Так само, як і кількість виконаних завдань.

Корисна одиниця — це прийнята робота.

Практична метрика:

1прийняті результати
2------------------------------
3хвилини перевірки людиною + вартість запуску

Також відстежуйте:

• рівень прийняття з першої спроби
• рівень відновлення після невдачі інструменту
• рівень повторних невдач
• втручання людини на завдання
• непідтверджені твердження про завершення
• час від запиту до підтвердженого результату
• накладні витрати обв'язки за компонентом

Це запобігає поширеній ілюзії:

Агент може виглядати дуже продуктивним, створюючи дорогу роботу з перевірки.

Мета — не більше активності агента.

Це більше довірених результатів на одиницю уваги людини.

19. Коли вам не потрібна важка обв'язка

Не кожен виклик моделі потребує операційної системи.

Використовуйте просту підказку, коли:

• завдання коротке
• результат легко перевірити
• невдача дешева
• не відбувається зовнішнього побічного ефекту
• користувач залишається в циклі

Додавайте обв'язку, коли:

• робота охоплює кілька інструментів або сеансів
• середовище може змінюватися
• дії мають реальні наслідки
• завершення важко оцінити вручну
• одна й та сама невдача з'являється повторно
• перевірка людиною стає вузьким місцем

Мета обв'язки — не зробити демо складнішим.

Вона полягає в тому, щоб зробити реальну роботу надійною.

Справжній зсув

Перше покоління AI-продуктів було побудовано навколо підказок.

Наступне покоління будується навколо середовищ.

Питання більше не лише:

Як зробити відповідь моделі кращою?

Воно звучить так:

Як побудувати систему, де хороші дії є легкими, небезпечні дії контрольовані, невдачі видимі, а завершення доведене?

Це і є зсув від інженерії підказок до інженерії обв'язки.

Модель забезпечує інтелект.

Обв'язка забезпечує структуру.

Разом вони створюють надійне виконання.

Якщо ваш агент продовжує розвалюватися, перестаньте додавати прикметники до підказки.

Побудуйте середовище, яке йому потрібне для успіху.

Якщо ви дочитали до цього місця

Закладіть цей посібник.

Підпишіться на @LunarResearcher на X

Підпишіться на мій Substack

Надішліть цю статтю комусь, хто все ще намагається виправити кожну невдачу агента довшою підказкою.