InfraAlert

AI-powered multi-agent system for infrastructure issue reporting and response coordination in Nigeria.

Overview

InfraAlert uses advanced AI to transform citizen reports into coordinated responses. The system:

• Receives reports through multiple channels (web, mobile, voice)
• Analyzes using Vision API, Speech-to-Text, NLP, and Gemini AI
• Detects infrastructure issues with machine learning
• Prioritizes based on severity, urgency, and impact
• Coordinates real-time resource matching and dispatch
• Sends notifications via Africa's Talking SMS (cost-effective Nigerian coverage)

Live Services

All services are deployed on Google Cloud Run:

Service	URL	Purpose
Web Application	https://infraalert-webapp-wuqtulo2va-uc.a.run.app	Citizen-facing report submission and tracking
Report Webhook	https://report-webhook-wuqtulo2va-uc.a.run.app	Cloud Function for report intake
Orchestrator Agent	https://orchestrator-agent-wuqtulo2va-uc.a.run.app	Workflow coordinator
Issue Detection Agent	https://issue-detection-agent-wuqtulo2va-uc.a.run.app	Issue analysis and classification
Priority Analysis Agent	https://priority-analysis-agent-wuqtulo2va-uc.a.run.app	Priority scoring
Resource Coordination Agent	https://resource-coordination-agent-wuqtulo2va-uc.a.run.app	Team and equipment matching
Platform Integration Agent	https://platform-integration-agent-wuqtulo2va-uc.a.run.app	External integrations and notifications
MCP Server	https://mcp-server-wuqtulo2va-uc.a.run.app	Model Context Protocol tools

Architecture

The system consists of specialized agents:

• Orchestrator Agent: Central workflow coordinator that orchestrates the complete infrastructure issue workflow
• Issue Detection Agent: Analyzes and classifies infrastructure issues using Vision API, NLP, Speech-to-Text, and Gemini AI
• Priority Analysis Agent: Evaluates severity and urgency to determine priority scores
• Resource Coordination Agent: Matches and dispatches resources based on issue type and location
• Platform Integration Agent: Executes platform actions including notifications and external integrations
• MCP Server: Provides external system integration tools (SMS, ticketing, dashboard updates)

ADK Multi-Agent Implementation

InfraAlert supports two orchestration modes using Google ADK:

In-Process Workflow (default for local dev, adk web, Agent Engine):

• Uses ADK's native SequentialAgent to orchestrate sub-agents in a single process
• Agents share session state directly via SessionKeys (zero-copy)
• Pipeline: Detection -> Priority -> Coordination -> Platform Integration (with MCP tools)

HTTP Microservices (production Cloud Run, set USE_HTTP_ORCHESTRATOR=true):

• Each agent is a separate Cloud Run service exposing ADK root_agent from agent.py
• Orchestrator coordinates via HTTP calls to each agent's /task endpoint
• Session IDs propagate via X-ADK-Session-Id headers for distributed tracing

Key patterns:

• MCP Protocol: The MCP server uses FastMCP (proper MCP SDK), and the Platform Integration agent connects via MCPToolset for native tool access
• A2A Protocol: All agents expose /.well-known/agent.json for discovery and POST /tasks/send for standardized task submission
• Agent Instructions: Each agent has a detailed instruction prompt for Gemini reasoning
• Workflow Agents: SequentialAgent, ParallelAgent, and LoopAgent patterns available for composing workflows

Prerequisites

• Python 3.12+ (3.11+ also supported)
• uv package manager (install)
• gcloud CLI (Google Cloud SDK) - install
• Docker Desktop (for local development)
• Google Cloud Account (for deployment)

Install uv

Recommended: Use the setup script (ensures persistence)

# Run the setup script (installs and configures PATH)
./scripts/setup-uv.sh

Manual installation:

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip (less recommended)
pip install uv

Ensure persistence:

After installation, uv should be automatically added to your PATH. If not available in new terminals:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/.cargo/bin:$PATH"

# Then reload your shell
source ~/.bashrc  # or source ~/.zshrc

Verify installation:

# Quick check
make verify-uv

# Or manually
uv --version

Install gcloud CLI

Recommended: Use the setup script (ensures persistence)

# Run the setup script (installs latest version and configures PATH)
./scripts/setup-gcloud.sh

# Or via Makefile
make setup-gcloud

Manual installation:

# Linux/macOS
curl https://sdk.cloud.google.com | bash

# macOS (via Homebrew)
brew install --cask google-cloud-sdk

# Windows
# Download installer: https://cloud.google.com/sdk/docs/install

Ensure persistence:

After installation, gcloud should be automatically added to your PATH. If not available in new terminals:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/google-cloud-sdk/bin:$PATH"

# Enable completion (optional but recommended)
source "$HOME/google-cloud-sdk/path.bash.inc"  # or path.zsh.inc
source "$HOME/google-cloud-sdk/completion.bash.inc"  # or completion.zsh.inc

# Then reload your shell
source ~/.bashrc  # or source ~/.zshrc

Initialize gcloud:

# Authenticate
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Update to latest version
gcloud components update

Verify installation:

# Quick check
make verify-gcloud

# Or manually
gcloud --version
gcloud config get-value project

Install all tools at once:

# Install both uv and gcloud CLI
make setup-tools

Getting Started

1. Clone and Setup

git clone <repository-url>
cd InfraAlert

# Install and configure all required tools (uv + gcloud)
make setup-tools

# Or install individually
make setup-uv      # Install uv package manager
make setup-gcloud  # Install gcloud CLI

Environment Setup

Important: .env files are gitignored for security. You need to create them from the example files.

Run the setup script to create .env files from templates:

./scripts/setup-env.sh

Or manually copy the example files:

# Root .env file (used by most agents)
cp .env.example .env

# Agent-specific .env files (optional, agents fall back to root .env)
cp agents/issue_detection/.env.example agents/issue_detection/.env
cp agents/resource_coordination/.env.example agents/resource_coordination/.env

Required Environment Variables:

• GEMINI_API_KEY - Your Google Gemini API key (required for all agents)
• PROJECT_ID or GOOGLE_CLOUD_PROJECT - Your GCP project ID
• Other GCP credentials as needed (service accounts, buckets, etc.)

Optional - Africa's Talking (SMS Notifications):

• AFRICASTALKING_USERNAME - Your Africa's Talking username (or sandbox for testing)
• AFRICASTALKING_API_KEY - Your Africa's Talking API key
• AFRICASTALKING_SENDER_ID - Custom sender ID (optional, default: "InfraAlert")

Note: Africa's Talking is optional. Without it, the system runs in "mock mode" (no actual SMS sent). See the Africa's Talking section in .env.example for setup instructions.

Edit the .env files and add your actual credentials. Never commit .env files to git!

2. Install Dependencies

# Install all dependencies (production + development)
make install-dev

# Or manually
uv pip install -r requirements.txt
uv pip install -r requirements-test.txt

3. Verify Setup

# Run tests
make test

# Run linting
make lint

# Run both (recommended before committing)
make check

4. Start Local Development

# Start all services via Docker Compose
docker-compose up

# Or run individual agents (see agent-specific READMEs)
cd agents/issue_detection
python app.py

5. Optional: Setup SMS Notifications (Africa's Talking)

Africa's Talking provides cost-effective SMS notifications for InfraAlert (40-90% cheaper than alternatives).

# Quick setup (creates secrets in Secret Manager)
./scripts/setup-africastalking.ps1  # Windows PowerShell
# or
./scripts/setup-africastalking.sh   # Linux/Mac/WSL

# For detailed setup instructions, see:
# See .env.example for Africa's Talking configuration

Benefits:

• 💰 Cost-effective: ~$0.003-0.005 per SMS to Nigeria (vs $0.035-0.09 with Twilio)
• 🇳🇬 Better coverage: Local presence in Nigeria with excellent deliverability
• 🆓 Free sandbox: Test for free before going live

Not required: System works without SMS (notifications disabled in mock mode).

6. Quick Commands

make help          # Show all available commands
make install       # Install production dependencies only
make install-dev   # Install all dependencies
make lint          # Check code quality
make lint-fix      # Auto-fix linting issues
make test          # Run test suite
make check         # Run lint + tests
make clean         # Remove caches and temporary files

Build & Deployment

Local Development

Start all services with hot-reload:

# Use development override for auto-reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Or via Makefile
make docker-up

Build all Docker images locally:

make build-all

Build single service:

make build-service SERVICE=issue-detection
make build-service SERVICE=orchestrator

Deploy to Cloud Run

Deploy all services:

make deploy-all

Deploy single service:

make deploy-service SERVICE=priority-analysis

Test deployed service:

# Test health and readiness endpoints
./scripts/test-service.sh issue-detection-agent

# Or via Makefile
make test-service SERVICE=issue-detection-agent

Configuration Management

Validate build config:

make validate-config  # Validate main cloudbuild.yaml
./scripts/validate-all-builds.sh  # Validate all cloudbuild files

View available make commands:

make help

Quick development workflow:

# 1. Make changes
# 2. Run quality checks
make check

# 3. Test locally
make docker-up

# 4. Build image
make build-service SERVICE=issue-detection

# 5. Deploy (when ready)
make deploy-service SERVICE=issue-detection

For Agent Engine deployment, see docs/agent-engine-deployment.md.

Cost Management

Monitoring Costs

Track your Google Cloud costs to stay within budget:

./scripts/setup-cost-monitoring.sh

Current Optimization Status

All services are configured for cost-efficient operation:

• ✓ Scale to zero when not in use (min-instances=0)
• ✓ Optimized CPU and memory allocations
• ✓ Automatic scaling based on demand

Development

Package Management with uv

This project uses uv for fast, reliable package management:

# Install packages (replaces: pip install)
uv pip install <package>

# Install from requirements.txt
uv pip install -r requirements.txt

# Install in development mode
uv pip install -e .

# List installed packages
uv pip list

Code Quality

make lint          # Check code (Ruff + MyPy)
make lint-fix      # Auto-fix issues
make format        # Format code
make format-check  # Check formatting

Testing

make test          # Run all tests
make check         # Lint + test (use before committing)

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually
make pre-commit

Tools Used:

• Ruff - Linting and formatting
• MyPy - Type checking
• Pytest - Testing
• uv - Package management

CI/CD

Automated builds and deployments via:

• Cloud Build for image building and deployment
• Cloud Run for hosting services
• Artifact Registry for image storage

Test locally before pushing:

make test-cloudbuild

Deploy manually:

gcloud builds submit --config=cloudbuild.yaml --substitutions=_TAG=$(git rev-parse --short HEAD)

Documentation

Core Documentation

• AGENTS.md - Agent development and deployment guidelines
• docs/agent-engine-deployment.md - Google Agent Engine deployment guide
• docs/adk-workflow-agents.md - ADK workflow agent patterns (Sequential, Parallel, Loop)

Tech Stack

• Platform: Google Cloud Platform
• AI/ML: Google Generative AI (Gemini), Vision API, Speech-to-Text, Natural Language API
• Framework: Google ADK (Agent Development Kit)
• Databases: Firestore, BigQuery
• Storage: Cloud Storage
• Compute: Cloud Run
• Messaging: Pub/Sub
• Monitoring: Cloud Monitoring, Cloud Logging
• MCP: FastMCP (Model Context Protocol SDK for tool integration)
• SMS Provider: Africa's Talking (optional, for cost-effective Nigerian SMS)
• Package Manager: uv (fast, reliable Python package management)

License

See LICENSE file for details.