Harness Engineering: Полное руководство по созданию надежных AI-агентов

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

Когда агент терпит неудачу, они переписывают промпт.

Когда он снова терпит неудачу, они добавляют больше инструкций.

Прежде чем мы начнем:

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

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

Но многие сбои агентов — это не сбои в рассуждении.

Это сбои в среде.

Агент не знал, какие файлы важны.

Он использовал правильный инструмент в неправильном месте.

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

Он заявил об успехе, не выполнив проверки.

Он повторил действие после частичного сбоя.

У него было разрешение сделать то, что должно было требовать одобрения.

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

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

И ее проектирование становится отдельной инженерной дисциплиной.

Инженерия обвязки (Harness Engineering) — это практика построения среды, которая превращает интеллект модели в надежную работу.

Промпт меняет одну попытку.

Обвязка меняет каждую попытку.

Это руководство объясняет, как построить такую обвязку.

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

Отправьте эту статью тому, кто все еще пытается исправить каждый сбой агента более длинным промптом.