Поставил себе новый GitHub-kit для Hermes и хочу разобрать, зачем он вообще нужен. Решает он скучную, зато дорогую проблему: как из размытой задачи для агента собрать понятный рабочий цикл, который не превратится в черный ящик.
Agent Loop Engineering Kit - это набор файлов и CLI hermes-loop, который превращает мутный промпт для агента в проверяемый цикл: триггер, источники данных, разрешения, точки approval, проверки и receipt. Сам он агента не запускает и Hermes не заменяет. У меня на локальной проверке прошли 22 теста, privacy scan чистый, а специально кривой пример честно падает на safety gate.
- Kit готовит цикл работы агента до автоматизации, а не вместо Hermes.
- Внутри loop spec, схемы, шаблоны, safety gates, классы риска L0-L5, privacy scan, dry-run и receipt.
- Порядок один: сначала цикл, потом проверка, потом dry-run, потом receipt.
- Cron, вебхук, Kanban и GitHub-автоматизацию подключают в самом конце.
- Лицензия MIT, нужен Python 3.11+, ставится через uv или pipx.
Ссылка на репозиторий: github.com/AlekseiUL/agent-loop-engineering-kit. Дальше по порядку, что это и зачем.
Что такое Agent Loop Engineering Kit
Это инструмент для проектирования повторяемых задач агента Hermes. Берет расплывчатый промпт и заставляет описать его как ограниченный цикл: что его запускает, какое у него состояние, чем ему можно пользоваться и когда он обязан остановиться.
Покажу на простом. Вы хотите "каждое утро делай мне бриф". В чате это обычный запрос, и для разового случая хватает за глаза. А вот если агент должен собирать бриф каждый день без вас, одного промпта уже мало. Надо заранее ответить на семь вопросов:
- что его запускает;
- откуда он берет данные;
- куда ему можно ходить;
- куда нельзя;
- где нужен мой approval;
- как проверить результат;
- и где потом посмотреть, что он реально сделал.
Kit как раз про эти вопросы. Он не работает за вас и не подменяет собой runtime. Это слой подготовки: описать правила игры, проверить их, прогнать вхолостую и получить нормальный отчет.
Почему хороший промпт не спасает
Промпт описывает намерение, но молчит про границы. Агент в цикле крутится без вас, и тут важно ведь не "что я хочу", а "что ему видно, что он может трогать, что должен вернуть и где остановиться". Идеальная формулировка задачи всего этого не задает.
Без явного цикла легко получить знакомую картину: агент сидит в cron, что-то делает, жжет токены и в конце пишет "готово". А проверить это "готово" нечем. Вы не видите, куда он ходил, что менял и почему решил, что закончил. Получается дорогой черный ящик, которому остается верить на слово.
Что входит в kit
Внутри лежит все, чтобы описать и проверить цикл до запуска. Не один файлик с инструкцией, а связанный набор: спецификация, схемы под нее, шаблоны и проверки.
| Компонент | Зачем нужен |
|---|---|
| Loop spec | Главный документ цикла: триггер, входы, состояние, разрешенные инструменты, запреты, проверки, точки approval и условия остановки. |
| Схемы (schemas) | YAML-схемы для loop spec и записи о запуске. По ним идет валидация, чтобы спека не разъезжалась. |
| Шаблоны (templates) | Заготовки спеки, плана активации и receipt, чтобы не начинать с пустого листа. |
| Safety gates | Проверки безопасности: опасный цикл не проходит дальше и падает на этом шаге. |
| Risk classes | Классы риска от L0 до L5: чем сильнее побочные эффекты, тем строже правила. |
| Privacy scan | Сканирование на утечки секретов и лишних путей в спеке и артефактах. |
| Dry-run | Холостой прогон цикла без реальных действий, чтобы увидеть поведение заранее. |
| Receipt | Читаемый отчет о запуске: статус, результат проверок, причина остановки, побочные эффекты. |
| CLI hermes-loop | Командная утилита, которая все это связывает: init, validate, score, dry-run, render-receipt, privacy-scan. |
Ставится kit на Python 3.11+ через uv или pipx, лицензия MIT. После установки проверка одной командой: hermes-loop --help.
Классы риска: от L0 до L5
Классы риска - способ сразу понять, насколько опасен цикл и что ему вообще разрешено. Чем выше класс, тем серьезнее последствия и тем строже проверки. Верхний уровень просто заблокирован.
| Класс | Что делает цикл |
|---|---|
| L0 | Разовая задача только на чтение, совет без действий. |
| L1 | Повторяемые отчеты только на чтение. |
| L2 | Пишет только локальное состояние. |
| L3 | Редактирует файлы и репозитории. |
| L4 | Внешние побочные эффекты, выход наружу. |
| L5 | Финансы, секреты, удаления. Заблокирован. |
Удобно тем, что вы не на глаз прикидываете "ну вроде безопасно", а сразу относите цикл к классу и видите правила для него.
Как выглядит рабочий процесс
Процесс линейный, от пустого шаблона до отчета. Каждый шаг - отдельная команда CLI, и проскочить проверку перед запуском не выйдет.
- init - создать заготовку loop spec из шаблона.
- validate - проверить схему и safety gates.
- score - оценить инженерное качество цикла в баллах.
- dry-run - прогнать вхолостую и получить запись о запуске.
- render-receipt - собрать из нее читаемый отчет.
- privacy-scan - проверить на утечки секретов и путей.
- Первый реальный прогон в Hermes делается руками и только на чтение.
- План активации заполняется отдельно, и лишь потом включают расписание.
Что я проверил локально
Поставил kit к себе и прогнал основные сценарии. Хотел убедиться, что проверки не для галочки и плохой цикл правда не проходит.
- 22 теста прошли;
- privacy scan чистый;
- нормальные примеры валидируются;
- dry-run по утреннему брифу собрал читаемый receipt.
- кривой пример честно падает на safety gate;
- цикл, который лезет редактировать репозиторий из крона, дальше не идет.
Тут важна именно вторая колонка. Если бы кривой пример проходил, грош цена всей затее. А так видно: гейты держат, и опасную конфигурацию проще поймать на этапе спеки, чем потом ловить в проде. Dry-run по утреннему брифу, кстати, собрал вполне читаемый receipt - видно, куда цикл ходил и почему остановился.
Для каких задач это нужно
Kit нужен там, где задача должна повторяться без вашего постоянного присмотра. Для разового вопроса он избыточен, а для регулярного цикла - в самый раз. Мои кандидаты:
- ежедневные брифы;
- регулярный ресерч по теме;
- диагностика и здоровье системы;
- обслуживание репозитория;
- coding-fix loop, где агент чинит и проверяет себя;
- watchlist по источникам, который следит за обновлениями.
Общее у всех одно: это не "ответь один раз", а "делай это снова и снова по правилам". Где есть расписание и побочные эффекты, там цена ошибки растет, и описанный цикл себя окупает.
Чего kit не делает
Это не runtime и не замена Hermes. Он готовит и проверяет цикл, но сам ничего не запускает. Граница важная, поэтому разнесу ее явно.
- описывает цикл как спеку;
- валидирует схему и гейты;
- гоняет dry-run;
- собирает receipt;
- сканирует на утечки.
- не выполняет реальные задачи агента;
- не создает cron, вебхуки и Kanban в Hermes;
- не пишет в профили, память и скиллы;
- не заменяет планировщик и шлюз;
- не доказывает, что ответ модели верный.
Частые вопросы
Это замена Hermes?
Нет. Kit не runtime и не планировщик. Он готовит и проверяет цикл до того, как вы дадите задаче расписание и свободу. Реальный запуск остается за Hermes.
Что нужно для установки?
Python 3.11 и выше плюс uv или pipx. Лицензия MIT. После установки работоспособность проверяется командой hermes-loop --help.
Зачем dry-run, если можно просто запустить агента?
Холостой прогон показывает поведение цикла без реальных побочных эффектов и сразу отдает receipt. Дешевле увидеть проблему на этом шаге, чем ловить ее в проде после запуска по расписанию.
Что такое safety gate простыми словами?
Это проверка, которая не пропускает опасный цикл дальше. Например, конфигурацию класса L5 с удалениями или работой с секретами она блокирует, и спека просто не проходит валидацию.
Для чего нужен receipt?
Receipt - это читаемый отчет о запуске: статус, результаты проверок, причина остановки и побочные эффекты. Он заменяет слепое доверие к слову "готово" нормальным следом того, что агент реально сделал.
Итог
Если совсем коротко, перед автоматизацией нужен понятный цикл, иначе получите черный ящик, который жрет токены и пишет "готово". Сначала цикл, потом проверка, потом dry-run, потом receipt. И только после этого стоит думать про cron, вебхук, Kanban или GitHub-автоматизацию.
Репозиторий kit лежит на GitHub: github.com/AlekseiUL/agent-loop-engineering-kit.
