Рабочий цикл: dev → production
Практический цикл brt: локальная разработка, подключение интеграций, выкатка в production и диагностика без смешивания targets.
У agent-проекта два независимых runtime-окружения: dev для короткого цикла разработки и production для реального трафика. Они входят в один логический бот в консоли, но не делят настройки, секреты, интеграции или данные. Изменение одного окружения никогда не должно незаметно менять другое.
Код живёт в 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
включён по умолчанию. Одновременно CLI связывает development-runtime с
production-ботом из agent.json. Связь не переносит данные между окружениями:
она нужна, чтобы консоль показывала их под одним ботом и переключала отдельные
истории Evals.
agent.local.json не попадает в Git и хранит runtime именно этого checkout.
Повторный запуск переиспользует тот же target и сохраняет hosted evals. Другой
checkout создаёт ещё одно Development-окружение внутри того же проекта.
Меняйте код и проверяйте результат. Сохраняйте файлы в 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 не нужно. Дождитесь сообщения об
успешной регенерации и проверьте реальный канал.
В отличие от интеграций, значения config-переменных (brt secret set --dev)
CLI забирает у Cloud только один раз — при старте dev-воркера. Watcher
перезагружает изменённый код в том же процессе (worker.reload()) и
переменные окружения при этом не обновляет. После brt secret set для уже
запущенного brt dev остановите его (Ctrl+C) и запустите заново — только
тогда новое значение попадёт в process.env/secrets.X дочернего процесса.
Продвигайте в 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.
Управление Development-окружениями
Откройте страницу Окружения в настройках бота, чтобы увидеть все runtime
одного проекта. Для каждого Development консоль показывает runtime ID, имя,
дату создания и обновления, число диалогов и запусков Evals. admin и owner
могут переименовать Development или удалить больше не нужный target.
Удаляйте окружение только после проверки его runtime ID, даты обновления и счётчиков данных. Вместе с Development удаляются его диалоги, файлы, таблицы, интеграции, секреты и история Evals. Production и другие Development того же проекта не затрагиваются.
Если вы удалили Development текущего checkout, вручную править
agent.local.json не нужно. При следующем запуске brt dev CLI увидит, что
сохранённый target отсутствует, создаст новый Development и запишет его ID в
локальную привязку.
Изменение production-зависимостей
Для повторной регистрации не запускайте install: передайте существующий
webhookId в brt integrations register <webhookId>, затем проверьте
production-канал. Публичной команды для in-place изменения конфига существующей
installation пока нет; повторный install создаёт другую installation либо
завершается конфликтом, а не обновляет текущую.
Новую SemVer-версию существующей инсталляции не ставьте повторным install:
он создаёт ещё одну инсталляцию. Переключите текущую installation командой
brt integrations upgrade <name@version> --alias <alias> или действием
«Обновить до v…» в веб-консоли, затем выполните brt deploy --adk. Сервер
сохранит alias, webhook, конфиг, статус и секреты и откажет с 409, если новый
config schema или режим проверки webhook несовместимы.
Публичное управление интеграциями уже доступно через 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. Для dev target добавьте --dev: CLI проверит opaque runtime
target и прочитает логи связанного numeric bot. Для end-to-end приёмки всё
равно проверяйте также реальный канал: наличие логов не доказывает доставку
ответа пользователю.
Окно можно задавать абсолютным RFC3339 или duration без ручного вычисления
timestamp: brt logs --since 10m; CLI отправит серверу уже канонический
RFC3339 timeStart.
Быстрая диагностика
| Симптом | Что сделать |
|---|---|
Команда с --dev ещё не знает target | Один раз успешно запустите brt dev, затем повторите команду из второго терминала. |
Integration остаётся pending или failed | Повторите register с --dev; для production после исправления снова выполните brt deploy --adk. |
| Production-канал установлен, но новый код его не видит | Выполните второй brt deploy --adk: обновление локального отражения зависимостей само по себе не собирает и не загружает бандл. |
dev --check сообщает drift | Запустите обычный brt dev для того же target. Не редактируйте .adk/ вручную. |
brt dev пишет Local tunnel handler failed | Используйте напечатанные HTTP status, request ID и локальный response. Это ответ локального handler, а не потеря tunnel; исправьте первичную ошибку и повторите запрос. |
| Состояние в Cloud конфликтует или не может быть подтверждено | Исправьте конкретную installation/definition либо восстановите target как оператор, затем повторите обычную команду. CLI не угадывает пустое состояние. |
brt logs возвращает 401/403 | Проверьте активный profile, его workspace и роль на боте; per-bot key команде не нужен. |
brt logs --bot-id <runtime UUID> возвращает invalid bot id | Для opaque dev runtime используйте brt logs --dev; --bot-id без --dev выбирает production target. |
Изоляция targets
Платформа разделяет dev и production targets:
| Флаги | Куда идёт команда |
|---|---|
| без флагов | Production target выбранного профиля. |
--dev | Отдельный dev target того же профиля. |
Код brt dev выполняется локально, но управление ботом, данные и dev target
остаются в облачной платформе.
Что происходит внутри
Обычно достаточно основного цикла выше. Форматы snapshots, безопасный импорт
legacy dependencies, правила --noBuild, target attestation и полный контракт
dev --check описаны в «Dependency snapshots».