Быстрый старт

Создайте TypeScript-бота, проверьте его в dev и задеплойте в production.

В этом руководстве вы создадите минимального бота, запустите его через отдельный dev target и поговорите с ним прямо из терминала. Production изменится только после явного deploy.

Что понадобится

Bun 1.3.14 или новее;
аккаунт и воркспейс botruntime.

Поговорить с ботом можно сразу после dev-запуска через встроенный CLI-чат — без Telegram и без единого внешнего аккаунта. Реальный канал (Telegram) — отдельный опциональный раздел в конце руководства.

1. Установите CLI

bun add -g @holocronlab/brt
brt --help

Пакет публикуется в npm. Доступ к GitHub Packages не требуется.

2. Войдите в платформу

brt login
brt profiles active

brt login откроет подтверждение в браузере и сохранит выбранный воркспейс в ~/.brt/profiles.json. Для CI передавайте PAT и workspace ID через секреты системы сборки.

3. Создайте проект

mkdir support-bot
cd support-bot
brt init --type bot --template hello-world --name support-bot
brt check

brt check загружает конфигурацию, находит примитивы и проверяет проект без сетевых запросов.

Минимальная конфигурация выглядит так:

agent.config.ts

import { defineConfig } from '@holocronlab/botruntime-runtime'

export default defineConfig({
  name: 'support-bot',
  description: 'Помощник службы поддержки',
})

Обработчик отвечает на сообщения из любого подключённого канала:

src/conversations/index.ts

import { Conversation } from '@holocronlab/botruntime-runtime'

export default new Conversation({
  channel: '*',
  handler: async ({ execute }) => {
    await execute({
      instructions: 'Помогай пользователю проверить статус заказа.',
    })
  },
})

Не коммитьте .adk/, .brt/, agent.local.json, .env и node_modules/. Эти файлы содержат локальное или сгенерированное состояние.

4. Запустите dev target

brt dev

Команда создаёт отдельного dev-бота, собирает проект и открывает tunnel к локальному процессу. Оставьте её запущенной.

5. Поговорите с ботом

Во втором терминале, из той же папки проекта, запустите встроенный CLI-чат:

brt chat --dev

Команда сама устанавливает и регистрирует совместимую первую версию first-party Chat-интеграции на dev target (никаких токенов и внешних аккаунтов), создаёт новую беседу и открывает интерактивный терминальный чат. Пишите сообщения после >>, ответ бота приходит в том же окне. Для выхода — exit или клавиша ESC.

Измените instructions в src/conversations/index.ts, сохраните файл — brt dev пересоберёт проект — и отправьте новое сообщение в том же чате, чтобы увидеть изменение.

brt chat помечена как экспериментальная и годится для быстрой проверки логики бота. Для приёмочной проверки реального канала используйте Telegram (раздел ниже).

6. Задеплойте в production

Создайте production target и загрузите проверенный код:

brt deploy --adk --name "support-bot"

После изменения production-зависимостей выполните deploy ещё раз. Команда зафиксирует точное состояние интеграций в новом бандле.

brt deploy --adk

Поговорить с production-ботом тем же способом можно и без --dev (см. оговорку про экспериментальный статус brt chat выше):

brt chat

Подключите Telegram (опционально)

Реальный канал понадобится для приёмочной проверки и живых пользователей. Используйте разные токены Telegram Bot API для dev и production — один токен может иметь только один активный webhook.

Установите интеграцию для dev target:

printf '{"botToken":"%s"}' "$DEV_TELEGRAM_TOKEN" \
  | brt integrations install botruntime/telegram@1.1.3 --config-stdin --dev

Скопируйте webhookId из ответа и зарегистрируйте webhook:

brt integrations register "$DEV_WEBHOOK_ID" --dev

Напишите боту в Telegram — dev-процесс отвечает так же, как в brt chat --dev.

Для production подключите интеграцию без --dev и с отдельным токеном:

printf '{"botToken":"%s"}' "$PROD_TELEGRAM_TOKEN" \
  | brt integrations install botruntime/telegram@1.1.3 --config-stdin
brt integrations register "$PROD_WEBHOOK_ID"

Проверка результата

brt check завершается без ошибок;
brt chat --dev показывает ответ бота без единого внешнего канала;
production-бот отвечает только после явного deploy;
dev и production используют разные настройки и токены.