Harness Engineering 101: побудова надійного середовища виконання ШІ-агентів з нуля
Новий відкритий посібник детально розбирає анатомію автономних агентів: stateless LLM як мозок і harness-обв'язку як тіло. У 16 розділах автор покроково розбирає контекстні масиви, MCP та ізоляцію робочих процесів.
Чому це важливо
Опануйте базову архітектуру обв'язок, щоб відмовитися від громіздких фреймворків і створювати власні детерміновані цикли виконання для Claude та Cursor.
TL;DR
- 01Моделі повністю позбавлені власної пам'яті; автономність забезпечується менеджментом масиву контексту.
- 02Усі популярні агентні фреймворки є обгортками навколо циклу надсилання повідомлень і виклику інструментів.
- 03Ізольовані Git worktrees вирішують проблему конфліктів файлової системи під час одночасного запуску кількох агентів.
Ключові факти
- Обсяг коду
- ~300 рядків коду на Python для базового прототипу
- Кількість розділів
- 16 глав плюс 4 технічні додатки
- Ліцензія коду
- MIT License
- Ліцензія тексту
- CC BY-NC-ND 4.0
Ментальна модель агентної системи
Будь-який API сучасних LLM є stateless: під час кожного запиту розробник передає повну історію розмови у вигляді JSON-масиву. Агентний каркас (harness) — це програма, що збирає, підтримує та захищає цей масив. Більшість популярних бібліотек є лише надбудовами над цим простим циклом.
Архітектурні етапи посібника
Книга розділена на 16 розділів із практичними зразками на Python:
- Частини I та II (Робота під навантаженням): Боротьба з деградацією контексту, стратегії очищення токенів і синхронізація асинхронних викликів системного оточення.
- Частина III (Екосистема): Робота з Model Context Protocol (MCP), відкладене завантаження скілів та перехоплювачі життєвого циклу (hooks).
- Додатки (Продакшн-інфраструктура): Маршрутизація між дешевими та флагманськими моделями, ізоляція агентів через Git worktrees та обробка ретраїв під час стрімінгу.
Встановлення та запуск
Текстова частина поширюється за ліцензією CC BY-NC-ND 4.0, а вихідний код прикладів ліцензовано під MIT.
Спробуй за 2 хвилини
# Clone and preview the interactive guide locally
git clone https://github.com/IsuruMaduranga/harness-engineering-101.git
cd harness-engineering-101
cargo install mdbook mdbook-mermaid
mdbook serve --openbash
✓ Коли використовувати
- Використовуйте для налагодження неочевидних багів із втратою стану в циклі агентів.
- Застосовуйте для розробки персональних легковикових агентів без зайвих зовнішніх залежностей.
✕ Коли НЕ варто
- Не використовуйте, якщо вам потрібен простий одноразовий CLI-скрипт для одиночного запиту до LLM.
- Не замінюйте готові ентерпрайз-стеки, якщо у вашій системі вже налаштовано моніторинг та безпеку.
Що зробити сьогодні
- Склонуйте репозиторій для аналізу покрокової реалізації агентного циклу на чистому Python.
- Розділіть логіку виклику інструментів та очищення контексту у власних проектах.
- Використовуйте тимчасові Git worktrees для ізоляції паралельних агентів у файловій системі.
Що каже спільнота
“Can’t recommend making your own harness enough. Even a trivial toy harness will clarify a lot of concepts that I see people confuse all the time (especially here on HN).”
“I gave myself three days to see if I could make a harness that was complete enough to work on my own projects. It was usable in less than a day. I love using it, because I know exactly what its boundaries are.”