Skip to main content

Getting Started

AgentCore is a multi-tenant AI agent backend. It routes employee queries through RAG, approval, and channel integrations. This guide covers a local install.

Prerequisites​

  • Node.js 22+ (LTS recommended)
  • Docker and Docker Compose (for PostgreSQL and Redis)
  • OpenAI API key with access to gpt-4o and text-embedding-3-small

Installation​

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

# Install dependencies
npm install

Infrastructure​

Start PostgreSQL 16 (with pgvector) and Redis 7:

docker compose up -d

This starts:

  • agentcore_postgres on port 5432 (user: agentcore, password: agentcore)
  • agentcore_redis on port 6379

Verify both are healthy:

docker compose ps

Environment Configuration​

cp .env.example .env

Edit .env and set at minimum:

VariableWhat to set
OPENAI_API_KEYYour OpenAI API key
JWT_SECRETRandom string, at least 32 characters
PII_ENCRYPTION_KEYBase64-encoded 32-byte key generated with node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

All other variables have sensible defaults for local development.

Database Setup​

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

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

Start the Server​

npm run dev

The server starts at http://localhost:3000 with hot reload enabled.

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

First Steps​

1. Seed Departments and Users​

For a local demo, run:

npm run db:seed

This creates demo departments, namespaces, users, profiles, and sample conversations.

2. Register a User​

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>"}'

Self-registration always creates an employee. Use the admin API (/api/v1/users, /api/v1/roles) or Prisma Studio to promote roles when needed:

npm run db:studio

3. Create a Knowledge Base​

Login to get a JWT token, then create a knowledge base and upload documents through the API or the frontend dashboard.

4. Connect a Channel​

Configure WhatsApp or Telegram credentials in .env and restart. See:

Frontend​

The React admin dashboard is in frontend/. To develop:

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

Set ALLOWED_ORIGINS=http://localhost:5173 in .env (default).

Running Tests​

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

# Run tests
npm test

# Watch mode
npm run test:watch

Tests use a separate database configured in .env.test.