NestJS AI Agent

A production-ready NestJS backend demonstrating AI-driven agent architecture with MongoDB persistence, pluggable AI services, and flexible premium data modes.

Overview

This project showcases clean separation-of-concerns principles:

• Orchestration: AgentService coordinates data fetching and AI calls
• Persistence: Mongoose + MongoDB for customer/policy data
• AI Integration: Pluggable service (OpenAI by default, extensible to LangChain)
• Premium Data: External APIs, mock servers, or local computation
• Monitoring: Built-in health checks and graceful shutdown

Core Principles: KISS, DRY, and clear module boundaries

Features

• ✅ Mongoose + MongoDB integration with schema validation
• ✅ Health check endpoint (GET /api/health) for readiness
• ✅ Agent endpoint (GET /api/agent/customer/:id/insight) for AI insights
• ✅ Customer CRUD (POST /api/customer, GET /api/customer)
• ✅ Pluggable AI service (OpenAI by default)
• ✅ Premium data modes: external API, local computation, mock server
• ✅ Global validation pipe with class-validator
• ✅ Graceful shutdown and error handling

Prerequisites

• Node.js ≥ 18.x
• Yarn or npm
• MongoDB (local, Docker, or Atlas)

Quick Start

1. Install dependencies

yarn install

2. Configure environment

Create a .env file:

MONGODB_URI=mongodb://localhost:27017/ai-agent
OPENAI_API_KEY=sk_test_...
OPENAI_MODEL=gpt-3.5-turbo
PREMIUM_API_MODE=local
PORT=3000

3. Start the application

yarn start:dev

Expected output: Listening on http://localhost:3000/api

API Endpoints

Health Check

GET /api/health

Response: { "status": "up", "mongo": { "readyState": 1 }, "timestamp": "..." }

Create Customer

POST /api/customer
Content-Type: application/json

Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1-555-0100",
  "policies": [{ "policyNumber": "POL-001", "type": "auto", "coverageAmount": 50000 }]
}

List Customers

GET /api/customer

Get Agent Insight

GET /api/agent/customer/:customerId/insight

Response: { "customer": {...}, "premium": {...}, "answer": "..." }

Premium Data Modes

Mode: local (default)

Computes premium from customer policies — no external calls.

export PREMIUM_API_MODE=local
yarn start:dev

Mode: mock

Calls local mock premium API server.

# Terminal 1
node scripts/mock-premium.js

# Terminal 2
export PREMIUM_API_URL=http://localhost:4000
export PREMIUM_API_MODE=mock
yarn start:dev

Mode: external

Calls a real external premium API.

export PREMIUM_API_URL=https://api.your-service.com
export PREMIUM_API_MODE=external
yarn start:dev

Project Structure

src/
├── agent/       # Agent orchestration
├── customer/    # Customer CRUD
├── ai/          # AI service wrapper
├── health/      # Health checks
├── pipes/       # Validation
└── main.ts      # Bootstrap

Scripts

yarn start:dev           # Development watch mode
yarn build               # TypeScript build
yarn start:prod          # Production
yarn test                # Unit tests
yarn test:e2e            # E2E tests
yarn test:cov            # Coverage
node scripts/mock-premium.js  # Mock premium API

Troubleshooting

Issue	Solution
MongoDB connection fails	Ensure MongoDB is running; check MONGODB_URI
AI responses are fallback	Set valid OPENAI_API_KEY
Premium API errors	Use local mode or start mock server

Next Steps

• Add unit tests for AgentService, CustomerService, AiService
• Integrate Swagger/OpenAPI documentation
• Add LangChain for advanced prompt management
• Implement JWT authentication
• Add pagination for customer endpoints

License

MIT