Ask AI App Overview

Your intelligent workplace assistant — ask questions in plain English, get instant answers, and let AI agents take action across every app in your organization.

---

What Is Ask AI?

Ask AI is the central AI-powered assistant for the MangoApps Workforce platform. Instead of navigating between dozens of apps to find information or complete tasks, employees simply type (or speak) a natural language question and Ask AI routes it to the right specialized agent for an instant, accurate answer.

Behind the scenes, Ask AI uses a multi-stage intelligence pipeline: hybrid ML classification identifies what you need, 40+ domain-specific agents access the right data, and real-time WebSocket streaming delivers responses character-by-character so you never stare at a loading screen.

Core Value Proposition:

• 🤖 Natural Language Interface — Ask questions the way you’d ask a coworker, no menus or forms needed
• ⚡ Real-Time Streaming — Responses stream live via WebSocket, character by character
• 🎯 40+ Specialized Agents — Each domain (scheduling, HR, service desk, etc.) has its own trained expert
• 🎙️ Voice Mode — Hands-free conversations using speech-to-speech AI with configurable voices
• 🧠 Learns Over Time — Remembers your preferences and context across conversations

---

At a Glance

🤖 AI Agents	🎙️ Voice Modes	📱 Platforms	🔐 Access Levels
40+ specialized domain agents	13 voice options with configurable pace and style	Web, Mobile (iOS/Android), API	Employee, Manager, Admin

Perfect For:

• 👩‍💼 Employees — Check PTO balance, find passwords, view schedules, submit forms — all from one chat
• 👨‍💼 Managers — Get team reports, review performance data, check attendance, approve requests
• 🏢 HR Teams — Look up employee data, run headcount reports, check compliance, manage onboarding
• ⚙️ Admins — Configure agent behavior, set guidelines, monitor usage analytics, manage guardrails

---

How It Works

Request Processing Pipeline

┌───────────────────────────────────────────────────────────────────────────┐
│                     ASK AI PROCESSING PIPELINE                            │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌───────────┐    ┌──────────────────┐    ┌──────────────────────────┐   │
│  │  USER      │    │  HYBRID ML       │    │  DOMAIN AGENT            │   │
│  │  MESSAGE   │───▶│  CLASSIFIER      │───▶│  ROUTING                 │   │
│  │            │    │                  │    │                          │   │
│  │  "How many │    │  Pattern Match   │    │  40+ specialized agents  │   │
│  │   PTO days │    │  → KNN Prototype │    │  each with domain-       │   │
│  │   left?"   │    │  → LLM Fallback  │    │  specific tools          │   │
│  └───────────┘    └──────────────────┘    └──────────┬───────────────┘   │
│                                                       │                   │
│                    ┌──────────────────┐               ▼                   │
│                    │  WEBSOCKET       │    ┌──────────────────────────┐   │
│                    │  STREAMING       │◀───│  LLM RESPONSE            │   │
│                    │                  │    │  GENERATION              │   │
│                    │  Character-by-   │    │                          │   │
│                    │  character to    │    │  RAG + Knowledge Base    │   │
│                    │  browser/mobile  │    │  + API data + DB queries │   │
│                    └──────────────────┘    └──────────────────────────┘   │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

Conversation Architecture

┌───────────────────────────────────────────────────────────────────────────┐
│                    CROSS-CLIENT CONVERSATION SYNC                         │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌────────────┐         ┌────────────────────┐        ┌──────────────┐  │
│  │  WEB       │         │  AI CONVERSATION    │        │  MOBILE      │  │
│  │  CLIENT    │────────▶│  (Single Active)    │◀───────│  CLIENT      │  │
│  │            │         │                    │        │              │  │
│  │  Desktop   │         │  • Session ID sync │        │  iOS/Android │  │
│  │  Sidebar   │         │  • JSONB messages  │        │  Native App  │  │
│  │  Chat      │         │  • Cross-client    │        │  WebView     │  │
│  └────────────┘         └────────────────────┘        └──────────────┘  │
│         │                        │                           │           │
│         │                        ▼                           │           │
│         │               ┌────────────────────┐              │           │
│         └──────────────▶│  ACTION CABLE       │◀─────────────┘           │
│                         │  (WebSocket)        │                          │
│                         │  Real-time stream   │                          │
│                         └────────────────────┘                          │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

---

✨ Key Features

1. Natural Language Chat Interface

The primary interaction with Ask AI is through a conversational chat interface accessible from anywhere in the platform.

What You Can Do:

• Type questions in plain English (or any supported language)
• View streaming responses in real time as the AI thinks and generates answers
• Browse conversation history and continue where you left off
• Clear conversations or reset all memory including learned preferences
• Use the /help command to discover what Ask AI can do
• Use @mention to direct questions to a specific agent (e.g., @scheduling show my shifts)

How It Works:

• Messages are sent to the streaming endpoint, which enqueues an AskAiStreamingJob
• The job classifies intent using a hybrid ML router (Pattern Match → KNN → LLM disambiguation)
• Results stream back via ActionCable WebSocket connection, character by character
• Conversations automatically sync between web and mobile — start on desktop, continue on your phone

Role Access: All users

---

2. Specialized AI Agents

Ask AI routes questions to 40+ specialized domain agents, each trained to handle a specific area of the platform. Agents have access to domain-specific tools, APIs, and database queries to provide accurate, actionable answers.

Available Agent Domains Include:

• Scheduling — View shifts, request time off, check availability
• Timekeeping — Clock in/out status, timesheet queries, overtime tracking
• Leave Management — PTO balance, leave requests, approval status
• Service Desk — Create tickets, check ticket status, IT support
• Password Manager — Search and retrieve stored credentials
• Tasks — View assigned tasks, update status, create new tasks
• Performance Management (EPMS) — Review cycles, goals, performance data
• Recruiting — Job postings, candidate pipeline, interview schedules
• Employee Data — Profile info, directory lookups, team structure
• Compensation — Salary data, pay structure, compensation history
• Custom Reporting — Generate on-demand reports with charts and tables
• Training — Course enrollment, completions, certification status
• Onboarding / Offboarding — Checklist progress, pending tasks
• Forms — Submit forms, check form status, form assignments
• Surveys — Survey participation, results summaries
• OKR Hub — Objectives and key results tracking
• Benefits — Benefits enrollment, plan details
• Policy Hub / SOP Hub — Company policy lookups, standard procedures
• Safety Hub — Safety protocols, incident reporting
• Attendance — Attendance records, absence tracking
• Skills & Certifications — Skill profiles, certification expiry
• Succession Planning — Talent pools, readiness assessments
• Company Store — Points balance, item catalog, redemption
• Recognition — Give/receive recognition, points summary
• Asset Pro — Asset assignments, asset requests
• Bookings — Room reservations, resource booking
• Contracts — Contract status, renewal dates
• Procurement — Purchase requests, vendor info
• E-Signature — Signature requests, document status
• Inspections — Inspection schedules, findings
• Guest Pass — Visitor management, pass status
• Payroll — Pay stub info, payroll queries
• Headcount Planner — Headcount tracking, position management
• Job Board — Internal job postings, applications
• Offer Manager — Offer status, offer details
• Competitive Intelligence (Mango IQ) — Market analysis, competitor tracking
• Admin Help — Platform help articles, how-to guidance

How Agent Routing Works:

1. The Hybrid ML Router classifies your question’s intent with high confidence (~10ms)
2. The AgentRegistry checks which agents are enabled for your business
3. The best-matching agent is instantiated with your user/business context
4. The agent uses its domain-specific tools to fetch data and generate a response

Role Access: Varies by agent — employees see their own data, managers see team data, admins see business-wide data

---

3. Voice Mode (Speech-to-Speech)

Ask AI supports hands-free voice conversations using OpenAI’s Realtime API with WebRTC. Speak your question and hear the AI respond in a natural, configurable voice.

What You Can Do:

• Start a voice conversation with one tap/click
• Speak naturally — the AI understands context and follow-up questions
• Choose from 13 different AI voice personalities (Marin, Cedar, Alloy, Ash, and more)
• Configure speech pace (normal, slow, fast) and response verbosity
• Use voice mode on both web and mobile

Usage Limits & Billing:

• Per-session limit: 15 minutes
• Per-user daily limit: 30 minutes (configurable by admin)
• Usage tracked via VoiceUsage model with per-minute billing
• Admins can view monthly usage stats (sessions, minutes, cost)

How It Works:

• Client requests an ephemeral token from the server for WebRTC connection
• Server validates rate limits, billing balance, and voice mode enablement
• Audio streams directly between the client and OpenAI’s Realtime API
• Session duration and cost are tracked in real time via ActionCable

Role Access: All users (when enabled by admin)

---

4. Context-Aware Conversations

Ask AI maintains conversation context across messages, enabling natural follow-up questions and references.

What You Can Do:

• Ask follow-up questions like “What about last week?” or “Show me more details”
• Use short confirmations (“Yes”, “Go ahead”, “The first one”) and Ask AI understands what you mean
• Reference previous results (“those above”, “the first three”)
• Switch topics mid-conversation — Ask AI re-routes to the appropriate agent

How It Works:

• Conversation history is loaded from the database before each response
• Context-dependent messages (confirmations, pronouns, short replies) bypass ML classification
• The ContextAwareRouter module detects reference words and low-confidence classifications
• The Master Service preserves conversation state for multi-turn interactions

Role Access: All users

---

5. Conversation Memory & Learned Facts

Ask AI extracts and remembers key facts from your conversations, building a personalized knowledge base over time.

What It Remembers:

• Preferences — “I prefer detailed reports” or “Always show me this week’s schedule”
• Information — Key facts about your role, team, or projects mentioned in conversation
• Goals — Stated objectives and priorities
• Patterns — Recurring question types and preferred response formats

Memory Management:

• Facts are stored with confidence scores and automatically age out
• High-confidence facts (80%+) are used to personalize responses
• Users can clear conversation history only, or clear everything including learned facts
• Three clear levels: messages only, messages + cache, and full reset (messages + facts + cache)

Role Access: All users (each user’s memory is private)

---

6. Agentic Tool Execution with Confirmation

Ask AI agents can take real actions on your behalf — not just answer questions. For sensitive operations, the system requests confirmation before proceeding.

What Agents Can Do:

• Create support tickets in Service Desk
• Update passwords in Password Manager
• Submit forms and create tasks
• Modify schedule entries and request time off
• Generate and export reports

Safety Guardrails:

• High-impact operations (update, delete) require explicit user confirmation
• Confirmation requests are streamed via WebSocket with approve/reject buttons
• Confirmations expire after a configurable timeout
• All tool executions are logged with full audit trail

How It Works:

• Agent determines a tool call is needed based on your request
• For read operations, the tool executes immediately
• For write/update/delete operations, a confirmation dialog is sent to the frontend
• User approves or rejects; the agent proceeds or cancels accordingly

Role Access: Varies by tool — employees can modify their own data, managers can act on team data

---

7. Admin Dashboard & Analytics

The Ask AI dashboard gives administrators visibility into AI usage, active agents, and conversation activity across the organization.

Dashboard Metrics:

• Total conversations and message volume
• Messages today and active users
• Average response time
• Active vs. disabled vs. available agents

Recent Activity Table:

• User name, first message, message count
• Conversation start time and last activity
• Status badges (active, completed)
• Voice message indicators

Role Access: Admin only

---

8. Agent Guidelines (Admin)

Administrators can customize how AI agents behave across the organization through the Agent Guidelines system.

What You Can Configure:

• Business Context — Tell the AI about your organization’s culture and priorities
• Custom Instructions — Add specific behavioral rules for all agents
• Tone & Style — Choose preset tones or write custom tone instructions
• Response Format — Control how verbose or concise responses should be
• Greeting / Apology / Escalation Messages — Customize standard responses
• Universal Guardrails — Rules all agents must follow (e.g., “Never share salary data with non-managers”)
• Action Guardrails — Rules for when agents take actions (e.g., “Always confirm before creating tickets”)
• Per-Agent Overrides — Customize tone, instructions, and guardrails for individual agents
• AI-Powered Optimization — Use the “Optimize” button to refine your instructions with AI

Draft & Publish Workflow:

• Changes are saved as a draft first
• Publishing makes guidelines active for all agents immediately
• Published-by and published-at timestamps are tracked
• Cache is automatically busted across all agents on publish

Role Access: Admin only

---

9. Configuration & Feature Controls

Administrators control Ask AI behavior through a comprehensive configuration panel.

AI Configuration:

• Response temperature slider (0.0 conservative to 1.0 creative)
• Default model selection (GPT-4o-mini)

Feature Access Controls:

• Enable/disable general questions
• Enable/disable schedule queries
• Enable/disable employee data access (with security warning)
• Enable/disable function calls (agentic actions)

Usage Limits:

• Daily request limit per user (0–500, configurable)
• Maximum conversation length (10–100 messages)

Privacy & Data Management:

• Conversation retention period (0–365 days, 0 = forever)
• Enable/disable conversation export

Voice Mode Settings:

• Enable/disable voice mode
• Voice daily limit per user (0–120 minutes)
• AI voice selection (13 options with live preview)
• Response style (concise, balanced, detailed)
• Speech pace (normal, slow, fast)

Integration Settings:

• Knowledge base access toggle
• Citations toggle
• Notification actions toggle

Role Access: Admin only

---

10. Test Suite

Managers and admins can verify AI agent behavior using a built-in test suite that exercises example questions across all enabled agents.

What You Can Do:

• Run individual test questions against specific agents
• See response time, intent classification, and agent routing details
• View thinking steps, tools used, and context metadata
• Identify failures with detailed error reasons
• Validate that agents respond correctly after configuration changes

How It Works:

• Each test creates a fresh AskAiMasterService instance with a test-specific thread
• Questions are processed through the full pipeline (classification → routing → response)
• Results include success/failure determination based on both explicit flags and response content analysis
• Error detection checks for phrases like “unable to”, “error generating”, “technical difficulties”

Role Access: Manager and Admin

---

11. Flow Logging & Observability (System Admin)

System administrators have deep observability into every Ask AI request through the Flow Log system.

Flow Log Dashboard:

• 24-hour stats: total requests, success/fail ratio, average latency
• Counts by service type: API Intelligence, Schema Intelligence, KB Search, LLM calls
• Classification review queue with flagged items
• Top intents and handlers breakdown

Per-Request Trace Detail:

• Full processing pipeline: Stage 1 classification → Stage 2 sub-intent → Handler → Response
• ML classification details: intent, confidence, method (pattern/KNN/LLM)
• API/Schema Intelligence: matched endpoints, SQL queries executed, response data
• KB Search: articles found, search type, relevance scores
• LLM calls: linked API logs, token usage, latency breakdown
• Tool calls: tool name, arguments, execution time, success/failure
• Event timeline: chronological trace of every processing step

Analytics Dashboard:

• Intent breakdown over configurable timeframes (day/week/month)
• Handler and response type distribution
• Slow request analysis (configurable threshold)
• Hourly volume charts

Classification Review:

• Auto-flagged suspicious classifications (low confidence, KNN/LLM disagreement)
• Admin feedback with correct intent annotation
• Export corrections as ML training data for model improvement

Role Access: System Admin only

---

12. Mobile Experience

Ask AI is available on mobile through both the native app and mobile web views, with full conversation sync between devices.

Mobile Features:

• Agent Discovery — Browse all available AI agents and their capabilities
• Help Examples — See example questions organized by agent domain
• Conversation History — Review past interactions in a read-only view
• Voice Mode — Full voice conversation support with session tracking
• Cross-Client Sync — Start a conversation on mobile, continue on desktop (and vice versa)

API Endpoints for Native Mobile:

• POST /api/v1/ask_ai/messages — Send message and get WebSocket subscription info
• GET /api/v1/ask_ai/conversations/:id/messages — Paginated message history
• GET /api/v1/ask_ai/help — Agent discovery with example questions
• GET /api/v1/ask_ai/settings — Feature toggles for mobile UI control
• POST /api/v1/ask_ai/voice_token — Ephemeral token for voice mode
• POST /api/v1/ask_ai/cancel — Cancel in-progress requests

Role Access: All users

---

🎯 Common Use Cases

For Employees

Question	What Happens
“How many PTO days do I have left?”	Leave Management Agent checks your balance
“Show me my schedule for next week”	Scheduling Agent queries your upcoming shifts
“Find my Slack password”	Password Agent searches your credential vault
“My laptop is overheating”	Service Desk Agent offers to create an IT ticket
“What is the dress code policy?”	Policy Hub Agent searches company policies
“Submit my expense report form”	Forms Agent helps you fill and submit

For Managers

Question	What Happens
“Show me attendance for my team this week”	Attendance Agent pulls team attendance data
“How many open positions do we have?”	Recruiting Agent queries job listings
“Generate a headcount report by department”	Reporting Agent creates an interactive HTML report
“Who on my team has expiring certifications?”	Skills Agent checks certification dates

For HR & Admins

Question	What Happens
“Show employee count by department”	Reporting Agent generates a grouped report
“What is the turnover rate this quarter?”	Database Agent runs analytics queries
“List all pending onboarding tasks”	Onboarding Agent checks task completion
“Who are the succession candidates for VP role?”	Succession Agent queries talent pools

---

⚙️ Admin Setup Guide

Step 1: Enable the App

1. Navigate to Apps in the main menu
2. Find Ask AI in the marketplace
3. Click Enable for your business

Step 2: Configure AI Settings

1. Go to Ask AI → Settings (admin only)
2. Set the response temperature (0.7 recommended for balanced responses)
3. Enable/disable feature access controls based on your data policy
4. Configure usage limits appropriate for your organization size
5. Set conversation retention period per your data retention policy

Step 3: Configure Voice Mode (Optional)

1. In Settings, scroll to Voice Mode
2. Enable voice mode for your organization
3. Select an AI voice personality (Marin recommended for professional settings)
4. Set daily usage limits per user
5. Choose response style and speech pace

Step 4: Set Agent Guidelines (Optional)

1. Go to Ask AI → Agent Guidelines (admin only)
2. Add your business context (industry, culture, priorities)
3. Write any custom instructions or guardrails
4. Configure per-agent overrides if needed
5. Use the Optimize button to refine instructions with AI assistance
6. Save as draft, then Publish when ready

Step 5: Review Agent Status

1. Go to Ask AI → Dashboard
2. Review which agents are Active, Disabled, or Not Installed
3. Install additional marketplace apps to unlock more AI agents
4. Enable/disable individual agents in each app’s configuration

---

🔒 Security & Privacy

Business Scoping

All queries are strictly scoped to the current user’s business context. Users can only access data they have permission to see based on their role.

Conversation Ownership

Conversations are verified for ownership at both the HTTP and WebSocket layers. The ActionCable channel validates user ID, business ID, and conversation ownership before allowing subscriptions.

Voice Session Security

Voice sessions use ephemeral tokens with 15-minute expiration. Session data is cached with user/business validation to prevent cross-session access.

Data Retention

Administrators control how long conversations are retained. Conversations older than the configured retention period are automatically cleaned up.

Audit Trail

Every AI request is logged with full trace data including classification, routing, tool calls, and response metadata through the Flow Log system.

---

📊 Monitoring & Troubleshooting

For Admins

Check AI Availability:

• Verify the AI service status on the Dashboard (response time metric)
• If responses are slow, check the Flow Log analytics for latency trends

Review Agent Performance:

• Use the Test Suite to verify agents respond correctly
• Check the Flow Log for failed requests and error patterns

Monitor Usage:

• Dashboard shows total conversations, active users, and daily message volume
• Voice mode usage tracked per-user and per-business with billing details

Common Issues

Issue	Solution
“AI service is not configured”	Verify OpenAI API key is set in system settings
Agent not responding correctly	Check agent guidelines, run Test Suite
Voice mode not available	Ensure voice mode is enabled in Settings
Responses are too slow	Check Flow Log analytics for latency bottlenecks
Conversation not syncing	Conversations auto-sync; try refreshing the page

---

🔗 Integration Points

Ask AI integrates with virtually every app in the MangoApps Workforce platform:

• Marketplace Apps — Each enabled app can provide an AI agent to Ask AI
• Knowledge Base — RAG-powered answers from help articles and documentation
• Service Desk — Automatic ticket creation for unresolved issues
• ActionCable — Real-time WebSocket streaming for live responses
• Mobile API — Full REST API for native mobile app integration
• Voice (OpenAI Realtime) — WebRTC speech-to-speech via ephemeral tokens

---

💡 Tips & Best Practices

1. Be specific — “Show my shifts for next week” works better than “What’s my schedule?”
2. Use @mentions — Direct questions to specific agents with @scheduling, @passwords, etc.
3. Try voice mode — Great for quick lookups when your hands are busy
4. Clear conversations when switching topics for cleaner context
5. Use the /help command to discover what each agent can do with example questions
6. Admins: Start with conservative settings and tune based on usage analytics
7. Admins: Review the Classification Review queue weekly to improve ML accuracy over time