Рабочий цикл: dev → production
Практический цикл brt: локальная разработка, подключение интеграций, выкатка в production и диагностика без смешивания targets.
У agent-проекта два независимых target: dev для короткого цикла разработки и production для реального трафика. Они не делят настройки, секреты, интеграции или данные. Изменение одного target никогда не должно незаметно менять другой.
Код живёт в Git. Установленные integrations и желаемый состав plugins живут в
Cloud у конкретного target. Перед каждым brt dev и brt deploy --adk CLI
сверяет точное состояние выбранного target с Cloud, обновляет локальное
сгенерированное отражение и только затем запускает генерацию и сборку. Файлы в
.adk/ — результат этого процесса, а не второй источник правды.
| Target | Основная команда | Для чего использовать |
|---|---|---|
| Dev | brt dev | Локальный процесс, tunnel, быстрый feedback loop и dev-интеграции с --dev. |
| Production | brt deploy --adk | Сборка и загрузка production-бандла; config и integrations без --dev. |
Dev — не staging и не копия production. Финальную доставку сообщений, production-секреты и другие критичные сценарии проверяйте на отдельном окружении, близком к production, после явного deploy.
Основной цикл
Запустите dev. Для проекта с agent.config.ts достаточно обычной команды:
brt devCLI создаёт или переиспользует отдельного dev-бота, сверяет его Cloud dependencies, генерирует бота и открывает tunnel к локальному процессу. Watch включён по умолчанию.
Меняйте код и проверяйте результат. Сохраняйте файлы в src/ — watcher
повторит generation и обновит только dev target. Ошибка сборки остаётся видимой
в терминале, но не затрагивает production.
Подключайте dev-интеграции из второго терминала. Сначала дождитесь первого
успешного запуска brt dev, затем используйте те же команды с --dev:
printf '%s' "$DEV_EXTERNAL_API_KEY" \
| brt secret set EXTERNAL_API_KEY --dev
printf '{"botToken":"%s"}' "$DEV_TELEGRAM_TOKEN" \
| brt integrations install botruntime/telegram@1.1.3 --config-stdin --dev
export DEV_WEBHOOK_ID='wh_replace_from_install_output'
brt integrations register "$DEV_WEBHOOK_ID" --devinstall и register меняют состояние интеграции в Cloud. Для уже
подготовленного dev target успешная команда также обновляет локальное отражение
зависимостей. Запущенный watcher замечает это изменение и сам
повторяет generation — перезапускать brt dev не нужно. Дождитесь сообщения об
успешной регенерации и проверьте реальный канал.
Продвигайте в production осознанно. Выкатка новой production-интеграции всегда состоит из четырёх действий:
# 1. Создать или обновить production target текущим кодом
brt deploy --adk --name "Мой бот"
# 2. Установить и зарегистрировать production-интеграцию
printf '{"botToken":"%s"}' "$PROD_TELEGRAM_TOKEN" \
| brt integrations install botruntime/telegram@1.1.3 --config-stdin
export PROD_WEBHOOK_ID='wh_replace_from_install_output'
brt integrations register "$PROD_WEBHOOK_ID"
# 3. Сверить Cloud dependencies, пересобрать и загрузить новый бандл
brt deploy --adk
# 4. Только теперь провести приёмочную проверку в production-каналеПервый deploy нужен, чтобы у проекта появился production target. Команды
install и register обновляют Cloud и готовое локальное отражение зависимостей,
но не генерируют, не собирают и не загружают bot bundle. Поэтому второй
brt deploy --adk — обязательная часть выкатки перед приёмочной проверкой.
brt dev --adk намеренно завершается ошибкой. Если нужен постоянный
production redeploy-loop, используйте явный brt deploy --adk --watch.
Изменение production-зависимостей
Для новой версии интеграции, нового конфига или повторной регистрации действует тот же короткий цикл:
- выполните
brt integrations install ...и при необходимостиbrt integrations register ...без--dev; - выполните
brt deploy --adk; - проверьте production-канал и нужный бизнес-сценарий.
Публичное управление интеграциями уже доступно через install/register. Для
plugins доступны каталог и server-side desired state, но публичной команды
brt для установки или удаления plugin у agent target пока нет. Не используйте
brt add/remove как замену: эти команды меняют только зависимости classic-
проекта на *.definition.ts.
Для Telegram используйте разные dev и production Bot API tokens. Telegram
поддерживает один активный webhook на token, поэтому повторный setWebhook
перенаправит трафик, даже если targets внутри платформы разделены.
CI
brt dev --check — read-only gate для уже подготовленного dev target:
brt dev --check --jsonОн подходит для проверки drift в CI, но не создаёт target и не исправляет
состояние. На новом checkout сначала нужен успешный обычный brt dev в
окружении, где dev target можно подготовить.
Production deploy использует выбранный профиль. Создайте отдельный CI-профиль, а затем запускайте обычную команду — так CI проходит ту же сверку с Cloud, генерацию и сборку, что локальная выкатка:
brt deploy --adk --profile cibrt logs использует workspace PAT выбранного профиля и подходит для CI после
device/PAT login. Для end-to-end приёмки всё равно проверяйте также реальный
канал: наличие логов не доказывает доставку ответа пользователю.
Быстрая диагностика
| Симптом | Что сделать |
|---|---|
Команда с --dev ещё не знает target | Один раз успешно запустите brt dev, затем повторите команду из второго терминала. |
Integration остаётся pending или failed | Повторите register с --dev; для production после исправления снова выполните brt deploy --adk. |
| Production-канал установлен, но новый код его не видит | Выполните второй brt deploy --adk: обновление локального отражения зависимостей само по себе не собирает и не загружает бандл. |
dev --check сообщает drift | Запустите обычный brt dev для того же target. Не редактируйте .adk/ вручную. |
| Состояние в Cloud конфликтует или не может быть подтверждено | Исправьте конкретную installation/definition либо восстановите target как оператор, затем повторите обычную команду. CLI не угадывает пустое состояние. |
brt logs возвращает 401/403 | Проверьте активный profile, его workspace и роль на боте; per-bot key команде не нужен. |
Изоляция targets
Платформа разделяет dev и production targets:
| Флаги | Куда идёт команда |
|---|---|
| без флагов | Production target выбранного профиля. |
--dev | Отдельный dev target того же профиля. |
Код brt dev выполняется локально, но управление ботом, данные и dev target
остаются в облачной платформе.
Что происходит внутри
Обычно достаточно основного цикла выше. Форматы snapshots, безопасный импорт
legacy dependencies, правила --noBuild, target attestation и полный контракт
dev --check описаны в «Dependency snapshots».