Agent Architecture

AI System

Comprehensive guide to SHELTR's multi-agent chatbot system with MCP-powered workflow automation, public orchestrator, and admin control panel

Version 2.0.0•Updated September 22, 2025•MCP ENHANCED•WORKFLOW AUTOMATION

System Overview

SHELTR features an AI chatbot system with three integrated components powered by Model Context Protocol (MCP):

Public Landing Page Chatbot - Orchestrator-based system with MCP workflow automation
Super Admin Chatbot Control Panel - Configurable agents with MCP tool integration
MCP Workflow Engine - 10 specialized tools + 2 automated multi-step workflows

🚀 MCP Integration Highlights

Intelligent Actions

• Real-world action execution (donations, status updates)
• Automated workflows (shelter onboarding, emergency response)
• Smart data queries with natural language

Technical Features

• 10 specialized MCP tools for platform operations
• Role-based access control for secure tool usage
• Multi-step workflow automation with dependencies

Public Landing Page Chatbot

MCP-powered orchestrator system for public users

Agent Types (7 MCP-Enhanced Agents)

• Emergency - Crisis response with automated escalation workflow
• Participant Support - Real status updates, QR code generation
• Donor Relations - Live donation processing, receipt generation
• Public Information - Enhanced knowledge search and platform queries
• Public Support - Intelligent onboarding and guidance
• Shelter Operations - Real-time capacity updates, reporting
• Technical Support - System queries and account management

MCP-Enhanced Workflow

• Intent Classification + MCP Tool Detection
• Role-Based Routing + Permission Validation
• RAG Enhancement + Real-Time Data Access
• Response Generation + Action Execution

Super Admin Control Panel

MCP-integrated configurable agent system for internal use

Agent Types (5 MCP-Integrated Agents)

• General Assistant - All MCP tools based on user role
• SHELTR Support - Platform tools, shelter onboarding workflows
• Technical Expert - System queries, performance analysis
• Business Analyst - Analytics tools, revenue reporting
• Creative Writer - Knowledge search for content research

MCP-Enhanced Features

• Session Management + Workflow Execution History
• Agent Selection + Tool Access Based on Role
• Model Selection + MCP Tool Integration
• Real-time Configuration + Action Monitoring

🛠️ MCP Tools & Workflows

🔧MCP Tools (10 Available)

Specialized tools for platform operations

Shelter Management

create_shelter, update_shelter_capacity

Donation Processing

process_donation, generate_donation_receipt

Participant Support

update_participant_status, generate_participant_qr

Emergency Response

emergency_escalation

Analytics & Knowledge

generate_impact_report, query_platform_data, search_knowledge_base

🔄MCP Workflows (2 Active)

Multi-step automated processes

Shelter Onboarding

1. Create shelter profile
2. Send welcome email
3. Schedule training

Emergency Response

1. Escalate emergency
2. Notify authorities (if critical)
3. Create incident report

🎯 User Experience Enhancement

Before MCP

User: "I need help with housing"

Bot: "Here are some resources about housing assistance..."

After MCP

User: "I need help with housing"

Bot: "Let me check your status and available options..."

[Executes: update_participant_status, search_knowledge_base]

Bot: "Found 3 shelters with availability. Generated your QR code. Here are your next steps..."

🎯 Agent Responsibilities Matrix

Public-Facing Agents (Orchestrator)

Agent	Primary Users	Key Functions	Status
emergency	Crisis situations	Crisis intervention, safety resources	✅ Active
participant_support	Homeless individuals	Service booking, resource navigation	✅ Active
donor_relations	Donors	SmartFund™ explanation, impact tracking	✅ Active
public_information	General public	Platform education, SmartFund™ model	✅ Active
public_support	New users	Getting started, donation guidance	✅ Active
shelter_operations	Shelter admins	Participant management, reporting	✅ Active
technical_support	All users	Platform issues, account problems	✅ Active

Admin-Facing Agents (Control Panel)

Agent	Primary Use	Key Functions	Status
general	General assistance	Various tasks, Q&A	✅ Active
sheltr_support	Platform support	SHELTR-specific help	✅ Active
technical_expert	Development support	Technical guidance, architecture	✅ Active
business_analyst	Strategy support	Business insights, analytics	✅ Active
creative_writer	Content creation	Writing assistance, marketing	✅ Active

🔄 System Architecture Comparison

Aspect	Orchestrator Agents	Control Panel Agents
Configuration	Hardcoded in prompts.py	Configurable via UI
Purpose	Public user support	Super Admin tooling
Persistence	Session-based	Full conversation history
Model Selection	Fixed per agent	User-selectable
Knowledge Base	RAG-enhanced	Configurable per agent
Access	Public users	Super Admin only

System Integration

Firebase Storage Status

• Knowledge Base: ✅ 10+ documents loaded
• Storage Bucket: gs://sheltr-ai.firebasestorage.app
• Collections: knowledge_documents, knowledge_chunks
• Embeddings: 100+ embedding chunks for RAG

Technical Implementation

• Orchestrator: apps/api/services/chatbot/orchestrator.py
• Control Panel: apps/web/src/app/dashboard/chatbots/page.tsx
• Models: GPT-4o, GPT-4o Mini, Claude (configurable)
• RAG System: Real-time knowledge enhancement

🚀 Current Status: MCP-Enhanced Multi-Agent System

✅ Operational Systems

Public Orchestrator: 7 MCP-enhanced agents with workflow automation
Admin Control Panel: 5 agents with MCP tool integration
MCP Backend: 10 specialized tools + 2 automated workflows
Knowledge Base: 57+ documents with semantic search

🔄 In Progress

Frontend MCP Client: React integration for tool execution
Tool Implementations: Converting stubs to full functionality
Workflow UI: Visual workflow execution monitoring
Testing & Validation: End-to-end workflow testing

🔧 Technical Architecture

Orchestrator: apps/api/services/chatbot/orchestrator.py

Control Panel: apps/web/src/app/dashboard/chatbots/page.tsx

MCP Service: apps/api/services/mcp_service.py

MCP Router: apps/api/routers/mcp.py

Knowledge Base: Firebase Firestore with vector embeddings

Models: OpenAI GPT-4o/Mini, Anthropic Claude