MAS (Multi-Agent System)

MAS is a unified UI and orchestration layer for multiple AI agents (similar to ChatGPT, Claude, Gemini), running on your own Kubernetes cluster.

🎯 Architecture

Agents

• Claude Code (Orchestrator): overall coordinator & DevOps expert
• Qwen Backend: backend engineer (FastAPI, Node.js)
• Qwen Frontend: frontend engineer (Next.js, React)
• Qwen SRE: monitoring & reliability engineer

Tech stack

• Backend: LangGraph + LangChain + FastAPI
• UI: Chainlit (chat-style UI)
• Database: PostgreSQL (CNPG)
• Cache: Redis
• LLMs: Claude API + Groq Llama 3.x (OpenAI-compatible API)
• Deploy: Kubernetes + ArgoCD

---

🚀 Local development

1. Run with Docker Compose

cd deploy/docker

# Copy or create .env and fill in your API keys
# (ANTHROPIC_API_KEY, GROQ_API_KEY, etc.)

# Start the full stack
docker compose up -d

# Tail logs
docker compose logs -f mas

Open: http://localhost:8000

2. Run backend directly (Python)

cd services/backend

# Create venv
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Environment variables
cp .env.example .env
# Edit .env and set your API keys

# Run Chainlit app
chainlit run chainlit_app.py

---

☸️ Kubernetes deployment

1. Create namespace and secrets

kubectl create namespace mas

kubectl create secret generic mas-api-keys \
  --from-literal=anthropic-api-key=YOUR_CLAUDE_KEY \
  --from-literal=openai-api-key=YOUR_OPENAI_KEY \
  --from-literal=google-api-key=YOUR_GEMINI_KEY \
  -n mas

2. Deploy via ArgoCD

# Create ArgoCD Application
kubectl apply -f deploy/argocd/mas.yaml

# Sync and check status
argocd app sync mas
argocd app get mas

3. Deploy from your server (example)

# SSH into your k3s master
ssh oracle-master

# Apply ArgoCD Application
sudo kubectl apply -f /path/to/deploy/argocd/mas.yaml

# Check status
sudo kubectl get pods -n mas
sudo kubectl logs -f deployment/mas -n mas

Ingress example (if configured): https://mas.mayne.vcn

---

🎨 UI customization

Chainlit theme & behavior

You can customize the UI via services/backend/.chainlit:

[UI]
name = "MAS"
show_readme_as_default = true
default_collapse_content = true

Agent prompts

System prompts for each agent live in services/backend/agents.py.
You can tune:

• how the Orchestrator routes tasks
• coding style of backend/frontend agents
• SRE troubleshooting behavior

---

📊 Observability

Prometheus ServiceMonitor (example)

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: mas
  namespace: mas
spec:
  selector:
    matchLabels:
      app: mas
  endpoints:
  - port: http
    path: /metrics

Grafana dashboards

Recommended panels:

• LangGraph workflow metrics
• Per-agent latency & error rate
• Token usage and cost estimates
• Backend API latency & 5xx rate

---

🔧 Advanced features

1. MCP (Model Context Protocol) with Claude

Using Claude Code as Orchestrator, MAS can access:

• Filesystem (read/write project files)
• Git (status, commit, push, PR)
• SSH (run remote commands on your servers)
• PostgreSQL (schema inspection, migrations, queries)
• Kubernetes (kubectl via MCP tool)

This allows fully automated workflows like:

• “Create a new service, add deployment manifests, and deploy to k3s.”
• “Debug failing pods and propose a fix, then open a PR.”

2. Multi-agent collaboration (LangGraph)

Typical workflow:

User request
  ↓
Claude Orchestrator
  ↓ decides which agent(s) to call
Backend Dev → Frontend Dev → SRE
  ↓
Claude Orchestrator (review & summary)
  ↓
Final answer to user

Examples:

• Full‑stack feature (API + UI + monitoring)
• Infra rollout (Harbor, Tekton, CNPG, MetalLB) with validation

---

📝 Usage examples

Backend API request

User: "Create a signup API with FastAPI.
       Use PostgreSQL and JWT tokens."

🎼 Orchestrator:
  → routes to Qwen Backend

⚙️ Qwen Backend:
  → generates FastAPI router, Pydantic models, DB schema, JWT logic

🎼 Orchestrator:
  → reviews, suggests improvements, and outputs final code snippet & file layout

Frontend component request

User: "Build a responsive dashboard chart component using Recharts."

🎼 Orchestrator:
  → routes to Qwen Frontend

🎨 Qwen Frontend:
  → generates a Next.js/React component with TypeScript and responsive styles

🎼 Orchestrator:
  → explains how to integrate it into your existing app

Infra / SRE request

User: "Prometheus is firing high memory alerts for the PostgreSQL pod.
       Help me stabilize it."

🎼 Orchestrator:
  → routes to Qwen SRE

📊 Qwen SRE:
  → analyzes metrics & logs (conceptually),
    proposes tuning (Postgres config, indexes, pooler),
    and suggests alert threshold adjustments.

---

🤝 Contributing

Contributions are welcome:

• New agents (e.g., data engineer, security engineer)
• New tools (Harbor, Tekton, CNPG, MetalLB integrations)
• Better prompts and workflows
• Docs and examples

Feel free to open issues or PRs in your Git repository.

---

📄 License

MIT