AI Virtual Agent Kickstart

A platform for creating and managing AI-powered virtual agents with knowledge base integration, built on top of LlamaStack.

What is this?

This platform provides the tools to build and deploy conversational AI agents that can:

• Access knowledge bases - Upload documents and create searchable knowledge bases for RAG (Retrieval-Augmented Generation)
• Use tools - Integrate web search, databases, and custom tools through the Model Context Protocol (MCP)
• Apply guardrails - Built-in safety measures and content filtering
• Scale in production - Kubernetes-ready architecture

Key Features

🤖 Agent Management - Create and configure AI agents with different capabilities 📚 Knowledge Integration - Document search and question answering via RAG 💬 Real-time Chat - Streaming conversations with session history 🔧 Tool Ecosystem - Built-in tools plus extensible MCP server support 🛡️ Safety Controls - Configurable guardrails and content filtering

Quick Start

Installation

Option 1: One-command setup

git clone https://github.com/rh-ai-kickstart/ai-virtual-agent
cd ai-virtual-agent
make install dev

Option 2: Step-by-step

# 1. Start database
podman compose up -d

# 2. Start backend
cd backend && python -m venv venv && source venv/bin/activate
pip install -r requirements.txt && alembic upgrade head
uvicorn main:app --reload &

# 3. Start frontend
cd ../frontend && npm install && npm run dev

Access your app:

• Frontend: http://localhost:5173
• API: http://localhost:8000
• Docs: http://localhost:8000/docs

Production Deployment

For production installation on Kubernetes/OpenShift:

make install NAMESPACE=ai-virtual-agent

📖 Full Installation Guide →

Project Structure

ai-virtual-agent/
├── frontend/           # React UI with PatternFly components
├── backend/            # FastAPI server with PostgreSQL
├── mcpservers/         # Custom MCP tool servers
├── docs/               # Architecture and API documentation
├── helm/               # Kubernetes and Helm deployment
├── scripts/            # Development and deployment scripts
└── tests/              # Integration test suite

Architecture Overview

The platform integrates several components:

• React Frontend - Web interface for agent and chat management
• FastAPI Backend - API server handling business logic and data persistence
• LlamaStack - AI platform managing models, agents, and inference
• PostgreSQL + pgvector - Data storage with vector search capabilities
• Kubernetes Pipeline - Document processing and knowledge base ingestion

📖 Detailed Architecture →

Getting Started Guides

👩‍💻 For Developers

• Contributing Guide - Development setup and workflow
• Backend API Reference - Complete API documentation
• Frontend Architecture - UI components and patterns

🚀 For Deployment

• Installation Guide - Production deployment on Kubernetes
• Agent Templates - Pre-built agent configurations
• Knowledge Base Setup - Document processing pipeline

🔧 For Integration

• MCP Servers - Building custom tool integrations
• Testing Guide - Running integration tests
• API Reference - Backend API endpoints

Example Use Cases

Customer Support Agent

const agent = await createAgent({
  name: "Support Bot",
  model: "llama3.1-8b-instruct",
  knowledge_bases: ["support-docs"],
  tools: ["builtin::rag", "builtin::web_search"]
});

Domain Expert (Banking)

const expert = await initializeAgentTemplate({
  template: "commercial_banker",
  knowledge_bases: ["banking-regulations"]
});

Development Commands

# Start everything locally
make dev

# Run tests
make test

# Stop all services
make stop

# Reset database
make reset-db

Community & Support

• 🐛 Issues - Report bugs and request features
• 💬 Discussions - Ask questions and share ideas
• 🤝 Contributing - See CONTRIBUTING.md for guidelines
• 📚 Documentation - Browse /docs for detailed guides

License

MIT License - Built with ❤️ by the Red Hat Ecosystem App Engineering team