Харнес — це продукт: практичний посібник з використання харнесів у агентському ШІ.
Дізнайтеся, що таке агентський харнес та складаються з яких семи елементів — від інструментів та контексту до правил та механізмів оцінки, а також про підагентів, способи збоїв та корисні фреймворки.
Джерела: The Harness Is the Product: An End-to-End Guide to Harnessing in Agentic AI
Уявіть собі, що ви даєте одну й ту саму модель мови двом різним командам. Команда А створює агента, який виправляє помилки у величезному репозиторії, запускає набір тестів та подає охайний запит на об’єднання коду. Команда Б створює чат-асистента, який втрачає контекст розмови вже після кількох повідомлень та із задоволенням вигадує внутрішню політику компанії. Ваги моделі ідентичні, проте результати кардинально відрізняються.
Цей „комплект“ — це фреймворк: все, що створюється навколо моделі. Він включає цикл, який дозволяє моделі діяти, інструменти, які вона може використовувати, механізми керування її вікном контексту, захисні механізми, які запобігають вчинкам, що можуть завдати шкоди, та зворотний зв’язок, який повідомляє її про те, чи досягає вона успіху. Те, що йде далі, починається з нуля, пояснює, що таке агент, та детально розглядає складові цього фреймворку, моделі виробництва, такі як підагенти та процеси компактизації, кілька відомих систем та сучасні фреймворки. Попередній досвід роботи з агентами не потрібен.
Основи
Що означає штучний інтелект-агент
Без усіх експресій, агент — це просто:
Агент — це мовна модель, яка працює в циклі, використовуючи інструменти, поки не досягне поставленої мети.
Для цього потрібні три компоненти: модель, яка може міркувати та обирати наступний крок, інструменти, які модель може використовувати, такі як пошук у Інтернеті, доступ до файлів, виконання коду, пошук у базі даних чи надсилання електронних листів, а також цикл, який повертає результат кожного інструменту, щоб модель могла вирішити, що робити далі.
Чат-бот відповідає один раз та зупиняється. Агент продовжує роботу: він виконує дію, оцінює результат, а потім виконує ще одну. Саме цей цикл робить текстовий прогнозувач здатним виконувати реальну роботу, а решта цього тексту розглядає цей механізм детальніше.
Що таке «харнес»
Уявіть собі «харнес» як середовище виконання для цього циклу. Модель вирішує, що має відбутися далі, тоді як «харнес» здійснює це та забезпечує безпеку, доступність, прозорість та контроль над усім процесом. Назва нагадує тестовий харнес у програмному забезпеченні чи стріпку на коні: потужність потребує структури, щоб бути спрямованою на корисну роботу.
У конкретних термінах цей механізм виконує запити інструментів до моделі, контролює те, що бачить модель на кожному кроці, забезпечує дотримання дозволів, обробляє збої, повторні спроби та нескінченні цикли, відстежує прогрес та визначає, коли завдання завершено, а коли потрібно зупинитися та звернутися до людини.
Один корисний спосіб уявити це: у моделі немає пам’яті між запусками. Кожного разу, коли її запускають, вона починає з чистого аркуша, читає наданий текст та формує один результат. Усе інше — скрипт, елементи сцени, захисні механізми — це саме цей механізм. Якщо змінити їх розташування, один і той самий „актор“ буде діяти зовсім по-іншому.
Чому механізм має значення
Виділяються три практичні причини.
Показники ефективності моделей наближаються, тоді як показники інструментальних систем — ні. Моделі нового покоління стають все більш схожими за первинними характеристиками. У тестах, які оцінюють здатність вирішувати реальні проблеми програмного забезпечення, одна й та сама модель може показувати значно різні результати лише через наявність кращих інструментів, формулювань запитів та механізмів зворотного зв’язку. У певний момент саме ці інструменти стають вирішальним фактором.
Довгі завдання посилюють вплив навіть незначних помилок. Якщо модель є на 99 відсотків надійною на кожному кроці, завдання з 50 кроками вдається виконати лише приблизно у 60 відсотках випадків, адже 0,99 у степені 50 дорівнює приблизно 0,605. Перевірка, повторні спроби, контрольні точки та корекція траєкторії є механізмами, які допомагають протидіяти цьому ефекту наростання помилок. Саме вони відрізняють демо-версію від готового продукту.
Свобода потребує обмежень. Будь-який агент, який може виконувати команди шеллу, переміщувати гроші чи спілкуватися з клієнтами, має мати обмеження на права доступу, сандбокси та журнали аудиту. Ці елементи є частиною інструментарію, а модель не надає жодного з них.
Анатомія інструментарію
Агенти для кодування, досліджень та підтримки зазвичай мають сім спільних компонентів. Ось вони по черзі.
1. Системний запит, постійні інструкції
Тут агенту пояснюють його роль, обмеження, правила поведінки та призначення кожного інструменту. У зрілих продуктах цей текст налічує тисячі слів та підтримується з такою ж ретельністю, як і вихідний код, з урахуванням тону, безпеки, моменту, коли потрібно запитати, та способів роботи з нечіткими інструкціями.
Початківець може написати один рядок про те, що агент є корисним асистентом з програмування. Натомість інструкція для роботи вказує конкретні процедури: відкривати файл перед його редагуванням, вдаватися до невеликих змін, запускати тести після кожної зміни, зупинятися та повідомляти про проблеми після двох невдалих спроб тестування, а також ніколи не вносити зміни безпосередньо у головну гілку, а потім йдуть ще багато подібних правил.
2. Шар інструментів, „руки“
Інструмент — це функція, яку модель може викликати; вона визначається ім’ям, описом та схемою типів для її аргументів. Модель запитує виконання цієї функції у структурованому форматі, після чого інструмент її виконує та надсилає результат назад.
Проектування інструментів — це недооцінена галузь. Це, по суті, проектування API для дуже прямолінійного користувача:
- Описи виступають у ролі інструкцій. Модель обирає інструменти на основі їхніх описів, тому нечіткий опис може призвести до вибору неправильного інструменту.
- Кілька добре сформованих інструментів кращі, ніж багато перекриваючих один одного. Надмірна кількість інструментів заплутує моделі так само, як меню з сорока статтями заплутує клієнтів.
- Повертайте помилки, з якими може працювати модель. Повідомлення про те, що файл є лише для читання та що спочатку потрібно отримати дозвіл на доступ, краще за сухий запис стек-трейсу.
- Зробіть небезпечні інструменти обмеженими. Інструмент, який надсилає лише попередньо схвалені чернетки, набагато безпечніший, ніж той, що виконує довільний код.
Важливим досягненням у цій галузі є Protocol Model Context, який Anthropic оприлюднив у відкритому доступі наприкінці 2024 року, і його вже прийняла більшість компаній галузі. Він стандартизує спосіб, яким постачальники інструментів роблять їх доступними для будь-якого агента, фактично створюючи універсальний з’єднувач: достатньо написати інтеграцію один раз, щоб використовувати її в будь-якому середовищі.
3. Управління контекстом, робоча пам’ять
Вікно контексту — це весь перцептивний світ моделі. Його обсяг зазвичай становить від сотень тисяч до мільйона токенів, що здається величезним, поки агент не прочитає сорок файлів та не виконає шістдесят команд.
Вибір того, що модель бачитиме на кожному кроці, ймовірно, є найважливішим елементом системи, і фахівці тепер називають це інженерією контексту, яка переважно замінила інженерію запитів як основну навичку. Техніки варіюються від простих до складних: обрізка (зберігання лише останніх повідомлень або частини файлу), пошук (індексування бази знань та отримання лише необхідної інформації) та компактування. За допомогою компактування, коли обсяг вікна майже досягає межі, модель створює узагальнення сеансу; це узагальнення замінює первинний запис, і робота продовжується. Саме так агенти можуть працювати над завданням годинами.
4. Пам’ять — довгострокове зберігання
Контекст триває протягом однієї сесії, а пам’ять зберігається. Зазвичай її структурують на кілька рівнів:
- пам’ять про проект, наприклад, файли інструкцій у репозиторії, які навчають агента програмування ваших стандартів та команд будування та читаються на початку сесії,
- пам’ять користувача, тобто уподобання, сформовані під час різних розмов,
- епізодична пам’ять, яка зберігає записи про попередні виконання, часто у векторному сховищі, щоб їх можна було відновити при повторенні схожих ситуацій.
5. Механізми контролю, дозволи та ізоляція, гальма
Шар безпеки постійно перевіряє, чи справді потрібно виконати певну дію. На практиці це означає:
- Рівні дозволів. Читання відбувається вільно, запис потребує перевірки політики, а незворотні дії, такі як розгортання, надсилання, видалення чи оплата, вимагають прямої схвалення людини.
6. Перевірка та зворотний зв’язок — очі
Ніщо не покращує роботу агента надійніше, ніж можливість перевірки його власних результатів. Агенти, які займаються програмуванням, компілюють код, перевіряють його на помилки та запускають тести після кожної зміни. Дослідницькі агенти порівнюють твердження з кількох джерел. Агенти браузера фіксують екран, щоб побачити, що насправді завантажилося. Деякі системи додають ще одну модель-рецензента, яка оцінює відповідь першої моделі за певними критеріями перед тим, як її прийняти.
Це безпосередньо вирішує проблему кумулятивних помилок. Агент, який може бачити, що він зазнав невдачі, може спробувати знову, тоді як той, хто не може цього, буде без вагань передавати некоректні дані.
7. Спостережуваність, «блокнот польотів»
У продакшені кожен запит до моделі, кожен виклик інструменту та кожен витрачений токен фіксуються. За допомогою цих слідів можна повторно запустити неуспішну операцію, визначити крок, який пішов не так, та виправити проблемний запит, інструмент чи політику. Навколо цього сформувалася ціла категорія продуктів, зокрема LangSmith, Langfuse, Braintrust та стандарти OpenTelemetry для генеративного ШІ, адже відлагоджувати агента без можливості спостереження так само складно, як відлагоджувати розподілені сервіси без журналів подій.
Ефективне виконання циклу
Назвати компоненти — це проста частина. Різниця між системою, яка витримує демонстрацію, та тією, яка працює стабільно протягом звичайного робочого дня, полягає у наступних практиках.
Планування, дія, перевірка
Прості агенти починають роботу миттєво. Більш розвинені інструменти забезпечують певний ритм: складається план шляхом розбиття мети на список завдань, робляться невеликі кроки, перевіряється кожен результат перед подальшою роботою, потім план коригується та процес повторюється. Письмовий план виконує дві функції: він допомагає моделі зосереджуватися на тривалих завданнях, оскільки його перечитують щоразу, а також дозволяє спостерігачеві бачити прогрес у реальному часі, що виявляється ціннішим, ніж очікувалося.
Структуровані результати
Кожного разу, коли програма буде використовувати результати роботи моделі, їх слід обмежити за допомогою схеми. Сучасні API підтримують примусові виклики інструментів та генерацію, перевірену за схемою. Проза призначена для людей; код має мати структуру.
Витрати та затримки
Агенти швидко витрачають токени, що робить економіку ресурсів важливою проблемою. Зберігання в кеші великого статичного префікса (системного запиту та визначень інструментів) між раундами коштує значно менше, ніж його повторна передача, що є великою перевагою під час тривалих сеансів. Механізм маршрутизації направляє рутинні кроки до невеликої, швидкої моделі, а модель вищого рівня залишається для кроків, що вимагають логічних міркувань. Незалежні підзавдання, такі як читання десяти файлів або перевірка п’яти джерел, можуть виконуватися одночасно.
Багатоагентні системи та ще більше
Підагенти та оркестрація
Коли завдання перевищують обсяг одного вікна контексту, системи переходять на багатоагентну архітектуру. Оркестратор ділить мету та створює підагентів, кожен з яких має свіжий контекст, часто обмежений набір інструментів та чітко сформульовані завдання. Кожен підагент виконує свою роботу та повертає лише свій висновок, а не всю історію виконання завдань.
Справжня перевага є менш очевидною, ніж швидкість: кожен підагент працює у власному ізольованому контексті, а не просто паралельно. Десять підагентів можуть кожен заповнити ціле вікно однією підсистемою, тоді як оркестратор зберігає лише десять коротких узагальнень.
Поширені топології включають оркестратора та працівників (що є найпоширенішим варіантом), конвеєри, такі як «проект», «критика» та «редагування», а також дискусійні групи, у яких кілька агентів незалежно вирішують проблему, а суддя узагальнює відповіді. Дискусії є ресурсоємними, але підходять для складних запитань.
Команди, які створили цей звіт, отримали кілька важливих уроків:
- Вкажіть очікуваний рівень зусиль для кожного завдання, інакше навіть тривіальне запитання може спричинити десятки пошуків.
- Пишіть інструкції, які є детальними та самодостатніми, адже підагент не може бачити контекст батьківського агента.
Створення контрольних точок та стійкість
Агенти, які працюють протягом тривалого часу, можуть зазнати збоїв через аварії, обмеження швидкості та необхідність перезапуску. У продакшн-середовищах використовується стан контрольних точок, який враховує хід роботи, список завдань та результати використаних інструментів, щоб процес міг продовжитися з 37-го кроку без необхідності початку знову. Це сфера діяльності стійких двигунів робочих процесів, і кілька фреймворків агентів побудовані безпосередньо на цій основі.
Evals – набір тестів для цього інструментарію
Поведінка агента є ймовірнісною, тому запит, який працює у понеділок, може зазнати невдачі у вівторок. Сильні команди тримають набір засобів оцінки, який містить від десятків до тисяч реалістичних завдань, результати яких можна автоматично перевірити. Чи пройшли тести, чи була знайдена правильна відповідь, чи залишився бюджет у межах ліміту? Будь-які зміни до запитів, нові інструменти та заміна моделей проходять перевірку через цей набір перед випуском. Він виконує ту саму функцію, що й CI/CD в інших сферах, а його ігнорування означає роботу без відповідних інструментів.
Використання комп’ютера — фінальний іспит
На передовій агентам надають екран, клавіатуру та мишу, і вони можуть керувати будь-яким додатком, незалежно від наявності у нього API. Це підвищує складність усіх попередніх проблем: скріншоти споживають величезну кількість токенів, тому контроль контексту має бути суворим; неправильний клік може завдати серйозної шкоди, тому дозволи посилюються; а перевірка означає фактичне переглядання екрана після кожного кроку.
Як відомі системи застосовують ці ідеї
Claude Code — інструмент для програмування. Це компактний приклад хорошого дизайну. Набір інструментів є невеликим, але потужним: він дозволяє читати, записувати та редагувати файли, виконувати команди оболонки та шукати код, без сотень дрібних інструментів. Перевірка є ключовою: він запускає компілятори, інструменти перевірки коду та тести та повторює спроби при їхніх помилках. Файл інструкцій проекту виконує функцію пам’яті. Жоден з цих елементів не є можливістю моделі, і саме тому та сама модель в ньому поводиться інакше.
Продукти глибоких досліджень, інструментарій для досліджень. Інструменти досліджень великих лабораторій перетворюють запит на автономне дослідження, яке триває кілька хвилин та завершується звітом із посиланнями. Їхньою особливістю є попередньо розроблений план дослідження, який іноді представляється на затвердження, що дозволяє залучити людину на найдешевшому етапі перед початком дорогого процесу. Механізми пошуку аналізують результати, виявляють прогалини та продовжують пошук, а метадані посилань супроводжують факти протягом усього процесу обробки.
Manus та школа проєктування контексту. Команда Manus опублікувала надзвичайно відверті примітки щодо внутрішньої структури інструменту напередодні його запуску у 2025 році, і кілька з цих положень отримали широке поширення. Розглядайте кеш KV як обмеження проєктування: зберігайте початок запиту стабільним (без часової мітки у верхній частині системного запиту), оскільки кількість токенів вхідних даних може значно перевищувати кількість токенів вихідних даних. Уникайте додавання чи видалення інструментів під час сеансу, адже це унеможливлює використання кешу та спричиняє плутанину у моделі, коли попередні запити згадують зниклі інструменти; тримайте список інструментів незмінним та маскуйте ті, які наразі можна обрати.
Курсор та інструментарій IDE. Редактор, створений з урахуванням технологій ШІ, демонструє іншу філософію глибокої інтеграції з середовищем. Він використовує семантичний індекс кодової бази редактора для швидкого пошуку, зберігає зміни у вигляді дифів для перегляду, щоб особа, яка схвалює об’єднання, була частиною моделі дозволів, прихованої під інтерфейсом, запускає фонові агенти на окремих гілках та передає результати перевірки формату та лінтера назад у цикл. Ті самі сім компонентів проявляються у різній формі.
Агенти підтримки в компаніях, де ключовим є дотримання правил. Агенти, які працюють безпосередньо з клієнтами, змінюють пріоритети: уникнення неправильних дій має більше значення, ніж просто технічні можливості. Тому вони починають із чітких обмежень: робота лише з схваленими знаннями, перевірка дій за схемами бізнес-систем (обмеження на повернення коштів, спочатку підтвердження особи), обов’язкова передача завдань іншим спеціалістам при низькому рівні впевненості та повні журнали аудиту. У регульованих секторах такі правила фактично є самим продуктом.
Фреймворки та інструменти, які є зараз у наявності
Сьогодні рідко створюють такі системи лише за допомогою базових API-викликів. Ось поширені варіанти, згруповані за філософією роботи:
- Claude Agent SDK. Це система, яка лежить в основі Claude Code; вона надається у вигляді бібліотеки з можливостями виконання циклів, використання інструментів, роботи з підагентами, налаштування прав доступу та стиснення даних. Найкраще підходить для швидкого створення потужних агентів на платформі Claude.
- OpenAI Agents SDK. Легкі інструменти для агентів, передачі завдань, обмежень, сеансів та відстеження. Ідеально підходить для багатоагентних додатків у екосистемі OpenAI.
- LangGraph. Агенти як явні машини станів із функціями зберігання стану, перериваннями з участю людини та стабільною роботою. Найкраще підходить для складних, контрольованих довготривалих робочих процесів.
- CrewAI. Команди на основі ролей, такі як дослідник та автор. Ідеально підходить для швидкого створення прототипів з багатьма агентами та обробки контенту.
- AutoGen, AG2 та Semantic Kernel. Багатоагентна робота, орієнтована на розмову, яка поєднується у корпоративні інструменти. Найкраще підходить для проектів на .NET та Azure, а також для дослідницьких експериментів.
- smolagents. Мінімалістична бібліотека, де агенти пишуть код у вигляді своїх дій. Ідеально підходить для гнучких рішень із відкритими моделями.
- Pydantic AI. Агенти з безпекою типів та схемою на першому місці з перевіреними результатами. Ідеально підходить для команд, які працюють з Python та хочуть суворої типізації.
- Vercel AI SDK. Примітиви на основі TypeScript із можливістю керування циклом агента. Найкраще підходить для інженерів веб-продуктів у екосистемі JavaScript.
Навколо цього існує „з’єднувальна тканина“: MCP для стандартних інструментів, платформи для трекінгу та оцінки, міцні двигуни виконання та провайдери сандбоксів для безпечної експекувації коду.
Порада щодо вибору: під час навчання напишіть самостійно простий цикл, використовуючи API моделі, цикл while та два інструменти — приблизно у сто рядків. Після цього жодна фреймворк не здаватиметься чимось магічним, а саме це і мета. Під час розробки продукту оберіть фреймворк, який найбільше відповідає вашому постачальнику моделей та мові, та витратьте заощаджений час на те, чого не може надати жоден фреймворк — а саме на ваші інструменти, процедури оцінки та правила безпеки.
# The whole idea, in miniature
while not done:
response = model.generate(context, tools) # model decides
if response.tool_calls:
results = execute(response.tool_calls) # harness acts (safely!)
context = manage(context + results) # harness curates memory
else:
done = verify(response) # harness checks the work
Способи збою
Ось типові причини збоїв агентів, кожна з яких супроводжується відповідним рішенням:
- Занепад контексту. Вікно поступово заповнюється застарілими результатами роботи інструментів, що призводить до падіння якості, поки через кілька годин мета не забувається. Рішення: компактизація інформації, ведення нотаток та періодичне повторення цілі.
- Цикли загибелі. Та сама неефективна команда повторюється без кінця, що коштує кілька центів за кожну спробу. Лікування: виявлення циклів, встановлення лімітів на ітерації та примусова зміна стратегії.
- Розрізненість інструментів. При наявності сорока схожих інструментів модель обирає неправильний у найгірший момент. Рішення: використання меншої кількості більш ефективних інструментів із чіткими описами.
- Вставка команд. Текст на веб-сторінці чи в електронному листі просить агента проігнорувати його інструкції та видалити базу даних, і оскільки агент не може за своєю природою розділяти дані та команди, він може підкоритися. Захід: фільтрація вхідних даних, інструменти з мінімальними правами, сандбокси та людське схвалення для значущих дій; застосовуються кілька рівнів захисту, оскільки жоден окремий захід не є надійним.
- Хибне повідомлення про завершення. Агент повідомляє про успіх, хоча робота ще не завершена. Захід: перевіряйте результати за допомогою незалежних засобів та не дозволяйте агенту самостійно позначати свою роботу як завершену.
- Неконтрольовані витрати. Багатоагентна робота може тихо збільшити рахунок у багато разів. Захід: бюджетування, маршрутизація, кешування та уважний аналіз того, чи б вистачило одного здатного агента.
- Поступова зміна функціоналу без змін у коді. Оновлення моделі змінює її поведінку, і запити, налаштовані під попередню версію, перестають працювати. Рішення: запускати набір тестів після кожної зміни.
Що варто пам’ятати
Модель забезпечує інтелект, а інфраструктура перетворює його на результати роботи. Інфраструктура складається з основної структури та семи компонентів: постійних правил, інструментів, керування контекстом, пам’яті, механізмів контролю, перевірки та можливості спостереження. Навколо цих компонентів існують шаблони для виконання довгострокових завдань, такі як планування, виконання та перевірка, стиснення даних, контрольні точки, підагенти та тести. Більшість проблем з агентами пов’язані з проблемами інфраструктури, а більшість покращень — з покращенням інфраструктури. Тож, коли агент працює неефективно, спочатку перевірте інфраструктуру, а вже потім змінюйте модель.
Пов’язана література
- Підагенти на практиці: ролі, бюджети, заборони та беззвучні невдачі — Як створювати стабільні підагенти Claude Code: ролі, файли передачі даних, стан виконання, бюджети, заборони, перевірки на беззвучні невдачі та допоміжні інструменти Copilot, на основі агентів, які використовуються у десятках репозиторіїв.
- Агентні аналітики — це більше, ніж просто текст у форматі SQL: уроки від Anthropic — Що говорить стаття Anthropic про самообслуговувані аналітичні інструменти щодо семантичних шарів, навичок, оцінок та основ даних, та чому сам текст у форматі SQL створює хибне враження точності.