Quick Tour

Let's walk through three real scenarios to see how CitadelMesh works in practice. This will give you a feel for the system in about 10 minutes.

Scenario 1: Security Breach Response

The Situation

3:00 PM, Thursday - Building is fully occupied, peak electricity rates ($0.18/kWh)

Avigilon camera detects forced entry at door-server-room:

• Person not recognized by facial analytics
• Door sensor shows forced entry (no badge scan)
• High-value equipment area (servers, network gear)

What Happens (in 2 seconds)

1. Event Detection

{
  "event_type": "security_breach",
  "alert_level": "high",
  "source": "avigilon-camera-12",
  "location": "server-room",
  "detected": "unauthorized_person",
  "confidence": 0.95
}

2. Security Agent Analyzes

🛡️ Security Agent State Machine:

MONITOR → ANALYZE → DECIDE → ACT

Analysis:
  ✅ Unauthorized person: YES
  ✅ Forced entry: YES
  ✅ High-value area: YES
  ✅ Business hours: YES
  → Threat Score: 85/100 (HIGH)

Decision:
  → Lock perimeter doors
  → Activate all cameras in zone
  → Track intruder movement
  → Alert security team (high priority)

3. Policy Check (OPA)

# Security agent requests action
allow {
  input.action == "lock_doors"
  input.agent_id == "security-agent"
  input.threat_level == "high"

  # Verify safety
  no_emergency_exits_blocked(input.doors)
  authorized_agent(input.agent_id)
}

→ ✅ ALLOWED

4. Energy Agent Coordinates

⚡ Energy Agent:

Receives coordination event from Orchestrator:
  "Security incident in progress"

Analysis:
  - Security has priority
  - Suspend energy optimization in affected zones
  - Maintain critical systems (cameras, access control)
  - Reduce HVAC in non-security zones

Actions:
  → Defer demand response (if scheduled)
  → Reduce HVAC in unaffected areas
  → Ensure security cameras have full power

5. Orchestrator Coordinates

🎯 Building Orchestrator:

Priority Hierarchy:
  1. Life Safety: 100
  2. Security: 80    ← ACTIVE
  3. Comfort: 50
  4. Cost: 30

Decision:
  → Security takes priority
  → Energy supports security response
  → Cost optimization suspended

Coordination Score: 100%

The Result

Timeline:

• T+0.2s: Security breach detected (Avigilon)
• T+0.5s: Security Agent threat analysis complete
• T+0.8s: OPA policy validated
• T+1.2s: Doors locked, cameras activated
• T+1.5s: Energy Agent coordinated response
• T+2.0s: Security team alerted

Actions Taken:

• ✅ 4 perimeter doors locked
• ✅ 12 cameras activated in zone
• ✅ Intruder tracked across camera network
• ✅ Security team dispatched
• ✅ HVAC reduced in non-critical zones
• ✅ $2.40 additional energy cost (acceptable for security)

Outcome:

• 🔐 Building secured in 2 seconds
• 👮 Security team on-site in 8 minutes
• ⚡ Energy efficiency maintained where safe
• 📝 Complete audit trail logged

---

Scenario 2: Fire Alarm Emergency

The Situation

2:30 PM, Friday - 150 people in building (Avigilon occupancy count)

Fire alarm triggered in Building A, Level 2:

• Smoke detector activated
• Temperature rising
• LIFE SAFETY EVENT (highest priority)

What Happens (immediately)

1. Emergency Event

{
  "event_type": "fire_alarm",
  "alert_level": "EMERGENCY",
  "source": "fire-safety-system",
  "location": "building-a-level-2",
  "smoke_detected": true,
  "temperature": "85°F",
  "occupancy": 150
}

2. Orchestrator Takes Control

🎯 Building Orchestrator:

Priority: LIFE SAFETY (100) - OVERRIDES EVERYTHING

Coordinated Emergency Protocol Activated:
  ✅ All other policies SUSPENDED
  ✅ Emergency evacuation policy ACTIVE
  ✅ All agents coordinated for life safety

3. Security Agent - Evacuation Mode

🛡️ Security Agent:

Emergency Actions (NO DELAY):
  ✅ UNLOCK all emergency exits (12 doors)
  ✅ DISABLE access control (allow free egress)
  ✅ Activate emergency lighting (full brightness)
  ✅ Alert: Fire department, building management, security

Policy Override: EMERGENCY - All safety locks released

4. Energy Agent - Emergency HVAC

⚡ Energy Agent:

Emergency HVAC Protocol:
  ✅ Switch to SMOKE EVACUATION mode
  ✅ Shutdown supply air (don't spread smoke)
  ✅ Activate exhaust fans (remove smoke)
  ✅ Open fresh air dampers
  ✅ Emergency power mode (critical systems only)
  ✅ Elevator recall to fire service mode

The Result

Timeline:

• T+0s: Fire alarm triggered
• T+0.5s: Orchestrator activates emergency protocol
• T+1.0s: All exits unlocked
• T+1.5s: HVAC smoke evacuation active
• T+2.0s: Emergency services notified
• T+3.0s: Full evacuation protocol executing

System Response:

{
  "evacuation_status": {
    "exits_unlocked": 12,
    "access_control": "disabled",
    "emergency_lighting": "full_brightness",
    "occupants": 150,
    "evacuation_routes": "clear"
  },
  "hvac_status": {
    "mode": "smoke_evacuation",
    "supply_air": "shutdown",
    "exhaust": "active",
    "fresh_air_dampers": "open"
  },
  "emergency_response": {
    "fire_department": "notified",
    "ambulance": "dispatched",
    "building_management": "on-site"
  },
  "estimated_evacuation_time": "3-5 minutes"
}

Outcome:

• 🚨 Safe evacuation enabled in 2 seconds
• 🚪 All exits accessible (no blocked routes)
• 💨 Smoke controlled (not spread through HVAC)
• 👥 150 people can evacuate safely
• 🚒 Emergency services coordinated

---

Scenario 3: Smart Energy Optimization

The Situation

4:00 PM, Tuesday - Peak electricity period

Utility sends demand response request:

• Reduce 50 kW for 2 hours
• Incentive: $0.30/kWh ($30 for participation)
• Current: Building fully occupied, security monitoring active

What Happens

1. Demand Response Event

{
  "event_type": "utility_demand_response",
  "alert_level": "low",
  "source": "utility-grid",
  "reduction_target_kw": 50,
  "duration_hours": 2,
  "incentive_per_kwh": 0.30,
  "total_incentive": "$30.00"
}

2. Energy Agent Optimization

⚡ Energy Agent:

Mathematical Optimization (scipy):
  Minimize: energy_cost + discomfort_penalty
  Subject to:
    - Reduce 50 kW
    - Temperature: 68°F - 76°F
    - Occupancy comfort maintained
    - Security systems excluded

Optimal Actions:
  → Increase HVAC setpoints +4°F (aggressive)
  → Dim non-critical lighting 30%
  → Shutdown HVAC in unoccupied zones
  → Predicted: 52 kW reduction

3. Security Agent - Set Constraints

🛡️ Security Agent:

Constraints for Energy Agent:
  ❌ DO NOT reduce camera power
  ❌ DO NOT reduce security lighting below minimum
  ✅ MAINTAIN all monitoring
  ✅ VERIFY lighting adequate for cameras

4. Orchestrator - Conflict Check

🎯 Building Orchestrator:

Conflict Analysis:
  Energy wants: "Dim all lighting 30%"
  Security needs: "Maintain camera lighting"

Priority:
  Grid Stability: 30
  Security: 80

Resolution:
  → Energy can dim non-security lighting
  → Security camera zones maintain brightness
  → Both goals achieved

5. Policy Validation

# Energy agent action
allow {
  input.action == "demand_response_participation"
  input.reduction_kw <= 100  # Max allowed
  input.temperature_min >= 60
  input.temperature_max <= 85
  no_security_degradation(input.affected_systems)
}

→ ✅ ALLOWED

The Result

Execution:

{
  "energy_impact": {
    "target_reduction_kw": 50,
    "achieved_reduction_kw": 52,
    "achievement_percent": 104,
    "duration_hours": 2,
    "incentive_earned": "$31.20"
  },
  "security_impact": {
    "monitoring_effectiveness": "100%",
    "cameras_operational": 12,
    "lighting_adequate": true,
    "no_degradation": true
  },
  "comfort_impact": {
    "temperature_increase": "+4°F",
    "still_within_comfort_range": true,
    "occupant_complaints": 0
  }
}

Outcome:

• ⚡ $31.20 revenue earned (104% of target)
• 🔐 100% security monitoring maintained
• 😊 Comfort maintained within acceptable range
• 🤝 Perfect coordination (energy + security)
• 🌱 Grid stability supported

---

What You Just Learned

1. Multi-Agent Coordination

• Security, Energy, and Orchestrator agents work together
• Each agent has specialized expertise
• Coordination happens automatically

2. Safety-First Decision Making

• Every action validated by OPA policies
• Emergency scenarios override everything
• Fail-safe defaults protect people and property

3. Intelligent Conflict Resolution

• Priority hierarchy resolves conflicts
• Life Safety > Security > Comfort > Cost
• Both goals achieved when possible

4. Real-Time Performance

• Security responses: Under 2 seconds
• Fire alarm coordination: Immediate
• Energy optimization: Continuous
• All actions logged and auditable

---

What's Next?

• Want to understand the architecture? → Architecture Overview
• Want to learn how it was built? → The Chronicles
• Ready to build agents? → Agent Development Guide
• Want to get started? → Getting Started Guide

---

You've completed the Quick Tour! You now understand how CitadelMesh coordinates agents to make buildings intelligent, safe, and efficient. 🎉