Конфигурация проекта

agent.config.ts, состояние, deploy-настройки, секреты, события и модели.

agent.config.ts описывает публичный контракт бота. Файл хранится в Git и проверяется при brt check, brt dev и deploy.

Минимальная конфигурация

agent.config.ts

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

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

name — стабильное техническое имя. Не используйте в нём окружение, версию или имя разработчика.

Состояние

Опишите состояние пользователя и бота zod-схемами:

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

export default defineConfig({
  name: 'support-bot',
  user: {
    state: z.object({
      locale: z.string().default('ru'),
      customerId: z.string().optional(),
    }),
  },
  bot: {
    state: z.object({
      catalogVersion: z.string().optional(),
    }),
  },
})

Состояние диалога объявляется в Conversation, а состояние процесса — в Workflow. Подробности находятся на странице «Состояние».

Deploy-настройки

configuration.schema описывает значения, которые отличаются между dev и production. Они не входят в исходный код.

export default defineConfig({
  name: 'support-bot',
  configuration: {
    schema: z.object({
      crmProjectId: z.string().describe('ID проекта в CRM'),
      maxSearchResults: z.number().int().min(1).max(20).default(5),
      enableOrderCancellation: z.boolean().default(false),
    }),
  },
})

Задавайте значение через stdin или файл:

printf '%s' 'crm-project-42' | brt config set crmProjectId
brt config list

config list показывает имена и время обновления, но не раскрывает значения.

Секреты

Объявите секреты отдельно от обычной конфигурации:

export default defineConfig({
  name: 'support-bot',
  secrets: {
    CRM_API_KEY: {
      description: 'Ключ API CRM',
    },
    OPTIONAL_WEBHOOK_SECRET: {
      optional: true,
      description: 'Секрет исходящего webhook',
    },
  },
})

printf '%s' "$CRM_API_KEY" | brt secret set CRM_API_KEY

В runtime значения доступны через secrets.CRM_API_KEY. Не добавляйте токены в configuration, .env.example, логи или аргументы команды.

Credentials интеграции задаются при brt integrations install. Не дублируйте их в секретах бота.

События

Свои события объявляются с именем, описанием и схемой payload:

export default defineConfig({
  name: 'support-bot',
  events: {
    orderUpdated: {
      description: 'Статус заказа изменился',
      schema: z.object({
        orderNumber: z.string(),
        status: z.string(),
      }),
    },
  },
})

Conversation получает такое событие с type: 'event'. Воркфлоу общается с диалогом через workflow_request и workflow_callback.

Модели

defaultModels задаёт модели для агентного цикла и LLM-утилит:

export default defineConfig({
  name: 'support-bot',
  defaultModels: {
    autonomous: 'auto',
    zai: 'auto',
  },
})

auto передаёт выбор платформе. Конкретный вызов execute() может переопределить модель.

Прочитайте значения в runtime

import { configuration, secrets, user } from '@holocronlab/botruntime-runtime'

const projectId = configuration.crmProjectId
const apiKey = secrets.CRM_API_KEY
const locale = user.state.locale

configuration и secrets доступны только в контексте текущего вызова. Не читайте их при импорте модуля.