Перейти к основному содержимому

Начало работы

AgentCore — многопользовательский бэкенд AI-агента, который пропускает запросы сотрудников через RAG, процессы утверждения и интеграции с каналами. В этом руководстве — как установить и запустить его локально.

Требования​

  • Node.js 22+ (рекомендуется LTS)
  • Docker и Docker Compose (для PostgreSQL и Redis)
  • Ключ OpenAI API с доступом к gpt-4o и text-embedding-3-small

Установка​

# Clone the repository
git clone <repo-url>
cd kalheon_agents

# Install dependencies
npm install

Инфраструктура​

Поднимите PostgreSQL 16 (с pgvector) и Redis 7:

docker compose up -d

Запустятся:

  • agentcore_postgres на порту 5432 (пользователь: agentcore, пароль: agentcore)
  • agentcore_redis на порту 6379

Проверьте, что оба контейнера в порядке:

docker compose ps

Переменные окружения​

cp .env.example .env

Отредактируйте .env и задайте как минимум:

ПеременнаяЗначение
OPENAI_API_KEYВаш ключ OpenAI API
JWT_SECRETСлучайная строка не короче 32 символов
PII_ENCRYPTION_KEY32-байтовый ключ в Base64, сгенерированный командой node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

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

Инициализация БД​

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# (Optional) Seed initial data
npm run db:seed

Запуск сервера​

npm run dev

Сервер поднимется на http://localhost:3000 с hot reload.

  • Swagger UI: http://localhost:3000/docs
  • Health check: http://localhost:3000/api/v1/health

Первые шаги​

1. Сид отделов и пользователей​

Для локальной демки запустите:

npm run db:seed

Создаст демо-отделы, namespaces, пользователей, профили и примеры переписок.

2. Регистрация пользователя​

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email": "employee@example.com", "password": "securepass123", "name": "Employee", "departmentId": "<department-id>"}'

Самостоятельная регистрация всегда создаёт роль employee. Для повышения роли используйте API администратора (/api/v1/users, /api/v1/roles) или Prisma Studio:

npm run db:studio

3. Создайте базу знаний​

Авторизуйтесь, чтобы получить JWT-токен, затем создайте базу знаний и загрузите документы через API или админ-панель.

4. Подключите канал​

Пропишите учётные данные WhatsApp или Telegram в .env и перезапустите сервер. См.:

Фронтенд​

React-админка лежит в frontend/. Для разработки:

cd frontend
npm install
npm run dev    # http://localhost:5173

В .env задайте ALLOWED_ORIGINS=http://localhost:5173 (это дефолт).

Запуск тестов​

# Set up test database
npm run test:db:setup

# Run tests
npm test

# Watch mode
npm run test:watch

Тесты работают с отдельной БД, прописанной в .env.test.