Agent Versioning для AI-агентів: як безпечно релізити prompt, tools і policy

Ідея за 30 секунд

Agent versioning — це runtime-контроль, який фіксує, яку саме версію агента запускає кожен run: prompt, tools, policy і модель.

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

Проблема

Без версіонування нові зміни в prompt, tools і policy змішуються в один "поточний стан". У demo це майже не видно. У production стає незрозуміло, чому один run спрацював, а інший — ні.

Типові наслідки:

• неможливо точно відтворити інцидент
• складно зрозуміти, яка зміна зламала поведінку
• rollback перетворюється на ручну й ризикову операцію

І кожна хвилина без чіткої версії збільшує час розслідування інциденту.

Аналогія: це як деплой без номера версії. Поки все добре, проблема непомітна. Коли щось ламається, неясно, до чого саме повертатись.

Рішення

Рішення — зберігати агент як версійний пакет (version manifest) і запускати run тільки з pinned version_id. Кожен реліз проходить перевірку сумісності контрактів і rollout gate перед подачею трафіку.

Version policy layer повертає технічне рішення: allow або stop з явною причиною:

• contract_mismatch
• gate_failed
• rollback_required

Це окремий рівень системи, а не частина промпта чи логіки моделі.

Agent versioning ≠ rollback

Це різні ролі в системі:

• Versioning керує змінами до і під час rollout.
• Rollback повертає стабільну версію, коли нова вже дала регресію.

Одне без іншого не працює:

• без versioning rollback складно зробити точково
• без rollback навіть добрий versioning не рятує від production-інциденту

Приклад:

• versioning: support-agent@2.4.0 іде на canary 5%
• rollback: повернення на support-agent@2.3.3, якщо росте error rate

Компоненти versioning-контролю

Ці компоненти працюють разом на кожному запуску run.

Приклад alert:

Slack: 🛑 Agent support@2.4.0 blocked: gate_failed on canary stage (error_rate > threshold).

Як це виглядає в архітектурі

Version policy layer стоїть між runtime і запуском нової версії агента та блокує запуск до старту run. Кожне рішення (allow або stop) фіксується в audit log.

Кожен запуск run проходить через цей flow перед виконанням: runtime не стартує нову версію напряму, а передає рішення policy layer.

Коротко по flow:

• Runtime готує запуск run
• Policy перевіряє version_manifest, tool_contracts, rollout_stage, policy_version
• allow -> стартує pinned agent_version
• stop -> реліз блокується, лишається active stable version
• обидва рішення пишуться в audit log

Приклад

Команда релізить support-agent@2.4.0 із новим refund.create tool adapter. На контракт-перевірці виявляється несумісність schema.

Результат:

• policy повертає stop (reason=contract_mismatch)
• canary не стартує
• продовжує працювати support-agent@2.3.3

Versioning зупиняє ризиковий реліз до інциденту, а не після нього.

У коді це виглядає так

У спрощеній схемі вище показано основний flow. Критично: runtime має запускати run тільки з pinned version_id, а не брати "latest" під час виконання.

Приклад versioning-конфігурації:

agent_release:
  stable_version: support-agent@2.3.3
  candidate_version: support-agent@2.4.0
  canary_percent: 5
  rollback_on:
    error_rate_p95: 0.05
    tool_failure_p95: 0.03

release_cfg = load_release_config("support-agent")
candidate = registry.get(release_cfg.candidate_version)
decision = versioning.check(candidate, runtime_context)

if decision.outcome == "stop":
    audit.log(
        run_id,
        decision=decision.outcome,
        reason=decision.reason,
        version_id=candidate.version_id,
        rollout_stage=decision.rollout_stage,
    )
    alerts.notify_if_needed(candidate.version_id, decision.reason)
    return stop(decision.reason)

selected = versioning.select(candidate, stable=release_cfg.stable_version)
run = runtime.start(
    version_id=selected.version_id,
    prompt_hash=selected.prompt_hash,
    policy_version=selected.policy_version,
)
# Decision.allow — умовний helper, щоб зберегти єдину модель outcome/reason.
allow_decision = Decision.allow(reason=None)

audit.log(
    run.id,
    decision=allow_decision.outcome,
    reason=allow_decision.reason,
    version_id=selected.version_id,
    rollout_stage=selected.rollout_stage,
)

return run

Як це виглядає під час виконання

Сценарій 1: блокування через contract mismatch

1. Runtime готує запуск support-agent@2.4.0.
2. Policy перевіряє tool contracts.
3. Рішення: stop (reason=contract_mismatch).
4. Нова версія не запускається.
5. Подія фіксується в audit log.

Сценарій 2: canary rollout

1. Policy дозволяє candidate на canary_percent=5.
2. Частина run-ів іде на 2.4.0, решта — на stable.
3. Метрики відстежуються по version_id.
4. Якщо пороги не порушені, stage підвищується.
5. Версія переходить у ширший rollout.

Сценарій 3: rollback required

1. Після rollout росте tool_failure_rate.
2. Policy повертає stop (reason=rollback_required).
3. Трафік повертається на stable version.
4. Run-и з новою версією більше не стартують.
5. Команда аналізує інцидент за version_id і audit trail.

Типові помилки

• запускати run із "latest" замість pinned version_id
• версіонувати тільки prompt і ігнорувати tools/policy контракти
• робити full rollout без canary gate
• не логувати version_id і rollout_stage в audit
• змішувати rollback і новий реліз в одному кроці без stable fallback
• не мати явних порогів, при яких потрібен rollback

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

Самоперевірка

Швидка перевірка agent versioning перед запуском у production:

FAQ

Q: Чому не можна просто оновлювати "поточну" версію агента?
A: Тому що без pinned version_id ти втрачаєш відтворюваність run-ів і не можеш точно локалізувати регресію.

Q: Що саме версіонувати: тільки prompt?
A: Ні. Мінімум: prompt, tool contracts, policy/config і runtime-сумісність. Інакше версія неповна.

Q: Чи обов'язковий canary для кожної зміни?
A: Для high-risk змін — так. Для low-risk можна скорочувати етапи, але з явними метриками і stop-порогами.

Q: Коли запускати rollback?
A: Коли порушені узгоджені пороги (error/tool failure/latency/cost). Це має бути policy-рішення, а не ручна імпровізація.

Q: Versioning замінює rollback?
A: Ні. Versioning запобігає хаосу в релізах, rollback залишається аварійним механізмом повернення до stable.

Де Agent Versioning у загальній системі

Agent versioning — це один із рівнів Agent Governance. Разом із RBAC, лімітами, бюджетами, approval і audit він формує єдину систему контрольованих змін у production.

Пов'язані сторінки

Далі за темою:

• Огляд Agent Governance — загальна модель контролю агентів у production.
• Rollback стратегії — як безпечно повертатись до stable-версії.
• Контроль доступу (RBAC) — як обмежувати, хто і що може виконувати.
• Контроль бюджетів — як утримувати витрати під час rollout.
• Audit logs для агентів — як відновлювати ланцюг рішень за version_id.