Most AI chatbots answer from training data. RAG (Retrieval-Augmented Generation) enables AI assistants that answer from your documents, your knowledge base, your content.
The Laravel AI RAG Agent Demo is an open-source project that showcases how to build production-ready knowledge assistants using Laravel AI SDK, PostgreSQL with pgvector, and intelligent document processing. This isn't a proof-of-concept. It's a complete, production-ready application demonstrating how to transform static documentation into dynamic, conversational interfaces.
Try the live demo at laravel-ai-rag-agent-demo.on-forge.com to see RAG in action—or clone the source code on GitHub to explore the implementation and deploy your own RAG-powered knowledge assistant.
The global knowledge management market is projected to reach $1.1 trillion by 2026, driven by organizations seeking better ways to make information accessible. RAG bridges the gap between vast document collections and actionable insights, enabling AI assistants that understand context and retrieve relevant information on demand.
What RAG Solves
Traditional AI assistants have a fundamental limitation: they only know what they were trained on. They can't access your internal documentation, your product specifications, or your company knowledge base. RAG solves this by:
- Retrieving relevant context from your documents before generating responses
- Grounding answers in your actual content, not generic training data
- Enabling domain expertise without retraining models
- Maintaining accuracy by citing source material
The result: AI assistants that understand your business, your products, and your knowledge—not just general information.
The Architecture: Laravel AI SDK + pgvector
The Laravel AI RAG Agent Demo combines three powerful technologies:
Laravel AI SDK
Laravel AI SDK provides the foundation for AI interactions. It handles:
- Embedding generation — Converting text into vector representations
- Agent creation — Building conversational interfaces with memory
- Streaming responses — Delivering answers in real-time
- Error handling — Graceful fallbacks and user-friendly messages
The SDK makes AI features feel native to Laravel, not bolted-on integrations.
PostgreSQL with pgvector
pgvector extends PostgreSQL with vector similarity search capabilities. It enables:
- Efficient storage — Embeddings stored alongside traditional data
- Fast retrieval — Cosine similarity search in milliseconds
- Scalability — Handle millions of document chunks
- Familiar tooling — Use existing PostgreSQL infrastructure
Vector search finds semantically similar content, not just keyword matches.
Intelligent Document Processing
The demo includes sophisticated document handling:
- File upload — Support for
.txt,.md, and.csvfiles - Text chunking — Intelligent splitting with overlap for context preservation
- Background processing — Queue-based embedding generation
- Status tracking — Real-time progress monitoring
Documents become searchable knowledge bases automatically.
How It Works: The RAG Pipeline
The RAG pipeline transforms documents into conversational knowledge:
1. Document Upload and Chunking
When a file is uploaded, the system processes it in the background:
class ProcessKnowledgeFileJob implements ShouldQueue
{
public function handle(): void
{
$content = $this->extractText();
$chunks = $this->chunkText($content, 600, 80);
// Process chunks into embeddings...
}
}
The chunking strategy uses:
- 600-character chunks — Optimal size for embedding models
- 80-character overlap — Preserves context across boundaries
- Smart splitting — Maintains semantic coherence
This ensures each chunk contains meaningful context, not arbitrary fragments.
2. Embedding Generation
Each chunk is converted into a vector embedding:
$response = Embeddings::for($batch)->generate();
foreach ($batch as $i => $text) {
$embedding = $response->embeddings[$i] ?? null;
DocumentChunk::on('vector')->create([
'knowledge_file_id' => $knowledgeFile->id,
'content' => $text,
'embedding' => new Vector($embedding),
]);
}
Embeddings capture semantic meaning, enabling similarity search that understands context, not just keywords.
3. Query Processing
When a user asks a question, the system:
protected function getRagContext(string $query): string
{
$embeddingResponse = Embeddings::for([$query])->generate();
$queryEmbedding = $embeddingResponse->embeddings[0] ?? [];
$nearest = DocumentChunk::nearestTo($queryEmbedding, 5)->get();
$parts = $nearest->map(fn ($c) => $c->content)->all();
return implode("\n\n---\n\n", $parts);
}
This retrieves the five most semantically similar chunks from the knowledge base, providing relevant context for the AI agent.
4. Context-Aware Responses
The retrieved context is injected into the agent's instructions:
protected function buildInstructions(string $systemPrompt, string $context): string
{
$base = $systemPrompt ?: 'You are a helpful assistant.';
$contextBlock = "Use the following context from the knowledge base when relevant to answer the user. If the context does not contain relevant information, say so.\n\nContext:\n".$context;
return $base."\n\n".$contextBlock;
}
The agent uses this context to generate accurate, grounded responses that cite your actual content.
The Agent: Conversational Intelligence
The RAG chat agent combines multiple capabilities:
Memory and Context
class RagChatAgent implements Agent, Conversational, HasTools
{
use Promptable, RemembersConversations;
public function instructions(): Stringable|string
{
return $this->instructions;
}
}
The agent maintains conversation history, enabling multi-turn dialogues that build on previous exchanges.
Streaming Responses
Responses stream in real-time using Laravel AI SDK's streaming capabilities:
$stream = agent($instructions, [], [])
->stream($message, provider: $config->provider, model: $config->model);
return $stream->usingVercelDataProtocol();
Users see answers appear as they're generated, creating a responsive, engaging experience.
Configurable Behavior
The system prompt is configurable through an admin panel, allowing customization for different use cases:
- Domain-specific assistants — Tailored for specific knowledge bases
- Brand voice — Match your organization's communication style
- Response format — Structured outputs for different contexts
Each deployment can be customized without code changes.
Real-World Applications
The Laravel AI RAG Agent Demo enables diverse applications:
Customer Support
Transform support documentation into intelligent assistants that answer questions instantly, reducing ticket volume while improving response quality.
Internal Knowledge Bases
Make company documentation searchable and conversational. Employees find information faster through natural language queries instead of manual searching.
Product Documentation
Create interactive product assistants that understand specifications, features, and use cases. Customers get accurate answers without navigating complex documentation.
Educational Platforms
Build learning assistants that reference course materials, answer questions, and provide context-aware explanations based on actual content.
Legal and Compliance
Enable assistants that reference policies, regulations, and procedures, ensuring accurate information delivery while maintaining source citations.
Technical Excellence: Production-Ready Patterns
The demo showcases production-ready patterns:
Queue-Based Processing
File processing runs in background jobs, preventing request timeouts and enabling scalable document ingestion:
ProcessKnowledgeFileJob::dispatch($knowledgeFile);
Large files process asynchronously without blocking user interactions.
Error Handling
Comprehensive error handling provides user-friendly messages:
protected function userFacingErrorMessage(\Throwable $e): string
{
if (str_contains($message, 'API key')) {
return 'OpenAI API key is missing or invalid...';
}
if (str_contains($message, 'vector')) {
return 'Vector database is unavailable...';
}
return 'Chat is temporarily unavailable...';
}
Users get actionable feedback, not technical stack traces.
Status Tracking
Real-time status updates keep users informed:
- Pending — File uploaded, waiting for processing
- Processing — Embeddings being generated
- Completed — Ready for use in chat
- Failed — Error message displayed for debugging
Transparency builds trust and enables troubleshooting.
Multi-Database Architecture
The demo uses separate databases for application data and vectors:
protected $connection = 'vector'; // DocumentChunk uses vector DB
This separation enables:
- Independent scaling — Scale vector operations separately
- Performance optimization — Tune each database for its workload
- Flexibility — Use different PostgreSQL configurations
Building Your Own RAG Assistant
The Laravel AI RAG Agent Demo provides a complete foundation for building custom RAG applications. The open-source repository includes everything you need to get started.
Try it live: laravel-ai-rag-agent-demo.on-forge.com — Register, upload knowledge files, and chat with your own documents.
Getting Started with the Demo
Clone the repository:
git clone https://github.com/fakharkhan/laravel-ai-rag-agent-demo.git
cd laravel-ai-rag-agent-demo
Install dependencies:
composer install
npm install
npm run build
Configure your environment:
Copy .env.example to .env and configure:
- PostgreSQL database with pgvector extension
- OpenAI API key for embeddings and chat
- Vector database connection settings
Run migrations:
php artisan migrate
Start the queue worker (for background file processing):
php artisan queue:work
Launch the application:
php artisan serve
The demo includes a complete admin panel for managing knowledge files, configuring chat settings, and monitoring processing status. Upload your documents, configure the system prompt, and start chatting with your knowledge base immediately.
Exploring the Codebase
The repository structure demonstrates production-ready patterns:
app/Ai/Agents/— RAG chat agent implementationapp/Jobs/— Background processing for file embeddingsapp/Models/— Eloquent models for knowledge files and chunksapp/Http/Controllers/— Chat and admin controllersdatabase/migrations/— Database schema including vector tablesdocs/— Comprehensive setup and configuration guides
The codebase follows Laravel best practices and serves as both a working application and a learning resource for building RAG systems.
Customization and Extension
The demo is designed for easy customization:
- Modify chunking strategy — Adjust chunk size and overlap in
ProcessKnowledgeFileJob - Add file formats — Extend
extractText()to support additional file types - Customize agent behavior — Modify system prompts and agent instructions
- Extend vector search — Adjust similarity thresholds and result counts
- Add authentication — The demo includes Laravel Fortify for user management
The open-source nature means you can fork, modify, and deploy your own version tailored to your specific needs.
1. Setup Infrastructure
Install PostgreSQL with pgvector, configure Laravel AI SDK, and set up the vector database connection. The repository includes detailed setup instructions in docs/ai-rag-setup.md.
2. Upload Knowledge Files
The system handles file uploads, chunking, and embedding generation automatically. Upload your documents and they become searchable. The admin panel provides real-time status updates as files are processed.
3. Configure the Agent
Set your system prompt to define the agent's personality and behavior. Customize for your domain and use case. The demo includes example prompts in docs/chat-agent-system-prompt.md.
4. Start Chatting
Users can immediately query your knowledge base through natural language. The system retrieves relevant context and generates accurate responses with streaming support for real-time interactions.
5. Iterate and Improve
Monitor conversations, refine system prompts, and add more knowledge files as your content grows. The demo's admin interface makes it easy to manage your knowledge base over time.
The Business Value
RAG assistants deliver measurable business impact:
Reduced Support Costs
Automated answers to common questions reduce support ticket volume while maintaining response quality.
Faster Information Access
Employees find information in seconds instead of minutes, improving productivity across organizations.
Consistent Accuracy
AI assistants provide consistent answers based on your actual content, reducing errors from manual information retrieval.
Scalable Knowledge Management
As documentation grows, RAG assistants scale automatically. New documents become searchable without additional configuration.
Better User Experience
Natural language queries feel more intuitive than traditional search interfaces, improving user satisfaction.
The Future of Knowledge Assistants
RAG represents a fundamental shift in how we interact with information. Instead of searching through documents, we converse with knowledge bases. Instead of reading manuals, we ask questions and get answers.
The Laravel AI RAG Agent Demo demonstrates that building these systems doesn't require complex infrastructure or specialized expertise. Laravel AI SDK makes RAG accessible to any Laravel developer.
As organizations accumulate more documentation, RAG becomes essential for making that knowledge accessible. The open-source demo provides a production-ready foundation for building these systems today. Clone the repository, explore the code, and deploy your own intelligent knowledge assistant.
The project is actively maintained and welcomes contributions. Whether you're building a custom RAG system or learning how these technologies work together, the repository serves as both a practical tool and an educational resource.
Building the Next Generation of Knowledge Interfaces
The gap between having information and using it effectively has always been a challenge. RAG bridges that gap by making knowledge conversational, searchable, and accessible.
The Laravel AI RAG Agent Demo shows how to build these systems using familiar tools and patterns. Laravel AI SDK handles the AI complexity, pgvector provides efficient vector search, and Laravel's queue system enables scalable processing.
The result: intelligent assistants that understand your content, answer your questions, and scale with your needs.
Ready to build your own RAG assistant? Try the live demo or visit github.com/fakharkhan/laravel-ai-rag-agent-demo to clone the repository and deploy your own intelligent knowledge interface.
The future of knowledge management isn't better search. It's conversational intelligence.