Перейти до основного вмісту

Початок роботи

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

Скрипт створить демонстраційні відділи, простори імен, користувачів, профілі та приклади розмов.

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

Задайте ALLOWED_ORIGINS=http://localhost:5173 у .env (стоїть за замовчуванням).

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

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

# Run tests
npm test

# Watch mode
npm run test:watch

Тести використовують окрему БД, налаштовану в .env.test.