Справочник команд brt

brt — CLI и dev-kit платформы botruntime: путь «код → работающий бот». Одна команда собирает агент-проект в самодостаточный бандл, другая — деплоит его в платформу, третья — подключает канал. Ниже собраны поддерживаемые публичные workflow: сигнатура → назначение → важные флаги → пример с выводом. Машинным источником полного набора опций остаётся brt <command> --help той версии CLI, которую вы запускаете.

Стандартный endpoint — https://botruntime.ru. Необязательный --api-url переопределяет его для прокси, staging и разработки платформы. Это технический override; он не меняет модель поставки платформы. Профили и per-bot ключи лежат в ~/.brt.

Общие флаги

Парсер CLI принимает эти флаги на верхнем уровне, но эффект зависит от команды. В частности, --json является контрактом только там, где команда явно описывает machine-readable output (например, brt dev --check). brt logs и интерактивный brt chat пишут напрямую в свои потоки и не обещают глобальный JSON-режим.

--confirm/-y не подтверждает destructive table changes. Для удаления таблицы, колонки или изменения типа требуется отдельный --allow-destructive-table-changes.

Аутентификация и профили

brt login

brt login [--device | --no-device] [--token <PAT>] [--workspace-id <id>] [--api-url <url>]

Записывает профиль CLI: endpoint, персональный токен доступа (PAT) и воркспейс. По умолчанию использует https://botruntime.ru и открывает device authorization в браузере. --no-device переключает на интерактивную вставку PAT, а --token предназначен для CI. Без --workspace-id команда предлагает выбрать доступный workspace. Профиль пишется в ~/.brt/profiles.json.

brt login
# откроет device authorization, даст выбрать workspace и запишет профиль

brt logout

brt logout

Очищает текущий global cache CLI, включая active-profile selection. Именованные профили в profiles.json и per-bot ключи в bots.json остаются.

brt profiles

brt profiles list   [--display-token]
brt profiles active [--display-token]
brt profiles use    <profileName>
brt profiles get    <profileName> [--display-token]

Управление профилями CLI. Одна установка brt держит несколько профилей (разные воркспейсы или окружения) и переключается между ними. Активный профиль хранится в ~/.brt. Токен по умолчанию замаскирован — покажет только --display-token.

Каждый профиль привязан к одному воркспейсу. Используйте отдельные профили для разных аккаунтов или рабочих окружений.

brt profiles list
brt profiles use ci

Боты

brt bots

brt bots create --name <name> [--if-not-exists]
brt bots get    <botId>
brt bots delete <botId>
brt bots list   [--dev]

CRUD над ботами воркспейса через профиль CLI.

brt bots list
# botId               name            type
# 42                  support-bot     adk

brt bots versions list / deploy

brt bots versions list   [--bot-id <id>]
brt bots versions deploy <versionId> [--bot-id <id>]

«Что сейчас живо» и откат одной командой. Целевой бот резолвится как у brt logs/brt conversations — из канонического project-линка (agent.json/agent.local.json), с --bot-id как явным override — но auth здесь другой: /v1/admin/bots/{id}/versions и .../versions/deploy смонтированы только bot-scoped (нет workspace-PAT маршрута, в отличие от логов/трейсов), так что команда всегда использует per-bot key бота из bots.json (brt link --bot-id <id> --key-stdin), а не PAT текущего профиля.

list печатает id, createdAt и метку (current) у активной версии; --json отдаёт сырой массив версий. deploy <versionId> атомарно переключает current_version_id бота на уже загруженную версию — это и есть механизм отката (см. docs/deploy.md): взять versionId предыдущей версии из list и передать в deploy.

brt bots versions list
# 41   2026-07-10T12:00:00.000Z   v1
# 42   2026-07-15T09:30:00.000Z   v2 (current)

brt bots versions deploy 41
# ✓ Bot 42 is now running version 41

Каталог интеграций, интерфейсов и плагинов

brt integrations / interfaces / plugins

brt integrations get    <name[@version]>
brt integrations list   [--name <n>] [--version-number <v>] [--owned] [--public] [--limit <n>] [--dev]
brt integrations delete <name[@version]>

brt interfaces get    <ref>
brt interfaces list
brt interfaces delete <ref>
brt plugins get    <ref>
brt plugins list   [--name <n>] [--version-number <v>]
brt plugins delete <ref>

Чтение и удаление записей каталога. get/delete адресуют пакет по имени с опциональной версией (telegram, telegram@1.1.3). Список фильтруется.

brt integrations list --owned
brt interfaces get llm@5.1.0

Проект и сборка

brt init

brt init [--type bot|integration|plugin] [--template <id>] [--name <n>] [--work-dir <path>]

Скаффолдит интеграцию, плагин или ADK agent-проект.

brt check

brt check [--work-dir <path>]

Проверяет ADK agent-проект полностью локально: загружает agent.config.ts, выполняет primitive discovery и валидирует расписания Workflow.schedule. Команда не требует login, PAT или сети и не изменяет Cloud. Ошибки импорта, невалидные primitive-конструкторы, непустой src без найденных primitives и scheduled workflow с обязательными input-полями завершают проверку с ошибкой, вместо генерации пустого бота.

brt check
# Agent project check passed

brt build (classic project)

brt build [--source-map] [--no-minify] [--work-dir <path>]

Для classic-проекта на *.definition.ts выполняет generate + bundle. Root agent-проект на agent.config.ts эта команда намеренно не принимает: его generation/build встроены в brt dev и brt deploy --adk.

brt build
# .botpress/dist/index.cjs

brt generate, bundle, read, lint (classic project)

brt generate            # alias: gen — типы для intellisense (codegen без бандла)
brt bundle [--source-map] [--no-minify]   # только собрать бандл (без codegen)
brt read                # разобрать и напечатать определение интеграции
brt lint                # EXPERIMENTAL: линт определения интеграции

build = generate + bundle за один вызов. Отдельные подкоманды нужны, когда хотите обновить только типы (gen после правки схем) или только пересобрать бандл.

brt run

brt run <scriptPath> [scriptArgs..] [--force] [--prod]

Запускает один TypeScript-процесс в runtime-контексте agent-проекта и завершается с его exit code. Команда не запускает worker, watcher, reverse tunnel или callback receiver.

Dev-target получает публичные Cloud config vars; auth, network или attestation failure останавливает запуск пользовательского кода. Production secrets не скачиваются на машину разработчика. --local можно использовать только с development target и нельзя сочетать с --prod.

Durable workflows

CLI управляет persisted workflow engine платформы и не исполняет вторую копию workflow локально.

brt workflows run

brt workflows run <name> [--dev] [--input-file <path>] [--idempotency-key <key>]
                       [--timeout <ms>] [--workflow-timeout <ms>] [--wait | --no-wait]
                       [--include-data]

Создаёт workflow идемпотентно и по умолчанию наблюдает его до terminal state или до истечения observation timeout. Input — bounded JSON object из файла. CLI печатает использованный idempotency key; при outcome-unknown повторите исходную команду на том же target с тем же input и ключом. Один ключ с другим request fingerprint отклоняется.

--timeout ограничивает только наблюдение этой команды: при истечении CLI возвращает exit code 2 и не отменяет durable process. --workflow-timeout задаёт отдельный persisted execution deadline. --no-wait завершает CLI после подтверждённого create; --wait фиксирует обычную семантику. Failed, timed-out и cancelled terminal states возвращают exit code 1.

brt workflows list

brt workflows list [--dev] [--status <status>...] [--limit <n>] [--next-token <cursor>]

Возвращает bounded cursor-paginated историю metadata. --limit не может превысить серверный максимум 100; --next-token принимает только cursor, возвращённый предыдущей страницей.

brt workflows show

brt workflows show <workflowId> [--dev] [--steps] [--include-data]

Показывает один workflow. По умолчанию произвольные input/output/tags и raw failure payload исключены. --include-data явно включает только workflow input/output/tags; --steps добавляет bounded безопасную проекцию шагов.

brt workflows wait

brt workflows wait <workflowId> [--dev] [--timeout <ms>] [--steps] [--include-data]

Продолжает bounded-наблюдение уже существующего workflow. Observation timeout не является cancellation и не меняет persisted state. Для dev-target все команды используют --dev; --local при hosted operations допустим только вместе с ним.

Линковка и деплой

brt link

brt link --bot-id <id> (--key-stdin | --key <k>) [--workspace-id <id>] [--api-url <url>]

Привязывает текущий проект к существующему боту без провижининга. Для agent-проекта пишет agent.json, для classic — bot.json. Per-bot key сохраняется в ~/.brt/bots.json раньше link-файла, чтобы аварийный обрыв не оставил невосстановимую привязку.

Команда использует активный профиль и сохраняет связь с ботом в проекте.

printf '%s' "$BOT_KEY" | brt link --bot-id 42 --key-stdin

brt deploy --adk

brt deploy --adk [--name "<имя>"] [--bot-id <id>] [--noBuild]
                 [--watch] [--allow-destructive-table-changes] [--noTypecheck]

Деплоит агент-проект в production: создаёт бота при первом deploy, собирает и загружает bundle и синхронизирует объявленные таблицы.

В обычном пути CLI сначала доказывает точный target и сверяет его integrations и plugins с Cloud, затем генерирует и собирает .botpress/dist/index.cjs, загружает bundle и применяет diff объявленных таблиц. Первый deploy без link создаёт production-бота и сохраняет его key раньше project link; повторный deploy использует уже привязанный target. Сверка Cloud всегда происходит до generation и build, поэтому stale или неоднозначное dependency state останавливает команду до upload.

Форматы snapshots, target attestation, provenance для --noBuild и порядок fail-closed recovery вынесены в Dependency snapshots. Для обычной выкатки эти файлы не нужно читать или редактировать.

--dry-run не поддержан в сочетании с --adk: CLI завершается fail-loud до project bootstrap, build, авторизованного target API и записи project-файлов. Для classic deploy флаг сохраняет свою прежнюю семантику.

--watch нельзя сочетать с --noBuild: watch-режим обязан пересобирать изменившийся source перед каждым redeploy и отклоняет эту комбинацию до auth bootstrap, авторизованного target API и записи project-файлов.

Перед сборкой CLI запускает проверку типов проекта (семантика tsc --noEmit по tsconfig.json проекта, компилятор — из devDependencies самого бота). Ошибка типов останавливает deploy с диагностикой в формате tsc — до загрузки bundle, а не в рантайме. Обход — --noTypecheck (CLI предупреждает); проект без tsconfig.json проверку пропускает с предупреждением. Проверка выполняется после сверки Cloud dependencies: типы интеграций и plugins генерируются по актуальному состоянию target.

--noBuild предназначен только для повторной отправки уже собранного artifact тому же target. Он требует существующий target и точный adjacent provenance; после изменения source или Cloud dependencies используйте обычный deploy со сборкой. BRT_BUNDLE_PATH — продвинутый trusted override и не отменяет provenance-проверку в сочетании с --noBuild.

Для automation сначала создайте или выберите профиль через brt login --token ... --workspace-id .... Для прокси или staging добавьте --api-url ... при создании профиля. Затем запускайте deploy с --profile <имя>.

# 1. Первый deploy создаёт target и загружает текущий код
brt deploy --adk --name "support-bot"

# 2. Install/register меняют состояние интеграции в Cloud
printf '{"botToken":"%s"}' "$PROD_TG" \
  | brt integrations install telegram@1.1.3 --config-stdin
export PROD_WEBHOOK_ID='wh_replace_from_install_output'
brt integrations register "$PROD_WEBHOOK_ID"

# 3. Второй deploy сверяет Cloud, генерирует и загружает новый bundle
brt deploy --adk

# 4. После успешного deploy — приёмочная проверка в реальном канале

install/register обновляют готовый production snapshot, но не запускают генерацию/сборку и не загружают bundle. Поэтому второй deploy обязателен перед приёмочной проверкой. Он пропускает провижининг уже привязанного target, заново сверяет точное состояние с Cloud, загружает новую версию и применяет table diff.

brt bots deployments abort

brt bots deployments abort <deploymentId> [--bot-id <id>] --confirm [--json]

Терминально завершает только безопасный pre-schema deployment в phase staged или fenced при schemaMutated=false. Активная версия остаётся current, staged-версия больше не может активироваться, traffic fence снимается.

Команда сначала читает deployment и запрашивает подтверждение. Только после подтверждения она получает актуальный environment fence generation и отправляет один CAS-abort. Это важно после отдельного recovery-unfence: generation environment уже может быть на единицу больше значения в deployment.

Успехом считается только точное состояние failed с lastErrorCode=BOT_DEPLOYMENT_ABORTED. Повторный вызов идемпотентен. После начала schema mutation, смены active pointer или конкурентного изменения fence generation команда завершается без попытки ослабить проверку.

Зависимости classic-проекта

brt add / remove

brt add    <ref> [--alias <name>] [--use-dev] [--install-path <path>]   # alias: i, install
brt remove <alias>                                                       # alias: rm

Устанавливает пакет каталога (интеграцию, интерфейс или плагин) в зависимости classic-проекта на *.definition.ts: обновляет bpDependencies и генерирует bp_modules. ref — ID или имя с опциональной версией: teams, teams@0.2.0, llm@5.1.0.

brt add telegram@1.1.3
brt remove telegram

Переменные и интеграции бота

Команды config, secret и integration mutations в production и dev используют PAT активного профиля, явный workspace и bot target. Cloud дополнительно проверяет принадлежность бота workspace и роль owner/admin. Это позволяет настраивать существующего бота без копирования bot key на каждую машину.

brt config / secret

brt config set  <NAME> [--value-file <f>] [--dev]
brt config list [--dev]                         # alias: ls
brt config rm   <NAME> [--dev]                  # alias: delete
brt secret set  <NAME> [--value-file <f>] [--dev]

config и secret — разные контракты:

• config set/list/rm управляет публичной schema-backed bot.configuration.data; set и rm подтверждают persistence контрольным чтением;
• secret set записывает зашифрованное write-only значение в secrets/env.

printf '%s' '20' | brt config set maxSearchResults
brt config list
# maxSearchResults  20

printf '%s' "$EXTERNAL_API_KEY" | brt secret set EXTERNAL_API_KEY
# secret EXTERNAL_API_KEY -> ok

Токен Telegram не является bot secret: передавайте его в sealed-конфигурации brt integrations install botruntime/telegram@… --config-stdin. Модельные credentials обычного диалога принадлежат LLM-шлюзу платформы, а не каждому боту.

brt integrations install / register / upgrade / publish

brt integrations install <name@version> (--config-stdin | --config-file <f>) [--alias <a>]
                         [--dev]
brt integrations register <webhookId> [--dev]
brt integrations upgrade <name@version> [--alias <a>] [--dev] [--wait]
brt integrations publish [--name <name>] [--version-number <semver>]
                         [--config-schema-file <path>] [--no-bundle]
                         [--dryRun] [--noBuild] [--api-url <url>]

install устанавливает точную версию integration на production target либо, с --dev, на отдельный dev target и возвращает webhookId; register активирует её webhook на том же target. upgrade переключает существующую installation на другую опубликованную точную версию без повторного install/register. publish отправляет полное определение и bundle через канонический deploy-контракт с visibility=public. Все четыре команды используют profile PAT; install, register и upgrade дополнительно сужены явными workspace+bot и writer role.

Для подготовленного agent target install, register и upgrade после подтверждённой Cloud mutation обновляют dependency snapshot. В dev запущенный watcher замечает обновление и повторяет generation. В production обновление snapshot не является build/deploy: выполните brt deploy --adk и только затем проводите приёмочную проверку.

upgrade сначала получает installation выбранного бота и требует ровно одно совпадение effective alias. Явно сохранённый alias имеет приоритет; для пустого alias подходит canonical integration name или его последний сегмент. Затем CLI отправляет один атомарный direct repoint. Cloud сохраняет installation ID, webhook, alias, статус и credentials и отклоняет несовместимые config schema или webhook auth mode с 409. Отдельного preflight нет.

--wait пока не поддержан и отклоняется до выбора target, сетевых запросов и mutation. Только ответ 4xx считается подтверждённым отказом. При network error, 5xx, malformed или противоречивом 2xx результат неизвестен: проверьте текущий ref installation, прежде чем выполнять напечатанную rollback-команду. Локальный snapshot в таком случае не меняется.

printf '{"botToken":"%s"}' "$DEV_TG" | brt integrations install botruntime/telegram@1.1.3 --config-stdin --dev
# installed botruntime/telegram -> webhookId=wh_...
brt integrations register wh_... --dev

brt integrations upgrade botruntime/telegram@1.2.0 --alias telegram
brt deploy --adk

Трейсы

brt traces

brt traces [tokens..]
           [--conversation-id <id>] [--dev]
           [--status unset|ok|error] [--error | --no-error]
           [--source <source>] [--name <spanName>]
           [--workflow <name>] [--action <tool>]
           [--trace-id <32-hex>] [--since <RFC3339|duration>]
           [--until <RFC3339|duration>] [--limit <n>]
           [--next-token <cursor>] [--include-llm] [--json] [--verbose]

Показывает сохранённые трейсы выбранного бота. Основной режим задаётся через --conversation-id <id> или token conversation=<id>. Для workflow и action без conversation обязательна нижняя граница since; точный non-zero traceId можно читать без неё. Запрос без conversation и без одного из workflow / action / traceId завершается до сетевого обращения. action совпадает как с Autonomous tool, так и с hosted integration.action по bare имени (createPayment, а не yookassa:createPayment). Полного unscoped listing Cloud API не предоставляет.

Botpress-compatible tokens можно смешивать с независимыми named flags, но один и тот же фильтр нельзя задавать обоими способами:

since и until принимают RFC3339 или duration вроде 30s, 5m, 1h и 1d. Relative duration вычисляется один раз и отправляется серверу как абсолютная RFC3339-граница. Дополнительные typed filters доступны только как флаги: --status, --source и span --name; --no-error выбирает строки без эффективной ошибки.

Production target берётся из canonical agent.json (или bot.json для classic-проекта): положительные decimal workspaceId и botId вместе с PAT выбранного профиля адресуют GET /v1/admin/workspaces/{workspaceId}/bots/{botId}/traces. Сервер повторно проверяет membership workspace и принадлежность target bot; координаты link не создают authority сами по себе.

С --dev команда использует PAT профиля и attested opaque runtime bot ID, полученный для dev target через brt dev, и вызывает bot-scoped GET /v1/traces. Opaque ID не заменяется production bot ID и не выбирается из произвольного query/header.

Строки упорядочены детерминированно, а pagination ограничена по размеру страницы, общему --limit и числу страниц. Единственный server cursor — meta.nextToken ответа API: CLI не вычисляет cursor из ID строк и не принимает другие поля. Для продолжения передайте выведенный nextToken через --next-token; повтор или malformed cursor завершает команду ошибкой вместо зацикливания или молчаливого рестарта.

brt traces conversation=conv_123 error since=1h
brt traces --conversation-id conv_123 --status ok --source otlp --name autonomous.tool
brt traces workflow=builtin_eval_runner since=10m --dev --json
brt traces trace=0123456789abcdef0123456789abcdef --verbose
brt traces trace=0123456789abcdef0123456789abcdef --include-llm --json
brt traces --conversation-id conv_123 --limit 100 --next-token 456 --json

Cloud API возвращает полное сохранённое содержимое span: correlation IDs, attributes, platform payload, tool input/output и LLM request/response. CLI всегда показывает tool input/output, но по умолчанию убирает из представления тяжёлые LLM-поля. --include-llm добавляет их в human- и JSON-вывод; --verbose показывает stack и attributes/payload выбранного режима. Платформа не удаляет LLM-контент при записи. Доступ ограничен выбранным workspace/bot; удалить все трейсы бота можно через DELETE /v1/admin/workspaces/{workspaceId}/bots/{botId}/traces. Режимы unscoped listing, follow и trigger не поддерживаются.

Диалоги

brt conversations list

brt conversations list [tokens..]
                       [--dev]
                       [--since <RFC3339|duration>] [--limit <n>]
                       [--next-token <cursor>] [--json]

Показывает последние conversations выбранного target без message content и conversation tags. Human output содержит timestamp, ID, integration/channel и messageCount. Стабильный JSON envelope имеет schemaVersion, canonical target, массив conversations и server-issued nextToken; каждая запись ограничена полями id, createdAt, updatedAt, channel, integration и messageCount.

Совместимые tokens повторяют актуальный Botpress ADK CLI:

Один фильтр нельзя одновременно задавать token и named flag. Клиент валидирует limit, calendar-correct RFC3339 и positive-decimal cursor до network. Backend page не превышает 1000 строк; CLI ограничивает общее число страниц, обнаруживает cursor loop и использует только meta.nextToken, не вычисляя продолжение из ID.

brt conversations list
brt conversations list limit=5 since=1h
brt conversations list --dev --limit 100 --json
brt conversations list --limit 100 --next-token 456 --json

brt conversations show

brt conversations show <conversationId> [tokens..]
                       [--since <RFC3339|duration>]
                       [--until <RFC3339|duration>]
                       [--limit <n>] [--next-token <cursor>]
                       [--dev] [--json]

Строит metadata-only timeline из bounded trace API. Команда не читает весь диалог: по умолчанию она запрашивает не больше 20 сырых trace rows. limit считается до группировки строк по typed traceId, поэтому traceCount может отличаться от turnCount.

Каждый turn содержит timestamp, duration, effective status, bounded trigger/tool metadata и errorKind. Полная ошибка конкретного span читается через brt traces trace=<traceId> --verbose. Conversation ID валидируется до network. Если для ID нет trace rows, команда возвращает пустой timeline, а не подмешивает другой conversation.

Совместимые tokens задают то же окно, что named flags:

Один фильтр нельзя одновременно задавать token и named flag. Для duration CLI фиксирует общий now один раз, вычисляет обе границы от этого момента и отправляет их серверу как абсолютные timestamps. since не может быть позже until.

Production использует canonical positive-decimal workspace/bot route и PAT выбранного профиля; dev использует тот же PAT, существующий opaque x-bot-id resolver и target, ранее доказанный brt dev. Набор фильтров и правила пагинации в production и dev одинаковы; различаются только существующие target resolution и auth route.

При limit <= 1000 CLI делает один trace request. Большой явный limit может прочитать несколько страниц, но не больше общего лимита. nextToken — выданный сервером positive-decimal cursor для следующей, более старой части timeline. Human output печатает Next token: ... и готовую команду Continue: ... с заданными временными границами в абсолютном виде, исходным limit и --next-token.

JSON сохраняет schemaVersion: 1 и поля target, conversationId, traceCount, turnCount, turns, nextToken (string | null) и truncated. truncated: true означает, что сервер вернул cursor продолжения.

# Bare-вызов: не больше 20 сырых trace rows
brt conversations show conv_123

# Botpress-совместимые tokens
brt conversations show conv_123 since=1h until=5m limit=20

# Те же фильтры named flags
brt conversations show conv_123 \
  --since 2026-07-23T08:00:00Z \
  --until 2026-07-23T09:00:00Z \
  --limit 100

# JSON-пагинация: cursor продолжает то же абсолютное окно
brt conversations show conv_123 \
  --since 2026-07-23T08:00:00Z \
  --until 2026-07-23T09:00:00Z \
  --limit 20 \
  --json
brt conversations show conv_123 \
  --since 2026-07-23T08:00:00Z \
  --until 2026-07-23T09:00:00Z \
  --limit 20 \
  --next-token 456 \
  --json

# Те же фильтры для attested dev target
brt conversations show conv_123 since=30m limit=20 --dev

Команда не принимает --follow и --include-llm. Она не печатает prompts, model responses, tool input/output, message/document payloads, conversation tags и неотфильтрованные attrs/payload. Для разрешённой подробной диагностики используйте brt traces по trace ID.

Hosted evals

brt eval / brt eval run

brt eval [name]
brt eval run [name]
             [--tag <tag>] [--type capability|regression]
             [--judge-model <model>] [--timeout <ms>]
             [--repeat <1-100>] [--max-concurrency <1-10>]
             [--min-pass-rate <0-1>]
             [--dev] [--json]

Обе формы запускают builtin_eval_runner на выбранном hosted target и ждут terminal result. Bare brt eval повторяет default-action актуального Botpress ADK CLI; run — явная форма для скриптов и discoverable command tree. Перед запуском CLI загружает определения из evals/*.eval.ts, синхронизирует metadata-only manifest и приватные fixture-файлы, а также проверяет или автоматически устанавливает точную совместимую версию first-party chat. Runner сохраняет каждую завершённую проверку как отдельный workflow checkpoint: длинный suite продолжается в новых runtime invocation без повторной отправки уже выполненных chat-turn-ов и без дублирования результатов.

Terminal polling ограничен общим --timeout, но не обрывается из-за одного исчерпанного transient retry идемпотентного GET. CLI продолжает читать тот же workflow — не создаёт новый run и не повторяет side effects — и, если Cloud уже завершил связанный EvalRun, возвращает именно его terminal detail и ненулевой exit code для failed suite.

Production использует canonical positive-decimal workspace/bot link и per-bot key из ~/.brt/bots.json; существующий бот перепривязывается через brt link --key-stdin. Dev использует PAT выбранного профиля, narrowed только существующим opaque x-bot-id resolver. Path/query ID не задаёт tenant scope.

При brt dev CLI передаёт server-owned связь development-runtime с production из agent.json или bot.json. Сервер требует эту связь при первом создании и не позволяет перепривязать существующий runtime к другому проекту. Повторный запуск использует target из agent.local.json, поэтому его hosted eval history остаётся доступна в Development-переключателе консоли. Production и Development по-прежнему имеют разные данные и результаты.

brt eval
brt eval greeting
brt eval run greeting --tag smoke --type regression
brt eval run --judge-model openai:gpt-4o --json
brt eval run regression --repeat 10 --max-concurrency 2 --min-pass-rate 0.9
brt eval run --dev

При repeat > 1 каждый повтор получает отдельные workflow/run/conversation и state. Итог содержит pass rate, stable | flaky, p50/p95 duration и histogram только по assertion kind. Сообщения, prompts и tool payload в aggregate не попадают.

Fixtures, actors и test-only controls

Attachment объявляется локальным fixture. CLI проверяет, что путь остаётся внутри проекта, считает sha256, ограничивает один файл 20 MiB и весь suite 100 MiB, загружает файл с private integrations access и удаляет локальный путь из hosted manifest. Runner получает свежий короткоживущий URL непосредственно перед ходом и отправляет обычный file/image message payload.

export default new Eval({
  name: 'catalog-upload',
  fixtures: {
    catalog: { path: 'fixtures/catalog.pdf', contentType: 'application/pdf', name: 'catalog.pdf' },
  },
  conversation: [
    { actor: 'client', message: 'Изучи каталог', attachments: [{ fixture: 'catalog' }] },
  ],
})

Durable table fixtures объявляются в setup.tables. Перед первым ходом runner создаёт строки обычным Tables API, заменяет {{eval.id}} одним execution-scoped значением во всём setup и табличных assertions, а после grading удаляет только созданные им row ID. Частичное создание или удаление завершает eval стабильной ошибкой: runner не очищает таблицу целиком и не скрывает утечку fixture. Это manifest schema v2: старый runtime отклонит её явно, а не проигнорирует durable setup. После обновления runtime повторно запустите brt eval, чтобы синхронизировать manifest.

Табличные assertions доступны как на отдельном ходе, так и в outcome. Поддерживаются совместимые с Botpress формы row_exists и row_count с необязательным where; в результат попадают только счётчики, без содержимого строк.

export default new Eval({
  name: 'order-is-durable',
  setup: {
    tables: [
      {
        table: 'OrderTable',
        rows: [{ externalId: 'eval-{{eval.id}}', status: 'pending' }],
      },
    ],
  },
  conversation: [
    {
      message: 'Проверь тестовый заказ',
      assert: {
        tables: [
          { table: 'OrderTable', row_exists: { externalId: { equals: 'eval-{{eval.id}}' } } },
        ],
      },
    },
  ],
  outcome: {
    tables: [
      {
        table: 'OrderTable',
        row_count: { equals: 1 },
        where: { externalId: { equals: 'eval-{{eval.id}}' } },
      },
    ],
  },
})

Для multi-actor сценария setup.relations резолвит связанный conversation по integration/channel/tags. Ход с target.relation создаётся как synthetic incoming message именно в этом conversation. Assertions deliveredTo, notDeliveredTo и conversationMode проверяют новые исходящие после baseline, а не совпадение текста в общем transcript.

setup: {
  relations: {
    operator: { integration: 'telegram', channel: 'channel', tags: { upstream: '$conversationId' } },
  },
},
conversation: [
  { actor: 'operator', target: { relation: 'operator' }, message: '/take' },
  { actor: 'client', message: 'Нужна помощь с заказом', expectSilence: true },
  {
    actor: 'operator', target: { relation: 'operator' },
    message: 'Заявка принята.', assert: { deliveredTo: 'client' },
  },
]

parallel и control доступны только isolated dev target. Production suite с ними отклоняется capability-preflight до создания run. advanceClock двигает монотонные часы конкретного dev-бота и делает due workflow jobs доступными воркеру; fault plan атомарно расходует failAfter/times на закрытых точках, поддерживает 429/503 и lost_ack только после успешного handler.

Hosted runner выдаёт table seed, native event и каждой control-операции стабильный effect ID. Cloud сохраняет результат вместе с самой мутацией в одной транзакции: повтор после потерянного ответа возвращает исходный результат и не создаёт второй row/event/clock advance. Повтор того же ID с другим payload отклоняется как конфликт до выполнения side effect.

conversation: [
  { control: { faults: [{ point: 'workflow.after_dispatch', failAfter: 1, times: 1, mode: 'lost_ack' }] } },
  { parallel: [{ message: 'Повтор A' }, { message: 'Повтор B' }] },
  { control: { advanceClock: { milliseconds: 72 * 60 * 60 * 1000, runDueWorkflows: true } } },
]

brt eval runs

brt eval runs [runId]
              [--latest] [--status pending|running|completed|failed]
              [--limit <1-100>] [--next-token <cursor>]
              [--verbose] [--dev] [--json]

Без selector команда возвращает одну server page hosted run summaries. --latest сначала выбирает последний run и затем получает detail; positional runId — строгий positive-decimal ID. --status и --next-token относятся только к listing и не смешиваются с detail selector. Продолжение берётся только из server-issued opaque base64url nextToken.

Detail содержит run/entry IDs, status, trigger type, timestamps, typed errorKind, eval name/type/tags, verdict, duration и allowlisted assertion metadata. Для каждого хода доступны opaque conversationId и traceId, а для ошибки исполнения — стабильные errorCode, phase и turn index. --verbose добавляет human-readable assertion rows и печатает готовую команду brt traces --conversation-id <id>. JSON сохраняет те же безопасные поля в versioned metadata-only форме.

brt eval runs --limit 10 --status completed
brt eval runs --limit 10 --next-token MTAw --json
brt eval runs --latest --json
brt eval runs 101 --verbose

Prompts, user/bot messages, model responses, evidence, tool input/output, documents, raw evaluator errors и произвольный workflow failure reason исключаются из stdout/stderr даже при --verbose, malformed response или network failure. Известный код workflow delivery unavailable переводится в фиксированную подсказку проверить запущенный brt dev и tunnel, без отражения серверного текста. Auth/target/HTTP/cursor/timeout ошибки и failed suite возвращают ненулевой exit code с remediation.

brt eval runs 101 --verbose
# diagnostic code=CHAT_PAYLOAD_INVALID  phase=observation  turn=0
# inspect: brt traces --conversation-id conv_eval_1  traceId=0123456789abcdef0123456789abcdef

brt traces --conversation-id conv_eval_1

Логи

brt logs [--bot-id <id>] [--dev] [--since <RFC3339|duration>]
         [--until <RFC3339|duration>]
         [--level <level>] [--grep <text>] [--conversation-id <id>]
         [--follow] [--limit <n>]

Команда реализует фильтры, пагинацию nextToken и polling --follow. Запрос идёт на workspace-scoped маршрут /v1/admin/workspaces/{workspaceId}/bots/{botId}/logs с PAT выбранного профиля; per-bot key не используется. Без --dev target берётся из production link, а --dev резолвит opaque runtime target из dev cache в attested numeric bot. Вместе с --dev можно явно передать opaque runtime ID через --bot-id; без --dev этот флаг принимает только production numeric bot ID. Для обязательной production-проверки дополните логи реальным каналом и web inspector. Вывод logs текстовый; глобальный --json здесь не является контрактом.

--since и --until принимают RFC3339 или look-back duration относительно одного времени запуска команды: например, --since 10m --until 30s. CLI преобразует duration в RFC3339 до запроса, отклоняет невалидное время локально и не допускает since позже until. Без --since используется один час назад.

Логи в облако попадают только из production-супервизора. brt dev пишет вывод воркера прямо в свой терминал и никогда не отправляет его в облако, поэтому brt logs --dev для только что запущенного dev-бота пуст — это ожидаемо, а не поломка. При пустом результате на --dev target команда сама печатает эту подсказку и советует свериться с терминалом brt dev.

Локальная разработка

brt serve (classic project)

brt serve [--port <n>] [--secrets <k=v>...] [--work-dir <path>]

Запускает уже собранный classic bundle без Cloud side effects. Root agent-проект на agent.config.ts команда не принимает; для него используйте brt dev.

brt chat

brt chat [<botId>] [--dev] [--chat-api-url <url>] [--protocol polling]

Создаёт новый интерактивный Chat conversation для target проекта. По умолчанию это production target из canonical link; Chat integration проверяется и при необходимости устанавливается/регистрируется под workspace PAT с owner/admin guard. Сама беседа использует Chat webhook и отдельную user identity, поэтому per-bot key и brt link не нужны. --dev выбирает attested dev runtime из agent.local.json/project cache, использует PAT профиля и направляет Chat в связанный dev bot. Обычно для dev достаточно brt chat --dev; positional ID нужен только как явный override.

CLI проверяет точную совместимую версию first-party Chat integration и при необходимости устанавливает её в выбранное окружение. --local допустим только вместе с --dev.

--chat-api-url — advanced override Chat endpoint для прокси и разработки платформы. Обычный запуск использует endpoint активного профиля.

brt dev

brt dev [--watch | --no-watch] [--port <n>] [--tunnel-url <url>]
brt dev --check [--json]

Для agent-проекта автоматически генерирует classic bot, минтит отдельного dev-бота и гонит Cloud traffic в локальный worker через reverse-tunnel. Для classic-проекта запускает тот же tunnel loop напрямую. По изменению файлов пересобирает и обновляет только dev target.

Каждый brt dev сверяет точное состояние Cloud-зависимостей до generation и не переиспользует устаревший snapshot без новой сверки.

После разрыва уже работающего tunnel CLI объединяет одновременные error/close сигналы в один reconnect loop и повторяет соединение с exponential backoff от 250 ms до 5 s в пределах 120 s. Если окно исчерпано, brt dev завершается ошибкой; бесконечного скрытого retry нет.

dev --check — read-only gate: один физический GET без retries, PUT и локальных записей. Он сверяет cached target, .adk/dependencies/dev.json, полный inventory bp_modules и authoritative Cloud identity/config revision/lifecycle. Любой unknown, partial или drift даёт ненулевой exit code.

Проверка намеренно не является bootstrap-командой. На fresh agent-проекте сначала один раз успешно запустите обычный brt dev: он докажет target, прочитает authoritative-состояние в Cloud и создаст snapshot. После этого используйте dev --check локально или в CI. Не создавайте .adk/dependencies/* вручную.

Дальше