Skip to main content

AquaGen AI Multi-Agent System

Complete Architecture & Build Plan​

Company: FluxGen  |  Product: AquaGen  |  Version: 1.0  |  Date: March 2026

1. Vision​

Build a production-grade, domain-native AI system embedded inside the AquaGen customer dashboard that:

  • Answers any water-related question a customer asks in natural language
  • Analyses data across all 12 dashboard modules by calling existing APIs
  • Generates reports, graphs, and forecasts autonomously
  • Runs complex background pipelines without blocking the user
  • Scales from a single smart agent today to a full multi-agent system without rewriting anything
North Star

A customer opens the AquaGen dashboard and gets instant, accurate, conversational answers about their water data — as if a water domain expert is sitting next to them 24/7.

2. The 12 Dashboard Modules​

These are the 12 existing AquaGen dashboard pages. Each maps to a specialist AI agent.

#ModulePage RouteAgent Group
1Dashboard (Overview)page-dashboardCore
2Alertspage-alertsCore
3Reportspage-reportsCore
4Water Flowpage-water-flowWater Operations
5Water Qualitypage-water-qualityWater Operations
6Water Balancepage-water-balanceWater Operations
7Water Stockpage-water-stockWater Operations
8Water Neutralitypage-water-neutralitySustainability
9Rainwaterpage-rainwaterSustainability
10Groundwaterpage-groundwaterSustainability
11Energypage-energySustainability
12UWI (Used Water Intelligence)page-uwiIntelligence

3. Agent Design​

The 12 modules are grouped into 4 agent groups for efficient orchestration. Each group has a lead specialist agent that handles all modules within it.

3.1 Agent Groups Overview​

3.2 Core Agent Group​

Page: page-dashboard

Responsibility: Provide a unified overview of the customer's entire water system. The first agent activated on any session — always has the broadest snapshot.

Answers questions like:

  • "Give me a summary of my water system today"
  • "What's the overall health of my site?"
  • "What needs my attention right now?"

APIs it calls:

  • GET /dashboard/summary — site-wide KPI snapshot
  • GET /dashboard/health-score — overall system health
  • GET /dashboard/alerts-count — active alert counts by severity

3.3 Water Operations Agent Group​

Page: page-water-flow

Responsibility: Monitor and analyse water flow rates, consumption patterns, zone comparisons, and spike detection.

Answers questions like:

  • "Why did my flow rate spike on the 14th?"
  • "Which zone has the highest flow right now?"
  • "Compare this month's flow to last quarter"

APIs it calls:

  • GET /water-flow/realtime — live flow readings by zone
  • GET /water-flow/summary — aggregated flow by period
  • GET /water-flow/anomalies — detected spikes and drops
  • GET /water-flow/zones — per-zone breakdown

3.4 Sustainability Agent Group​

Page: page-water-neutrality

Responsibility: Track progress towards water neutrality goals, offsetting, net water consumption, and ESG targets.

Answers questions like:

  • "How close are we to water neutrality?"
  • "What is our net water consumption this year?"
  • "What actions would help us reach neutrality faster?"

APIs it calls:

  • GET /water-neutrality/status — neutrality score and gap
  • GET /water-neutrality/offsets — offset activities and credits
  • GET /water-neutrality/targets — configured ESG goals

3.5 Intelligence Agent Group​

Page: page-uwi

Responsibility: Analyse and provide intelligence on used water — wastewater volumes, recycling rates, reuse efficiency, treatment status, and discharge compliance. Cross-references Water Flow, Water Balance, and Compliance modules to give a complete picture of water after use.

Answers questions like:

  • "How much used water did we generate this month?"
  • "What percentage of our used water is being recycled?"
  • "Are our wastewater discharge levels within compliance?"
  • "How can we improve our used water reuse rate?"
  • "What is the treatment efficiency of our used water system?"

APIs it calls:

  • GET /uwi/volume — used water generated by period and zone
  • GET /uwi/recycling — recycled and reused water volumes
  • GET /uwi/treatment — treatment plant efficiency and status
  • GET /uwi/discharge — discharge volumes and compliance status
  • GET /uwi/reuse-rate — percentage of used water recovered
  • Cross-references /water-balance/summary and /compliance/status
Cross-Module Agent

The UWI Agent cross-references Water Balance, Compliance, and Water Neutrality data to give a complete closed-loop view of water — from intake through use to discharge or reuse.

4. System Architecture​

4.1 High-Level Architecture​

4.2 Request Routing Logic​

4.3 Pre-fetch Strategy (Dashboard Load)​

When a customer opens the dashboard, all module snapshots are fetched simultaneously in the background before the first question is asked.

4.4 Cross-Agent Communication for Complex Questions​

5. Data & Context Management​

5.1 Shared Context Object​

Every agent reads from a shared context object stored in the Redis session. This is built from pre-fetched snapshots and updated incrementally as the conversation progresses.

interface CustomerContext {
  // Identity
  customerId: string;
  sessionId: string;
  siteId: string;

  // Pre-fetched snapshots (loaded on dashboard open)
  snapshots: {
    dashboard: DashboardSnapshot; // ~80 tokens
    alerts: AlertsSnapshot; // ~80 tokens
    waterFlow: WaterFlowSnapshot; // ~70 tokens
    waterQuality: WaterQualitySnapshot; // ~70 tokens
    waterBalance: WaterBalanceSnapshot; // ~60 tokens
    waterStock: WaterStockSnapshot; // ~60 tokens
    waterNeutrality: NeutralitySnapshot; // ~50 tokens
    rainwater: RainwaterSnapshot; // ~50 tokens
    groundwater: GroundwaterSnapshot; // ~50 tokens
    energy: EnergySnapshot; // ~50 tokens
    uwi: UWISnapshot; // ~60 tokens
  };

  // Conversation
  conversationHistory: Message[]; // Last 5 turns only
  fetchedAt: Date;
  totalTokensUsed: number;
}

5.2 Token Budget Per LLM Call​

ComponentTokens
System prompt + agent persona~300
Relevant snapshots (2–3 modules)~200
RAG chunks (if knowledge needed)~500
Targeted API summary (on demand)~400
Conversation history (last 3 turns)~300
User question~50
Total target< 2,000 tokens
Token Discipline

Never send raw data rows to the LLM. Your backend always pre-aggregates into summaries. The LLM reasons over summaries — your backend does the number crunching.

5.3 Summary API Contract​

Every agent-facing API must return analysis-ready summaries.

{
  "period": "last_30_days",
  "total_litres": 118420,
  "daily_avg": 3820,
  "peak": { "date": "2024-01-14", "value": 6200, "zone": "zone_3" },
  "trend": "up 12% vs previous month",
  "anomaly_count": 2,
  "zones": {
    "zone_1": { "avg": 1200, "trend": "stable" },
    "zone_3": { "avg": 980, "trend": "rising +18%" }
  }
}

5.4 Agent Output Contract​

Every agent returns the same standard structure so the Orchestrator can merge cleanly.

interface AgentResponse {
  agentId: string;
  module: string; // e.g. "water-flow"
  summary: string; // Plain English answer
  data: Record<string, unknown>; // Structured data used
  confidence: "high" | "medium" | "low";
  dataFreshness: "realtime" | "snapshot" | "cached";
  followupSuggestions: string[]; // 2-3 suggested next questions
  needsEscalation: boolean; // Flag for human support
  tokensUsed: number;
}

5.5 RAG Knowledge Base​

Store and embed the following as vector documents for semantic retrieval:

SourceUsed By
Water regulations (by region)Compliance reasoning
AquaGen product manualsTechnical troubleshooting
UWI scoring methodologyUWI Agent explanation
Historical support Q&AAll agents
Water quality standards (WHO, BIS)Water Quality Agent
Groundwater permit rulesGroundwater Agent
ESG / water neutrality frameworksNeutrality Agent

6. Tech Stack​

Existing stack — no replacement

The AquaGen frontend (React) and backend are already in production. The AI system adds a new Agent Gateway service alongside the existing backend — no rewriting, no migration.

ComponentTechnologyReason
Primary LLMClaude Sonnet 4.6 (claude-sonnet-4-6)Best tool use + reasoning for water-domain questions
Classifier LLMClaude Haiku 4.5 (claude-haiku-4-5-20251001)Fast, cheap intent routing — classifies every query
Agent FrameworkLangChain + LangGraphReAct loop, tool binding, state management
Embeddingstext-embedding-3-small (OpenAI)RAG vector search for regulations and product docs
Vector DBpgvector (existing Postgres) or PineconeCompliance / knowledge RAG
TracingLangSmithAgent trace, token usage, latency monitoring

7. Phased Build Plan​

Phase 1 — Foundation (Weeks 1–4)​

Goal: Working agent in dashboard answering real customer questions

  • Build Summary API adapter layer for all 12 modules
  • Build pre-fetch service — parallel snapshot loading on dashboard open
  • Build shared context object + Redis session store
  • Build Dashboard Agent + Alerts Agent (most common questions)
  • Build chat UI with SSE streaming
  • Intent classifier — route to correct module
  • Deploy to staging, test with real customer data
Phase 1 Outcome

Customers can ask dashboard overview and alert questions and get instant, accurate answers streamed in real time.

Phase 2 — Full Agent Pool (Weeks 5–10)​

Goal: All 12 modules live, cross-module questions handled

  • Water Flow Agent + Water Quality Agent + Water Balance Agent + Water Stock Agent
  • Water Neutrality Agent + Rainwater Agent + Groundwater Agent + Energy Agent
  • UWI Agent (cross-references all modules)
  • Orchestrator for multi-module question routing
  • Parallel execution — independent agents run simultaneously
  • Conversation memory — last 5 turns retained
  • Follow-up question suggestions after each response
Phase 2 Outcome

Full Q&A across all 12 modules. Cross-module questions answered in under 1.5 seconds.

Phase 3 — Reports & Background Jobs (Weeks 11–14)​

Goal: Autonomous report generation, proactive AI alerts

  • Reports Agent + Celery job queue
  • Full background pipeline: all agents → Report Agent → PDF/Excel output
  • Push notifications when reports are ready
  • Proactive suggestions based on data ("2 active leaks detected — want an analysis?")
  • Graph data generation from Trend + UWI agents
Phase 3 Outcome

Full autonomous report generation. Customers receive proactive AI-driven insights without asking.

Phase 4 — Fine-Tuning (Months 4–9)​

Goal: AquaGen-native model — faster, cheaper, proprietary

  • Collect conversation data from Phases 1–3 (with customer consent)
  • Build training dataset: water-domain Q&A pairs + module-specific examples
  • Fine-tune Llama 3.1 8B or Mistral 7B on AquaGen domain data
  • A/B test fine-tuned model vs Claude Sonnet on accuracy benchmarks
  • Gradually shift routine queries to fine-tuned model ("AquaGen Mini")
  • Keep Claude Sonnet for complex cross-module reasoning
Phase 4 Outcome

"AquaGen Mini" — FluxGen's own domain-tuned model. Lower cost per query, faster response, proprietary advantage.

Phase 5 — Intelligence Platform (Months 9–18)​

Goal: Predictive, proactive, fully autonomous water intelligence

  • Proactive anomaly detection — AI alerts before customer notices
  • Predictive maintenance scheduling
  • Automated compliance monitoring with early warning
  • Cross-customer benchmarking (anonymised)
  • Multi-tenant internal agent — FluxGen team monitors all customer sites via AI
  • FluxGen Water Intelligence API — expose as a product to water industry partners

8. Latency Targets​

ScenarioTargetMechanism
Simple question — answered from snapshot< 500msNo extra API call, stream immediately
Single module — needs one API call600–900msOne summary API + stream
Multi-module — parallel agents900ms–1.5sParallel execution + stream
Complex deep analysis1.5–2.5sDeep API call + extended reasoning
Report generation2–4 minutesBackground job, user not blocked

9. Observability​

Every agent call is fully traced:

    Trace: question_id = "q_8f3a2"
├── Question: "Why did our used water reuse rate drop last month?"
├── Intent classified: uwi + water-balance + compliance (312ms)
├── Snapshot cache hits: ✅ uwi, ✅ water-balance / ❌ water-flow (fetched)
├── Agents run: 3 (parallel)
│   ├── WaterFlowAgent: 620ms, 1,840 tokens
│   ├── WaterBalanceAgent: 410ms (from snapshot), 980 tokens
│   └── UWIAgent: 680ms, 2,100 tokens
├── Orchestrator merge: 180ms
├── Total latency: 1,090ms
├── Total tokens: 4,920 (input) / 640 (output)
└── User feedback: 👍

Tools: Langfuse (open source) for tracing. Alert on latency > 3s, tokens > 6,000, confidence = low, needsEscalation = true.

10. Security & Privacy​

ConcernHow It's Handled
Data isolationAll API calls authenticated with customer JWT — agents only access that customer's data
No raw data in LLMBackend always aggregates before sending to LLM
Conversation storageStored server-side in Redis, never in browser
RAG knowledge baseContains only non-PII regulatory and product docs
API key securityAll LLM calls go through your backend — keys never exposed to frontend
Cross-customer isolationAgent sessions are strictly scoped to customerId + sessionId

11. Future Vision — FluxGen Water Intelligence Platform​

Once the agent system is mature, it becomes a platform, not just a feature.

12. What to Build First​

Most Important First Step

Build the Summary API layer before anything else. Every agent, every optimisation, every future feature depends on your backend returning clean aggregated summaries — not raw data rows.

Week 1 Action Items:

  1. Define and build summary endpoints for all 12 modules (/module/summary)
  2. Build the pre-fetch service that calls them in parallel on dashboard load
  3. Wire up a basic chat UI with SSE streaming
  4. Build the Dashboard Agent and Alerts Agent with a focused system prompt
  5. Deploy to staging with one real customer's data

That delivers a working, impressive agent in two weeks — and every phase after is purely additive with zero rework.

Document maintained by FluxGen Engineering. Update this document as modules evolve and new agents are added.