Версионирование агентов и промптов: как не сломать продакшен

Промпт изменили — и метрики поехали

Типичная картина в команде, которая делает продукт на LLM: инженер правит системный промпт прямо в дашборде провайдера или в конфиге, деплоит, и через сутки поддержка получает поток жалоб. Ответы стали короче, агент перестал вызывать нужный инструмент, доля успешных диалогов упала. Кто, что и зачем менял — восстановить не получается, потому что промпт нигде не версионировался. Откатиться не к чему.

Проблема в том, что промпт и конфигурация агента — это исполняемая часть приложения, такая же, как код. Но обращаются с ними как с текстовой строкой: держат в переменной окружения, в базе, в панели SaaS-инструмента без истории. Как только модель, температура, набор инструментов или сам текст меняются без фиксации, воспроизвести поведение системы становится невозможно.

Что именно нужно версионировать

Поведение агента определяется не одним промптом. Между двумя запусками может измениться любой из компонентов, и каждый способен сдвинуть результат:

• Системный и пользовательские промпты — текст, шаблоны, примеры few-shot.
• Модель и её версия — переход с одной версии на другую меняет ответы даже при том же промпте. Провайдеры выпускают снапшоты моделей с датой в названии именно для воспроизводимости.
• Параметры генерации — temperature, top_p, max_tokens, штрафы.
• Определения инструментов (function calling) — их названия, описания и схемы аргументов влияют на то, когда и как агент их вызывает.
• Источники для RAG¹ — какая версия базы знаний и какой эмбеддинг-модели использовались.
• Логика оркестрации — порядок шагов, условия ветвления, лимиты на количество итераций агента.

Зафиксировать нужно всё это как единый артефакт с версией, а не только строку промпта. Иначе откат промпта на прошлую версию при новой модели даст третий, никем не проверенный результат.

Если вы не можете назвать точную комбинацию «промпт + модель + параметры + инструменты», на которой работает ваш продакшен прямо сейчас, у вас нет версионирования — у вас есть надежда, что никто ничего не трогал.

Три подхода к хранению версий

Команды приходят к одному из трёх решений, и выбор зависит от того, кто редактирует промпты и как часто.

1. Промпты в репозитории с кодом

Промпты лежат рядом с кодом как файлы (YAML, Jinja-шаблоны, отдельный модуль). История ведётся через Git, ревью — через pull request, откат — через revert коммита. Плюс: единый пайплайн, промпт проходит через CI вместе с тестами. Минус: чтобы поправить формулировку, нужен деплой, а продакт-менеджер или контент-редактор без доступа к репозиторию менять ничего не может.

2. Отдельный prompt registry

Промпты хранятся во внешнем реестре с версиями и тегами (например, alias production указывает на конкретную версию). Приложение подтягивает нужную версию по имени и тегу. Такой подход дают LangSmith, PromptLayer, Langfuse и подобные инструменты. Плюс: правки без деплоя, нетехнические люди работают через UI, есть история и метрики по каждой версии. Минус: промпт теперь живёт отдельно от кода, и рассинхрон между версией кода и версией промпта — новый класс багов.

3. Промпты как записи в собственной БД

Реестр пишется руками: таблица с полями версия, текст, параметры, автор, дата, статус. Плюс: полный контроль, ничего лишнего, данные не уходят стороннему сервису. Минус: весь тулинг — история, диффы, откаты, A/B — придётся строить самому.

Откат: к чему возвращаться и по какому сигналу

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

1. Держите предыдущую production-версию активной. Не удаляйте её сразу после релиза новой — псевдоним production должен переключаться на прошлую версию за одну операцию, без деплоя.
2. Заведите офлайн-набор кейсов. Прогоняйте новую версию промпта на фиксированном наборе примеров с ожидаемым результатом до релиза. Регресс виден до пользователей, а не после.
3. Считайте метрики по версиям. Логируйте, какая версия обработала запрос, и привязывайте к ней метрики: доля успешных диалогов, длина ответа, частота вызова инструментов, стоимость токенов.
4. Раскатывайте постепенно. Новую версию сначала на часть трафика (canary), сравните метрики с текущей, потом расширяйте.
5. Опишите условие отката заранее. Например: если доля успешных ответов на canary ниже базовой на согласованный порог — автоматический откат на предыдущую версию.

Кому это нужно, а кому нет

Полноценное версионирование окупается, если: у вас продакшен с реальными пользователями и деньгами на ответах агента; промпты правит больше одного человека; вы используете внешние модели, версии которых меняет провайдер; регрессии в качестве ответов бьют по бизнесу — например, агент выдаёт возвраты или считает заказы.

Можно обойтись малым, если вы делаете прототип, хакатон-проект или внутренний инструмент на пару человек. Здесь достаточно держать промпт в Git рядом с кодом и не строить реестр, A/B и canary — это оверинжиниринг, который замедлит проверку гипотезы. Начинать со сложной инфраструктуры на этапе, когда продукт ещё может не взлететь, — потраченное время.

Ориентир простой: как только вы впервые не смогли ответить на вопрос «почему вчера агент отвечал иначе», пора вводить версии. До этого момента — вероятно, рано.

¹ RAG (retrieval-augmented generation) — подход, при котором модель перед ответом подтягивает релевантные фрагменты из внешней базы знаний и отвечает с опорой на них, а не только на то, что запомнила при обучении.