n8n-AI-Multiple-Agent-Team/WORKFLOWS_IMPLEMENTATION.md

n8n Workflow Implementation Guide

Overview

This repository contains complete, executable n8n workflow JSON files for a multi-agent AI homelab management system. All workflows are based on the architectural specifications from Chapter 8 of the project documentation.

Files Included

Main Export File

• workflows-export.json - Single JSON file containing all 7 workflows in the required format with a files array

Individual Workflow Files

AI Agent Workflows:

• workflows/agents/vishnu-cto.json - CTO Orchestrator Agent (Preservation)
• workflows/agents/brahma-network.json - Network Administrator Agent (Creation)
• workflows/agents/shiva-devops.json - DevOps Engineer Agent (Transformation)
• workflows/agents/saraswati-database.json - Database Administrator Agent (Knowledge)
• workflows/agents/ganesha-security.json - Security Engineer Agent (Problem-Solving)
• workflows/agents/hanuman-helpdesk.json - Helpdesk Support Agent (Service)

Utility Workflows:

• workflows/utilities/approval-handler.json - Human-in-the-Loop Approval Handler

Workflow Details

1. Vishnu CTO Agent (vishnu-cto.json)

Role: Orchestrator and CTO Agent
Trigger: Webhook (POST to /critical-issue)
Version: 1.0

Nodes:

• Webhook - Critical Issue (receives alerts)
• AI Agent - Vishnu CTO (analyzes and delegates)
• Code - Delegation Logic (parses AI response)
• Execute Workflow - Delegate (calls specialist agents)
• Code - Synthesize Results (combines reports)
• Telegram - Approval Request (sends to human)
• Webhook Response (returns status)

Key Features:

• Receives critical issues via webhook
• AI-powered analysis and delegation to specialist agents
• Synthesizes multi-agent reports
• Requests human approval via Telegram
• Uses system prompt from Chapter 8

2. Brahma Network Agent (brahma-network.json)

Role: Network Administrator
Trigger: Schedule (Every 15 minutes)
Version: 1.0

Nodes:

• Schedule Trigger - Every 15 min
• HTTP Request - UniFi Status (checks http://unifi.local:8443)
• Execute Command - Net Diagnostics (ping & traceroute)
• Code - Combine Network Data
• AI Agent - Brahma Network (analyzes results)
• Telegram - Network Report (sends notifications)

Key Features:

• Scheduled monitoring every 15 minutes
• Checks UniFi Controller health via HTTP
• Runs network diagnostics (ping, traceroute)
• AI agent analyzes network data
• Reports status via Telegram

3. Shiva DevOps Agent (shiva-devops.json)

Role: DevOps Engineer
Trigger: Webhook (POST to /cicd-deploy)
Version: 1.0

Nodes:

• Webhook Trigger - CI/CD Push
• HTTP Request - Plex Session Check (http://plex.local:32400)
• AI Agent - Shiva DevOps (creates deployment plan)
• Code - Deployment Decision
• IF - Can Deploy? (checks active sessions)
• Execute Command - Docker Restart
• Telegram - Deployment Blocked/Success
• Webhook Response

Key Features:

• Triggered by CI/CD webhook
• Checks for active Plex sessions before deploying
• AI-powered deployment planning
• Conditional execution based on system state
• Notifications for success/blocked deployments

4. Saraswati Database Agent (saraswati-database.json)

Role: Database Administrator and Knowledge Keeper
Trigger: Schedule (Every 30 minutes)
Version: 1.0

Nodes:

• Schedule Trigger - Every 30 min
• HTTP Request - Database Status (checks http://postgres.local:5432)
• Execute Command - Query Analysis (PostgreSQL diagnostics)
• Code - Combine Database Data
• AI Agent - Saraswati Database (analyzes results)
• Telegram - Database Report (sends notifications)

Key Features:

• Scheduled database monitoring every 30 minutes
• Database health checks via HTTP
• Query performance analysis
• Slow query detection
• AI-powered optimization recommendations
• Reports via Telegram

5. Ganesha Security Agent (ganesha-security.json)

Role: Security Engineer and Obstacle Remover
Trigger: Schedule (Every 10 minutes)
Version: 1.0

Nodes:

• Schedule Trigger - Every 10 min
• Execute Command - Auth Logs (checks failed login attempts)
• Execute Command - Fail2ban Status
• Execute Command - Certificate Check (SSL/TLS expiration)
• Code - Combine Security Data
• AI Agent - Ganesha Security (threat analysis)
• Telegram - Security Report (sends alerts)

Key Features:

• Frequent security monitoring every 10 minutes
• Authentication log analysis
• Fail2ban status monitoring
• Certificate expiration tracking
• AI-powered threat assessment
• Immediate alerts for security incidents

6. Hanuman Helpdesk Agent (hanuman-helpdesk.json)

Role: Helpdesk Agent and Devoted Servant
Trigger: Telegram (on message)
Version: 1.0

Nodes:

• Telegram Trigger - User Requests
• Code - Parse User Request (categorization)
• AI Agent - Hanuman Helpdesk (triage and response)
• Code - Process Response
• IF - Should Escalate?
• Telegram - Direct Response
• Telegram - Escalation Notice
• Execute Workflow - Escalate to Vishnu

Key Features:

• Real-time user support via Telegram
• Intelligent request categorization
• AI-powered triage and troubleshooting
• Automatic escalation to specialist agents
• Friendly, empathetic communication
• User satisfaction tracking

7. Approval Handler (approval-handler.json)

Role: Utility Workflow for Human-in-the-Loop
Trigger: Telegram (on message)
Version: 1.0

Nodes:

• Telegram Trigger - On Message
• Code - Parse User Response (YES/NO/other)
• Switch - YES/NO/Other (routes flow)
• Execute Workflow - Run Approved Fix
• Telegram - Confirm Execution/Denial/Other Response

Key Features:

• Listens for Telegram messages
• Parses user approval responses (YES/NO)
• Routes based on response
• Executes approved workflows
• Confirms actions back to user

Configuration Requirements

Environment Variables

All workflows use placeholders that need to be configured in your n8n environment:

TELEGRAM_CHAT_ID=your_chat_id
OPENAI_API_KEY=your_openai_api_key

Credentials

The following n8n credentials need to be created:

1. Telegram API (id: 1, name: "Telegram API")

   • Required for all Telegram nodes
   • Add your bot token from BotFather

2. OpenAI Account (for AI Agent nodes)

   • Add your OpenAI API key
   • Model: gpt-4o-mini (cost-effective) or gpt-4

Service URLs

Update these placeholder URLs to match your environment:

• http://unifi.local:8443 - UniFi Controller
• http://plex.local:32400 - Plex Media Server
• http://proxmox.local - Proxmox VE (if used)

Installation Instructions

Method 1: Import Individual Workflows

1. Open n8n web interface
2. Click Workflows → Add Workflow
3. Click the three dots menu (⋯) → Import from File
4. Select one of the individual workflow JSON files
5. Configure credentials and environment variables
6. Activate the workflow

Repeat for all 7 workflows.

Method 2: Programmatic Import

Use the main export file with the n8n API or bulk import tool:

# Example using the workflows-export.json structure
# This file contains all 7 workflows in a single JSON with 'files' array
cat workflows-export.json | jq -r '.files[] | @json' | while read workflow; do
  echo "$workflow" | n8n import:workflow --input=-
done

Workflow Execution Flow

Typical Scenario: Critical Issue Response

1. Alert Triggered → Vishnu CTO receives webhook with issue details
2. Analysis → Vishnu AI Agent analyzes and determines delegation
3. Delegation → Vishnu calls Brahma Network workflow via Execute Workflow
4. Specialist Work → Brahma checks network, runs diagnostics
5. Synthesis → Vishnu receives Brahma's report and synthesizes
6. Human Approval → Vishnu sends approval request via Telegram
7. User Response → Approval Handler workflow processes YES/NO
8. Execution → If approved, fixes are executed
9. Confirmation → User receives completion notification

Scheduled Monitoring

1. Schedule Trigger → Brahma Network runs every 15 minutes
2. Data Collection → HTTP Request to UniFi, Execute Command for diagnostics
3. Analysis → AI Agent processes network data
4. Notification → Report sent via Telegram (only if issues detected)

CI/CD Deployment

1. Webhook → Shiva DevOps receives deployment request
2. Pre-checks → Checks active Plex sessions
3. AI Planning → Creates deployment plan with risk assessment
4. Conditional Logic → IF active sessions = 0, proceed; else wait
5. Execution → Docker restart command
6. Notification → Success or blocked status via Telegram

Customization Guide

Modifying AI Agent Behavior

Edit the systemMessage parameter in AI Agent nodes to change:

• Decision-making criteria
• Output format requirements
• Escalation triggers
• Personality and communication style

Adjusting Schedule

Change the Schedule Trigger interval in brahma-network.json:

"parameters": {
  "rule": {
    "interval": [
      {
        "field": "minutes",
        "minutesInterval": 15  // Change this value
      }
    ]
  }
}

Adding New Services

To monitor additional services, duplicate and modify brahma-network.json:

1. Change the HTTP Request URL
2. Update the Execute Command for service-specific checks
3. Adjust the AI Agent system prompt for the new domain

Testing

Test Vishnu CTO Workflow

curl -X POST http://your-n8n-instance/webhook/critical-issue \
  -H "Content-Type: application/json" \
  -d '{
    "service": "plex",
    "issue": "Service is down",
    "severity": "high"
  }'

Test Shiva DevOps Workflow

curl -X POST http://your-n8n-instance/webhook/cicd-deploy \
  -H "Content-Type: application/json" \
  -d '{
    "service": "plex",
    "version": "1.32.8",
    "action": "update"
  }'

Test Approval Handler

Send a message to your Telegram bot:

YES APR-12345

Validation

All workflows have been validated for:

• ✅ Valid JSON syntax
• ✅ Version set to "1.0"
• ✅ Complete node configurations
• ✅ Proper connection definitions
• ✅ Required node types present
• ✅ Environment variable placeholders
• ✅ Example URLs for services
• ✅ AI Agent system prompts from Chapter 8

Troubleshooting

Workflow Not Executing

1. Check workflow is activated (toggle in top-right)
2. Verify credentials are properly configured
3. Check webhook URLs are correct
4. Review execution history for errors

AI Agent Not Responding

1. Verify OpenAI API key is valid
2. Check model selection (gpt-4o-mini or gpt-4)
3. Review system prompt formatting
4. Check for API rate limits or quota issues

Telegram Notifications Not Sending

1. Verify Telegram bot token in credentials
2. Check TELEGRAM_CHAT_ID environment variable
3. Ensure workflow is activated
4. Test with manual execution first

Execute Workflow Node Failing

1. Verify target workflow exists and is activated
2. Check workflow ID/name matches
3. Ensure no circular dependencies
4. Review permissions if using separate n8n instances

Architecture Notes

This implementation follows the cosmic wisdom architecture from Chapter 8:

• Vishnu (Preservation) - Maintains stability, coordinates team
• Brahma (Creation) - Builds and manages infrastructure
• Shiva (Transformation) - Deploys changes and updates
• Approval Handler - Human-in-the-Loop pattern for safety

Each agent has specialized knowledge and clear delegation boundaries, creating a robust multi-agent system for homelab management.

Support

For issues or questions:

1. Review the main README.md in this repository
2. Check Chapter 8 (AI Team) in docs/08-AI-Team.md
3. Open an issue on GitHub
4. Consult n8n documentation at https://docs.n8n.io

Version History

• v1.0 - Initial implementation with all 6 AI agent workflows + 1 utility
  • Vishnu CTO Agent (Orchestrator - Preservation)
  • Brahma Network Agent (Infrastructure - Creation)
  • Shiva DevOps Agent (Deployment - Transformation)
  • Saraswati Database Agent (Data - Knowledge)
  • Ganesha Security Agent (Protection - Problem-Solving)
  • Hanuman Helpdesk Agent (Support - Service)
  • Approval Handler (Human-in-the-Loop)