Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact
  1. Home
  2. Learn
  3. AI quickstarts
  4. rh-ai-virtual-agent

Build an AI-powered virtual agent

View on GitHub

Build and deploy a conversational AI virtual agent on Red Hat OpenShift AI to automate customer interactions and provide instant support.

OpenShift AIConversational agentsAdopt and scale AI

This content is authored by Red Hat experts, but has not yet been tested on every supported configuration.

Build an AI-powered virtual agent
Copy link

GitHub release Docker Image

Build and deploy a conversational AI virtual agent on Red Hat OpenShift AI to automate customer interactions and provide instant support.

Detailed description
Copy link

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
Copy link

  • 🤖 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

Architecture Overview
Copy link

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

Architecture

📖 Detailed Architecture →

Requirements
Copy link

Minimum hardware requirements
Copy link

For a full working version with local inference:

  • GPU - Required for running inference locally
  • Alternatively, you can deploy without a GPU by using:
    • Remote vLLM deployment
    • Vertex AI

Minimum software requirements
Copy link

  • Red Hat OpenShift - Container orchestration platform
  • Red Hat OpenShift AI - AI/ML platform for model serving and management
  • oc CLI - OpenShift command-line tool
  • make - Build automation tool
  • Hugging Face token - With access to models (some models require authorization)

Required user permissions
Copy link

  • Cluster admin access - Required for installing ClusterRole resources for OAuth authentication

Deploy
Copy link

Cluster Deployment
Copy link

For production installation on Kubernetes/OpenShift:

# clone the repository
git clone https://github.com/rh-ai-quickstart/ai-virtual-agent.git

# Navigate to cluster deployment directory
cd deploy/cluster

# Install with interactive prompts for configuration
make install NAMESPACE=your-namespace
Copy to Clipboard Toggle word wrap

🧭 Advanced instructions →

📖 Full Installation Guide →

Delete
Copy link

To remove the application and all associated resources:

cd deploy/cluster
make uninstall NAMESPACE=your-namespace
Copy to Clipboard Toggle word wrap

This will automatically clean up the Helm chart, deployed resources, and PVCs.

Example Use Case
Copy link

Creating a Customer Support Agent with Knowledge Base

import requests

BASE_URL = "http://localhost:8000/api/v1"

# 1. Create a knowledge base
kb_response = requests.post(
    f"{BASE_URL}/knowledge_bases",
    json={
        "vector_store_name": "support-docs-v1",
        "name": "Support Documentation",
        "version": "v1",
        "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
        "provider_id": "ollama",
        "source": "S3"
    }
)
print(f"Knowledge base created: {kb_response.status_code}")

# 2. Create a support agent
agent_response = requests.post(
    f"{BASE_URL}/virtual_agents",
    headers={
        "X-Forwarded-User": "admin",
        "X-Forwarded-Email": "admin@change.me"
    },
    json={
        "name": "Support Agent",
        "model_name": "meta-llama/Llama-3.2-3B-Instruct",
        "prompt": "You are a helpful customer support agent",
        "knowledge_base_ids": ["support-docs-v1"],
        "tools": [{"toolgroup_id": "builtin::web_search"}],
        "temperature": 0.7,
        "top_p": 0.9,
        "max_tokens": 2048
    }
)
agent_id = agent_response.json()["id"]
print(f"Agent created: {agent_id}")

# 3. Create a chat session
session_response = requests.post(
    f"{BASE_URL}/chat_sessions",
    json={
        "agent_id": agent_id,
        "session_name": "Customer Support Session"
    }
)
session_id = session_response.json()["id"]
print(f"Chat session created: {session_id}")

# 4. Send a chat message
chat_response = requests.post(
    f"{BASE_URL}/chat",
    json={
        "virtualAgentId": agent_id,
        "sessionId": session_id,
        "message": {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Who is the first president of the United States?"
                }
            ]
        },
        "stream": False
    }
)
answer = chat_response.json()
print(f"Agent response: {answer}")
Copy to Clipboard Toggle word wrap

Advanced instructions
Copy link

Getting Started Guides
Copy link

👩‍💻 For Developers
Copy link

🚀 For Deployment
Copy link

🔧 For Integration
Copy link

Project Structure
Copy link

ai-virtual-agent/
├── frontend/           # React UI with PatternFly components
├── backend/            # FastAPI server with PostgreSQL
├── docs/               # Architecture and API documentation
├── deploy/
│   ├── cluster/        # Kubernetes/Helm cluster deployment
│   │   ├── helm/       # Helm chart files
│   │   ├── scripts/    # Cluster deployment scripts
│   │   ├── Containerfile # Cluster container image
│   │   └── Makefile    # Cluster deployment commands
│   └── local/          # Local development deployment
│       ├── compose.dev.yaml # Docker Compose for local dev
│       ├── dev/        # Local development configs
│       └── Makefile    # Local development commands
└── tests/              # Integration test suite
Copy to Clipboard Toggle word wrap

Local Development
Copy link

For local containerized development (without cluster):

📖 → See Local Development Guide

Note: Local setup has limited functionality compared to OpenShift AI deployment:

  • No authentication/authorization
  • Knowledge bases not available
  • MCP servers not tested

These features are only available with the full OpenShift AI deployment.

cd deploy/local

# Start all services
make compose-up

# Other available commands
make compose-down        # Stop all services
make compose-logs        # View logs
make compose-restart     # Restart services
make compose-status      # Show status
Copy to Clipboard Toggle word wrap

Access your app:

Cluster Development
Copy link

cd deploy/cluster

# Install on cluster
make install NAMESPACE=your-namespace

# Other available commands
make uninstall NAMESPACE=your-namespace    # Remove application
make install-status NAMESPACE=your-namespace    # Check status
make list-mcps                              # List available MCP servers
Copy to Clipboard Toggle word wrap

Note: All Makefile targets automatically load environment variables from a .env file in the repository root if it exists.

Environment setup (.env)
Copy link

Create a .env file in the repository root to configure your local environment. All Makefile targets will dynamically load this file if present:

cp .env.example .env
# then edit `.env` as needed
Copy to Clipboard Toggle word wrap

At minimum, set:

DATABASE_URL=postgresql+asyncpg://admin:password@localhost:5432/ai_virtual_agent
Copy to Clipboard Toggle word wrap

Optional toggles:

# Skip attachments bucket initialization/access during local dev
DISABLE_ATTACHMENTS=true

# Provide admin bootstrap for Alembic seeding (optional)
# ADMIN_USERNAME=admin
# ADMIN_EMAIL=admin@change.me
Copy to Clipboard Toggle word wrap

Note: If you're not using attachments in local dev, you can set DISABLE_ATTACHMENTS=true in .env to skip attachment-related initialization.

Community & Support
Copy link

License
Copy link

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

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat