MAS (Multi-Agent System)

K8s 인프라 분석 & 의사결정 시스템 - 클러스터를 분석하고 도구 도입 여부를 결정해주는 AI 시스템

🎯 What is this?

MAS는 Kubernetes 클러스터 상태를 분석하고, 도구 도입 추천/비추천을 결정해주는 AI 에이전트 시스템입니다.

사용 시나리오:

1. "Tekton 도입 여부를 결정해줘" → 클러스터 분석 → 도입 추천/비추천 결정
2. 한국어로 이유, 대안, 구현 가이드 제공
3. 기술적 세부사항 없이 명확한 결론 제시

🤖 Agents

Planning Agent (Claude 4.5)

• 도구 요구사항 분석
• 필요한 K8s 리소스 파악
• 확인이 필요한 클러스터 정보 정의

Research Agent (Groq Llama 3.3)

• kubectl 명령어로 클러스터 상태 분석
• 기존 도구 확인 (ArgoCD, Gitea, Prometheus 등)
• 리소스 사용률 및 버전 확인

Decision Agent (Claude 4.5)

• 도입 추천/비추천 결정 (한국어)
• 명확한 이유 제시
• 대안 제시 (비추천인 경우)
• 간단한 구현 가이드 (추천인 경우)

Tech stack

• Backend: LangGraph + LangChain + FastAPI
• UI: Chainlit (chat-style UI)
• Database: PostgreSQL (CNPG)
• Cache: Redis
• LLMs: Claude API (Orchestrator, Planning, Prompt Gen) + Groq Llama 3.3 (Research)
• 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

Example 1: Tekton 도입 여부 결정

User: "Tekton 도입 여부를 결정해줘"

🎼 Orchestrator → 조율

📋 Planning Agent:
  → Tekton 요구사항: Namespace, CRDs, Controllers
  → 필요 리소스: 2 CPU, 4GB RAM
  → 확인 필요: 기존 CI/CD 도구, K8s 버전

🔍 Research Agent:
  → kubectl get nodes: v1.33.6, 3 nodes ✓
  → kubectl get pods -A: ArgoCD 운영 중 발견
  → Gitea Actions 사용 가능 확인

💡 Decision Agent:
  ❌ Tekton 도입 비추천

  이유:
  - ArgoCD + Gitea Actions로 충분
  - 추가 리소스 소비 불필요
  - 학습 곡선 및 유지보수 부담

  대안:
  - Gitea Actions 활용 (이미 설치됨)
  - ArgoCD로 배포 자동화 유지

✨ Output: 명확한 한국어 보고서

Example 2: Harbor 필요성 분석

User: "Harbor가 필요한지 분석해줘"

→ Planning: Harbor 요구사항 분석
→ Research: 기존 registry 확인 (Gitea Container Registry 발견)
→ Decision:
  ❌ Harbor 도입 비추천
  이유: Gitea Container Registry로 충분

✨ 사용자 친화적 한국어 결론

Example 3: Prometheus 설치 여부

User: "Prometheus를 설치해야 할까?"

→ Planning: Monitoring stack 요구사항
→ Research: 이미 Prometheus 운영 중 발견!
→ Decision:
  ✅ 이미 설치되어 있음
  현재 상태: monitoring namespace에서 정상 작동 중

✨ 중복 설치 방지

---

🔧 Workflow

User Input: "X 도입 여부를 결정해줘"
     ↓
Orchestrator (조율)
     ↓
Planning Agent (도구 요구사항 분석)
     ↓
Research Agent (클러스터 상태 분석)
     ↓
Decision Agent (한국어 의사결정 보고서)
     ↓
Output: ✅ 추천 또는 ❌ 비추천 (이유 포함)

📊 출력 예시

# Tekton 도입 분석 결과

## 📊 현재 클러스터 상태
- Kubernetes 버전: v1.33.6
- 노드: 3개 (1 control-plane, 2 workers)
- 기존 CI/CD: ArgoCD, Gitea Actions
- 운영 애플리케이션: 15개

## 💡 권장사항: Tekton 도입 비추천

### ❌ 비추천 이유
1. ArgoCD + Gitea Actions 조합으로 충분
2. 추가 리소스 소비 (2 CPU, 4GB RAM)
3. 학습 곡선 및 운영 부담 증가

### 🔄 권장 대안
- Gitea Actions로 빌드 파이프라인 구성
- ArgoCD로 GitOps 배포 유지
- 필요시 GitHub Actions 연동

## 🎯 결론
현재 인프라로 충분하며, Tekton 도입은 불필요합니다.

🤝 Contributing

Contributions are welcome:

• Improve Planning Agent prompts for better folder structures
• Enhance Research Agent kubectl commands
• Add more infrastructure tools (Harbor, Tekton, CNPG, MetalLB, etc.)
• Better Markdown template for Prompt Generator

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

---

📄 License

MIT