Skip to content

spider4ai‐poc

Jump to bottom Edit New page
ByoungSeob Kim edited this page Feb 9, 2026 · 1 revision

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
Add a custom footer

Table of contents

Clone this wiki locally