spider4ai ⚡

Multi-Agent RAG Platform for Multi-Cloud Infrastructure Management

spider4ai는 CB-Spider와 MC-Insight를 MCP(Model Context Protocol) 기반으로 통합하여, 자연어로 멀티 클라우드 인프라를 관리할 수 있는 AI 에이전트 플랫폼입니다.

💡 "azure-westus에 Ubuntu VM 하나 만들어줘" → 자동으로 Image 조회 → Spec 선택 → VPC/SG/KeyPair 생성 → VM 프로비저닝

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       Web UI (port 8080)                        │
│               index.html · app.js · styles.css                  │
├─────────────────────────────────────────────────────────────────┤
│                      Web Server (Go)                            │
│         REST API · Auth · Session · Connection Resolver         │
├─────────────────────────────────────────────────────────────────┤
│                  ReACT Engine (LLM Loop)                        │
│          System Prompt · Tool Routing · Token Mgmt              │
├─────────────────────────────────────────────────────────────────┤
│                     NexusCore Aggregator                        │
│             Multi-Agent Hub · Tool Router · MCP                 │
├──────────────┬──────────┬────────────┬──────────────────────────┤
│ CloudHawk 🦅 │ SkyLens 🔭│ DocSearch 📚│    WebSearch 🌐      │
│   51 tools   │  9 tools │   2 tools  │      2 tools             │
├──────────────┼──────────┼────────────┼──────────────────────────┤
│  CB-Spider   │MC-Insight│ ChromemDB  │    DuckDuckGo            │
│  REST API    │ REST API │ (Vector)   │    Instant API           │
├──────────────┴──────────┴────────────┴──────────────────────────┤
│   AWS │ Azure │ GCP │ Alibaba │ Tencent │ IBM │ NCP │ NHN …     │
└─────────────────────────────────────────────────────────────────┘
          64 MCP Tools · 4 Sub-Agents · ReACT Loop

✨ Key Features

🤖 Multi-Agent System

CloudHawk 🦅 (51 tools) — CB-Spider 기반 실제 인프라 운영 (VM, VPC, SG, KeyPair, Disk, NLB, Cluster 등)
SkyLens 🔭 (9 tools) — MC-Insight 기반 메타정보 조회 (VM Image, Spec, Price, Region/Zone)
DocSearch 📚 (2 tools) — 로컬 문서 시맨틱 검색 (RAG, ChromemDB 벡터 DB)
WebSearch 🌐 (2 tools) — DuckDuckGo 기반 실시간 웹 검색

🧠 Intelligent LLM Integration

ReACT Loop — 최대 15 iteration의 Reason + Act 루프
Smart Tool Routing — Image/Spec/Price는 SkyLens, 인프라 작업은 CloudHawk으로 자동 라우팅
Dynamic Connection Context — 선택한 connection의 CSP/Region을 자동 resolve하여 LLM에 전달
Token Management — 오래된 tool result 자동 압축, 토큰 초과 시 aggressive compact
VM Provisioning Guide — 시스템 프롬프트에 4단계 프로비저닝 가이드 + 3회 자동 재시도 전략 내장

🌐 Web UI

채팅 기반 인터페이스 (세션 관리, 히스토리)
Connection 드롭다운 선택 → 자동 CSP/Region resolve
Tool call 실시간 표시 (✅ 성공 / ❌ 실패 / ⏳ 진행중)
클릭 가능한 Tool call 상세 패널
Markdown 렌더링 지원

🔌 Multi-LLM Backend Support

OpenAI (GPT-4o, GPT-4o-mini)
GitHub Models (Azure Inference)
Groq (Llama 3.3 70B)
Ollama (Qwen, Llama 등 로컬 모델)
Anthropic Claude
모든 OpenAI-compatible API 지원

💾 Persistent Memory

SQLite 기반 세션/메시지/프로비저닝 이력 저장
사용자 preferences 관리

📁 Directory Structure

spider4ai/
├── cmd/
│   ├── web/             # 🌐 Web Server (main entry point)
│   │   └── main.go      #    REST API, Auth, Session, Chat, Connection Resolver
│   ├── nexuscore/       # 🖥️  CLI tool for NexusCore
│   │   └── main.go      #    status, tools, call, recommend, compare, provision
│   ├── mcpserver/       # 🦅 CloudHawk MCP Server (CB-Spider)
│   │   └── main.go
│   ├── insightmcp/      # 🔭 SkyLens MCP Server (MC-Insight)
│   │   └── main.go
│   ├── ragmcp/          # 📚 DocSearch MCP Server (RAG)
│   │   └── main.go
│   ├── searchmcp/       # 🌐 WebSearch MCP Server (DuckDuckGo)
│   │   └── main.go
│   ├── cloudhawk/       # CloudHawk standalone agent
│   ├── skylens/         # SkyLens standalone agent
│   └── chat/            # Interactive chat CLI
├── internal/
│   ├── llm/             # LLM abstraction layer
│   │   ├── types.go     #   Provider interface, Message, ToolDef
│   │   ├── openai.go    #   OpenAI-compatible provider
│   │   ├── claude.go    #   Anthropic Claude provider
│   │   ├── ollama.go    #   Ollama local model provider
│   │   └── react.go     #   ReACT engine, system prompt builder
│   ├── nexuscore/       # Multi-agent aggregator
│   │   └── agent.go     #   SubAgent management, tool routing
│   ├── spider/          # CB-Spider REST API client
│   │   └── client.go
│   ├── insight/         # MC-Insight REST API client
│   │   └── client.go
│   ├── mcpserver/       # CloudHawk MCP tool definitions (51 tools)
│   │   ├── server.go
│   │   └── tools.go
│   ├── insightmcp/      # SkyLens MCP tool definitions (9 tools)
│   │   └── server.go
│   ├── ragengine/       # RAG engine (ChromemDB vector search)
│   │   └── engine.go
│   ├── ragmcp/          # DocSearch MCP server
│   │   └── server.go
│   ├── websearch/       # Web search client (DuckDuckGo)
│   │   └── search.go
│   ├── searchmcp/       # WebSearch MCP server
│   │   └── server.go
│   ├── memory/          # SQLite persistent storage
│   │   └── store.go
│   ├── cloudhawk/       # CloudHawk agent logic
│   └── skylens/         # SkyLens agent logic
├── web/
│   ├── config.yaml      # Web server configuration
│   ├── static/          # Frontend files
│   │   ├── index.html   #   Main chat UI
│   │   ├── login.html   #   Login page
│   │   ├── app.js       #   Frontend JavaScript (~840 lines)
│   │   └── styles.css   #   Styles
│   ├── spider-mcp-server.exe
│   ├── insight-mcp-server.exe
│   ├── rag-mcp-server.exe
│   └── search-mcp-server.exe
├── start_server.bat     # Quick-start script (Windows)
├── go.mod
└── README.md

🚀 Quick Start

Prerequisites

Go 1.24+
CB-Spider running on http://localhost:1024
LLM API key (OpenAI, GitHub Models, Groq, 또는 로컬 Ollama)

1. Build

# Web Server
go build -o web-server.exe ./cmd/web/

# MCP Servers (web/ 디렉토리에 빌드)
go build -o web/spider-mcp-server.exe ./cmd/mcpserver/
go build -o web/insight-mcp-server.exe ./cmd/insightmcp/
go build -o web/rag-mcp-server.exe ./cmd/ragmcp/
go build -o web/search-mcp-server.exe ./cmd/searchmcp/

# CLI (optional)
go build -o nexuscore.exe ./cmd/nexuscore/

2. Configure

환경변수 또는 web/config.yaml로 설정:

# LLM 설정 (필수)
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-4o-mini
export LLM_API_KEY=your-api-key
export LLM_BASE_URL=https://models.inference.ai.azure.com

# CB-Spider (필수)
export SPIDER_URL=http://localhost:1024/spider

# MC-Insight (선택)
export INSIGHT_URL=http://mc-insight.cloud-barista.org:8000
export INSIGHT_TOKEN=your-token

지원하는 LLM 백엔드 설정 예시:

Backend	LLM_BASE_URL	LLM_MODEL	Notes
GitHub Models (gpt-4o)	`https://models.inference.ai.azure.com/v1`	`gpt-4o`	⚠️ 무료 150회/일, 주기적 대기 필요
GitHub Models (gpt-4o-mini)	`https://models.inference.ai.azure.com`	`gpt-4o-mini`	⚠️ 무료 150회/일, 주기적 대기 필요
Groq	`https://api.groq.com/openai/v1`	`llama-3.3-70b-versatile`	⚠️ 무료 rate limit 있음
Gemini	`https://generativelanguage.googleapis.com/v1beta/openai`	`gemini-2.0-flash`	❌ 무료 quota 0, 사실상 사용 불가
Ollama (로컬 7B)	`http://localhost:11434/v1`	`qwen2.5:7b`	⚠️ 무제한, tool calling 품질 낮음
Ollama (로컬 30B)	`http://localhost:11434/v1`	`qwen3:30b-a3b`	⚠️ 무제한, 추론 속도 느림

💡 권장: GitHub Models gpt-4o-mini (최고 품질/비용 밸런스, 일일 한도 주의)

3. Run

# Web Server 실행
./web-server.exe

# 또는 Windows에서 start_server.bat 실행
start_server.bat

브라우저에서 http://localhost:8080 접속 후 로그인:

Username: admin
Password: your-passwd (config.yaml의 admin_key)

📡 REST API

모든 API는 Authorization: Bearer <token> 헤더 필요 (로그인 후 발급)

Method	Endpoint	Description
POST	`/api/auth/login`	로그인 → 토큰 발급
GET	`/api/auth/check`	토큰 유효성 확인
GET	`/api/health`	Sub-agent 상태 확인
GET	`/api/connections`	클라우드 연결 설정 목록
GET	`/api/tools`	전체 MCP 도구 목록 (64개)
POST	`/api/tool/call`	MCP 도구 직접 호출
POST	`/api/chat`	AI 채팅 (ReACT Loop)
GET	`/api/sessions`	채팅 세션 목록
POST	`/api/sessions/delete`	세션 삭제
GET	`/api/provisions`	프로비저닝 이력 조회
GET	`/api/memory/stats`	메모리 스토어 통계
GET	`/api/status`	전체 시스템 상태

Chat API Example

# 로그인
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-passwd"}' | jq -r '.token')

# 채팅 (connection 지정)
curl -X POST http://localhost:8080/api/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "keypair 목록을 보여줘",
    "connection": "azure-westus-config"
  }'

🛠️ MCP Tools (64 total)

CloudHawk 🦅 — CB-Spider (51 tools)

모든 CSP 지원: AWS, Azure, GCP, Alibaba, Tencent, IBM, NCP, NHN, KT, OpenStack 등

Category	Tools
Cloud OS	`list_cloud_os`
Driver	`list_driver`, `get_driver`, `create_driver`, `delete_driver`
Credential	`list_credential`, `get_credential`, `create_credential`, `delete_credential`
Region	`list_region`, `get_region`, `create_region`, `delete_region`
Connection	`list_connection_config`, `get_connection_config`, `create_connection_config`, `delete_connection_config`
VPC	`list_vpc`, `get_vpc`, `create_vpc`, `delete_vpc`
Security Group	`list_security_group`, `get_security_group`, `create_security_group`, `delete_security_group`
KeyPair	`list_key`, `get_key`, `create_key`, `delete_key`
VM	`list_vm`, `get_vm`, `start_vm`, `control_vm`, `terminate_vm`, `list_vm_status`, `get_vm_status`
Disk	`list_disk`, `get_disk`, `create_disk`, `delete_disk`, `attach_disk`, `detach_disk`
NLB	`list_nlb`, `get_nlb`, `create_nlb`, `delete_nlb`, `add_nlb_vms`, `remove_nlb_vms`, `get_nlb_health`
MyImage	`list_myimage`, `get_myimage`, `create_myimage`, `delete_myimage`
Cluster	`list_cluster`, `get_cluster`, `create_cluster`, `delete_cluster`
Tag	`list_tag`, `get_tag`, `create_tag`, `delete_tag`
Price	`get_price_info`
Health	`health_check`

SkyLens 🔭 — MC-Insight (9 tools)

Tool	Description
`get_regions`	Region/Zone 목록 (CSP/region 필터)
`get_vm_specs`	VM Spec 조회 (vCPU/memory/GPU 필터)
`get_vm_images`	VM Image 조회 (OS/architecture 필터)
`get_price_info`	가격 정보 (currency 지원)
`get_spec_filters`	Spec 필터 목록
`get_image_filters`	Image 필터 목록
`get_price_filters`	Price 필터 목록
`get_region_filters`	Region 필터 목록
`get_supported_csp`	지원 CSP 목록

DocSearch 📚 — RAG (2 tools)

Tool	Description
`search_documents`	시맨틱 유사도 검색 (top-K)
`document_stats`	로드된 문서 통계

WebSearch 🌐 — Web (2 tools)

Tool	Description
`web_search`	DuckDuckGo 웹 검색
`fetch_webpage`	URL 컨텐츠 추출

🧠 ReACT Engine

spider4ai의 핵심은 ReACT (Reason + Act) Loop 엔진입니다:

User Query
    │
    ▼
┌─────────────────────────────┐
│  1. Connection Context      │ ← 선택한 connection의 CSP/Region 자동 주입
│     Enrichment              │
├─────────────────────────────┤
│  2. LLM Reasoning           │ ← 시스템 프롬프트 + 64 tool definitions
│     (Think → Plan)          │
├─────────────────────────────┤
│  3. Tool Execution          │ ← NexusCore → MCP Sub-Agent → API
│     (Act → Observe)         │
├─────────────────────────────┤
│  4. Result Analysis         │ ← 결과 분석 후 추가 action 또는 응답
│     (Loop or Respond)       │
└─────────────────────────────┘
    │  (max 15 iterations)
    ▼
Final Response

Smart Tool Routing Rules

Query Type	Routed To	Notes
VM Image 조회	SkyLens `get_vm_images`	CloudHawk image tools 숨김 처리
VM Spec 조회	SkyLens `get_vm_specs`	CloudHawk spec tools 숨김 처리
가격 조회	SkyLens `get_price_info`	캐시된 메타정보 활용
인프라 CRUD	CloudHawk	VPC, SG, Key, VM, Disk, NLB 등
문서 검색	DocSearch	로컬 파일 시맨틱 검색
웹 검색	WebSearch	실시간 최신 정보

VM Provisioning Flow (자동화)

Step 1: LOOKUP (SkyLens)
  ├── get_vm_images → Image ID + 2 backup images
  └── get_vm_specs  → Spec + 2 backup specs

Step 2: PROVISION (CloudHawk)
  ├── create_vpc
  ├── create_security_group (TCP 22 inbound)
  ├── create_keypair
  └── start_vm

Step 3: RETRY (최대 3회)
  ├── Attempt 1: primary_image + primary_spec
  ├── Attempt 2: primary_image + backup_spec
  └── Attempt 3: backup_image + primary_spec

Step 4: REPORT
  └── VM Name, Public IP, Spec, Image, Region

🖥️ CLI Usage (NexusCore)

# 시스템 상태 확인
./nexuscore -action status

# 전체 도구 목록
./nexuscore -action tools

# MCP 도구 직접 호출
./nexuscore -action call -tool list_vm -args '{"connection_name":"aws-seoul-config"}'

# VM Spec 추천 (SkyLens)
./nexuscore -action recommend -csp aws -region us-east-1 -min-vcpu 2 -max-vcpu 4

# 멀티 클라우드 비교
./nexuscore -action compare -regions "aws:us-east-1,azure:westus,gcp:us-central1"

# 자동 VM 프로비저닝
./nexuscore -action smart-provision -conn aws-seoul-config -csp aws -region ap-northeast-2

⚙️ Configuration (web/config.yaml)

server:
  port: 8080
  host: "0.0.0.0"

auth:
  admin_key: "your-passwd"        # 로그인 비밀번호 겸 토큰 시드

llm:
  provider: "openai"               # openai | claude | ollama
  model: "gpt-4o-mini"
  api_key: ""                      # 환경변수 LLM_API_KEY 권장
  base_url: ""                     # 환경변수 LLM_BASE_URL 권장
  max_tokens: 8192

spider:
  url: "http://localhost:1024/spider"

insight:
  url: "http://mc-insight.cloud-barista.org:8000"
  token: ""

mcp_servers:
  spider: "./spider-mcp-server.exe"
  insight: "./insight-mcp-server.exe"
  rag: "./rag-mcp-server.exe"
  search: "./search-mcp-server.exe"

모든 설정은 환경변수로 오버라이드 가능: LLM_PROVIDER, LLM_MODEL, LLM_API_KEY, LLM_BASE_URL, SPIDER_URL, INSIGHT_URL, INSIGHT_TOKEN

🏛️ Tech Stack

Component	Technology
Language	Go 1.24
MCP Protocol	mcp-go v0.32.0
Vector DB	chromem-go v0.7.0
Database	SQLite (pure Go, WAL mode) via go-sqlite
Frontend	Vanilla HTML/CSS/JS
Cloud API	CB-Spider REST API
Meta Info	MC-Insight REST API
Web Search	DuckDuckGo Instant Answer API
Config	YAML + Environment Variables

📊 Comparison: RAG Architectures

RAG vs Agentic RAG vs Multi-Agent RAG

spider4ai는 Multi-Agent RAG 아키텍처를 채택하여:

각 도메인별 전문 에이전트 분리 (CloudHawk, SkyLens, DocSearch, WebSearch)
NexusCore 중앙 허브로 통합 라우팅
ReACT Loop으로 자율적 추론 + 행동 반복
RAG 기반 로컬 문서 검색 통합

📝 License

Apache License 2.0

🔗 Related Projects

CB-Spider — Cloud-Barista Multi-Cloud Infrastructure Federation
MC-Insight — Multi-Cloud Insight (Spec, Image, Price)
Cloud-Barista — Multi-Cloud Service Platform

spider4ai‐poc - cloud-barista/cb-spider GitHub Wiki

spider4ai ⚡

🏗️ Architecture

✨ Key Features

🤖 Multi-Agent System

🧠 Intelligent LLM Integration

🌐 Web UI

🔌 Multi-LLM Backend Support

💾 Persistent Memory

📁 Directory Structure

🚀 Quick Start

Prerequisites

1. Build

2. Configure

3. Run

📡 REST API

Chat API Example

🛠️ MCP Tools (64 total)

CloudHawk 🦅 — CB-Spider (51 tools)

SkyLens 🔭 — MC-Insight (9 tools)

DocSearch 📚 — RAG (2 tools)

WebSearch 🌐 — Web (2 tools)

🧠 ReACT Engine

Smart Tool Routing Rules

VM Provisioning Flow (자동화)

🖥️ CLI Usage (NexusCore)

⚙️ Configuration (web/config.yaml)

🏛️ Tech Stack

📊 Comparison: RAG Architectures

📝 License

🔗 Related Projects

⚠️ GitHub.com Fallback ⚠️

spider4ai‐poc - cloud-barista/cb-spider GitHub Wiki

spider4ai ⚡

🏗️ Architecture

✨ Key Features

🤖 Multi-Agent System

🧠 Intelligent LLM Integration

🌐 Web UI

🔌 Multi-LLM Backend Support

💾 Persistent Memory

📁 Directory Structure

🚀 Quick Start

Prerequisites

1. Build

2. Configure

3. Run

📡 REST API

Chat API Example

🛠️ MCP Tools (64 total)

CloudHawk 🦅 — CB-Spider (51 tools)

SkyLens 🔭 — MC-Insight (9 tools)

DocSearch 📚 — RAG (2 tools)

WebSearch 🌐 — Web (2 tools)

🧠 ReACT Engine

Smart Tool Routing Rules

VM Provisioning Flow (자동화)

🖥️ CLI Usage (NexusCore)

⚙️ Configuration (web/config.yaml)

🏛️ Tech Stack

📊 Comparison: RAG Architectures

📝 License

🔗 Related Projects

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️