Розробка системи версіонування AI-агентів (Agent Versioning)

Чому без системи версіонування AI-агентів ламається експлуатація

Типовий збій виглядає буденно: інженер править формулювання в системній інструкції агента й викладає її в прод без перевірки й без сліду в історії.

За добу просідає частка коректних відповідей на потоці заявок, надходять скарги від користувачів, а сказати, яка версія інструкції працювала до правки, нічим — у репозиторії лежить код, але не стан агента. Інцидент в експлуатації розбирають за логами діалогів, тобто за непрямими ознаками.

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

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

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

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

Звідси типова картина: система версіонування AI-агентів або відсутня, або зведена до журналу правок у текстовому файлі, який розходиться з реальністю вже за тиждень.

Розбираємо, як це закривається — версіями конфігурації, прив’язкою логів до конкретної версії та передбачуваним відкатом.

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

До версіонування відкат агента означав перезбирання середовища, ручне повернення промптів і описів інструментів та повторну перевірку зв’язок.

Тепер версія агента — це незмінний знімок: код оркестратора, тексти промптів, схеми інструментів, параметри конфігурації та версія моделі.

Відновлення зводиться до перемикання вказівника на попередній знімок — час відновлення агента вимірюється хвилинами, а не нічною роботою команди.

Частка невідтворюваних інцидентів падає, бо кожен запуск зберігається разом із версією та вхідними даними. Інженер бере ідентифікатор знімка з журналу й повторює сценарій у тому самому середовищі: розходження пояснюється даними, а не тим, що «щось змінили на стенді». Розбір із режиму здогадок переходить у режим порівняння двох зафіксованих станів.

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

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

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

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

Порівняння підходів: знімок, дельта й поступовий випуск

Вибір режиму визначається тим, що саме змінюється в агенті й як часто. Повний знімок стану агента фіксує системні інструкції, набір інструментів, схеми викликів і налаштування доступу до даних повністю — таку версію можна підняти через місяці, не відновлюючи історію правок. Промислові реєстри на кшталт MLflow за замовчуванням працюють саме зі знімками.

Дельта-версіонування зберігає лише відмінності між сусідніми версіями: правка інструкції важить кілька рядків, а не повний зліпок агента. Поступовий випуск версії розводить зберігання й розкатку — та сама збірка живе на частині трафіку, поки метрики не підтвердять якість.

Обмеження підходів проявляються на масштабі: знімки швидко роздуваються за щоденних правок, а дельти перетворюють відкат на крихку операцію.

Тому режими комбінують — знімок як база для аудиту й повернення, дельти для частих змін, поступовий випуск для підтвердження якості на частині трафіку. Далі розбираємо, як такий набір лягає на конкретний контур і що доведеться обмежити.

Етапи впровадження: від аудиту агентів до передачі регламентів

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

1. Аудит агентів. Збираємо повний перелік: де запущений, хто власник, які моделі та інструкції використовує, до яких зовнішніх сервісів звертається. На виході — карта залежностей і список агентів без відповідального, зазвичай це найризикованіші ділянки.

2. Схема версіонування. Фіксуємо, що взагалі вважається версією: інструкції, параметри генерації, набір інструментів, код обв’язки, прив’язка до даних. Кожному агенту — своя нумерація, незмінні збірки та явний зв’язок версії із середовищем, щоб тестове й робоче не розходилися.

3. Налаштування реєстру версій. Реєстр стає єдиним джерелом правди: метадані, артефакти, автор і час фіксації. Налаштовуємо політики зберігання та розподіл прав — розробник публікує, відповідальний за випуск просуває в робочий контур.

4. Перевірка відтворюваності. Проганяємо еталонні сценарії на зафіксованій версії та звіряємо відповіді й проміжні рішення. Розходження означає неявну залежність — наприклад, звернення до зовнішнього сервісу без версії.

5. Відкат і просування. Репетируємо повернення на попередню версію прямо в робочому контурі та замірюємо час до відновлення. Окремо перевіряємо, що відкат не ламає пов’язані агенти.

6. Передача регламентів. Віддаємо документацію, регламент випуску та правила іменування, навчаємо команду випускати версії самостійно. Далі зміни проходять за описаним процесом, а не з пам’яті інженера.

Що залишається на руках: реєстр версій і політики випуску

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

• Реєстр версій — на кожну збірку агента: ідентифікатор, склад моделі та інструкцій, підключені інструменти, автор випуску й перелік змін щодо попередньої версії.
• Схеми зв’язків — карта викликів між агентами та зовнішніми сервісами, точки передачі управління й даних, місця, де збій одного агента тягне за собою інших.
• Політики випуску — які перевірки обов’язкові до просування версії в робоче середовище, хто має право підписати випуск і що відбувається в разі провалу перевірки.
• Регламент відкату — покроковий порядок повернення до попередньої версії з переліком станів, які відкочуються разом із нею: пам’ять діалогів, індекси, черги завдань.
• Політики доступу — ролі та права на випуск, межі доступу агентів до внутрішніх даних і зовнішніх інструментів.
• Документація щодо агентів — призначення, межі застосовності, формати входів і виходів, відомі обмеження та типові помилки.
• Регламент розбору розходжень — як фіксується незбіг відповідей між версіями, хто розбирає, у які строки й як результат потрапляє в наступну збірку.

Кожен артефакт прив’язаний до версії та оновлюється разом із нею. Версія без опису й без записаного регламенту відкату вважається невипущеною — інакше реєстр швидко перетворюється на звалище записів, за якими не можна ні відкотитися, ні передати роботу.

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

Як випускали до впровадження

Агент збирався з одного «поточного» набору інструкцій, інструментів і параметрів — конфігурація лежала поруч із кодом сервісу, а попередні стани ніде не зберігалися.

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

Простій за такого інциденту сягав 40–60 хвилин, і приблизно кожен другий випуск потребував ручного втручання в робочий час.

Що змінили й що отримали

Версіонування винесли в окремий шар: версія агента — це незмінний набір інструкцій, доступних інструментів, схем даних і параметрів вибірки, жорстко пов’язаний із ревізією коду.

Артефакти й промпти фіксувалися в реєстрі на базі MLflow, а перемикання між версіями йде через конфігурацію середовища, без перезбирання сервісу. Перед випуском додано обов’язковий прогін за набором еталонних діалогів, а нова версія перші години обслуговує частину трафіку.

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

Простій сервісу за інциденту скоротився з 40–60 хвилин до 2–4, частка випусків із ручним втручанням — з половини до поодиноких випадків, а розбір збою тепер починається з питання «яка версія відповідала в цьому діалозі» й отримує точну відповідь за журналом.

Що робити, якщо агенти вже працюють без реєстру версій?

Починати варто не із зупинки контуру, а із запису того, що вже працює: агенти продовжують обслуговувати запити, а поруч з’являється журнал запусків — версія промпту, набір інструментів, схема входу й виходу, маршрут. Уже за кілька днів видно, які агенти змінювалися, хто правив і де саме ламалося.

Частину історії відновити не вдасться: конфігурації минулих версій ніхто не зберігав, тому точкою відліку стає поточний стан, а мітки ставляться лише на нові зміни. Це головний компроміс — реєстр не домалює минуле, але й не блокує роботу. Сценарій переходу вибирається за кількістю агентів і критичністю їхніх збоїв.

Поетапний перехід іде за критичністю: спочатку агенти, чиї збої критичніші за все інше. Кожен із них проганяється в тіні на копії трафіку, відповіді порівнюються з поточними, і перемикання робиться лише після збігу.

Відкат виконується за міткою версії — повернення займає хвилини замість годин на розбір і відновлення наосліп.

Питання інженерів: відкат, сумісність, доступи

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

Сумісність інтеграцій під час оновлення агента

Схеми входів і виходів інструментів версіонуються разом із агентом. Якщо нова версія змінює формат відповіді, зовнішні системи продовжують отримувати дані в попередньому контракті до планової міграції. Так оновлення агента не розриває обмін з обліковою системою, CRM або внутрішнім сервісом.

Як розмежовується доступ до версій і викатки?

Ролі розділені: розробник публікує версію лише в тестовий контур, переведення в продуктив робить відповідальний за викатку, а журнал фіксує автора, час і склад зміни. Промпти й налаштування не правляться руками на бойовому контурі — будь-яка зміна проходить той самий шлях.

Що робити, якщо зовнішня модель оновилася на боці постачальника?

Прив’язка до моделі зберігається у знімку версії, тому поведінка агента не змінюється непомітно. Прогін регресійних сценаріїв на фіксованому наборі діалогів показує розходження до перемикання, а не після.