guardia-docs/08_AI에이전트_Paperclip_설계서.md

# GUARDiA ITSM — AI 에이전트 (Paperclip × GUARDiA) 설계서

**문서 버전**: 1.0  
**작성일**: 2026-05-25  
**대상 독자**: 개발자, DevOps 엔지니어, 운영 관리자

---

## 목차

1. [개요 및 목적](#1-개요-및-목적)
2. [아키텍처 설계](#2-아키텍처-설계)
3. [Phase 1 — Paperclip 개발 도구 설정](#3-phase-1--paperclip-개발-도구-설정)
4. [Phase 2 — Ollama 로컬 LLM 설정](#4-phase-2--ollama-로컬-llm-설정)
5. [Phase 3 — GUARDiA 에이전트 엔진](#5-phase-3--guardia-에이전트-엔진)
6. [Phase 4 — 자율 운영 대시보드](#6-phase-4--자율-운영-대시보드)
7. [API 엔드포인트 설계](#7-api-엔드포인트-설계)
8. [보안 제약사항](#8-보안-제약사항)
9. [스케줄러 잡 설계](#9-스케줄러-잡-설계)
10. [테스트 결과](#10-테스트-결과)
11. [운영 가이드](#11-운영-가이드)
12. [향후 로드맵](#12-향후-로드맵)

---

## 1. 개요 및 목적

### 1.1 배경

GUARDiA ITSM은 온프레미스 IT 서비스 관리 플랫폼으로, 서비스 요청(SR), 장애 관리, SSL 인증서 모니터링, PM 일정 관리, SI 프로젝트 관리를 제공합니다.

AI 에이전트 기능 추가를 통해 다음 목표를 달성합니다:

- **반복 업무 자동화**: 장애 분류, KB 등록, SSL 갱신 SR 생성 등 반복적인 운영 업무를 AI가 자동 처리
- **능동적 모니터링**: 에이전트가 주기적으로 시스템 상태를 확인하고 이상 징후를 감지
- **사람-AI 협업**: 고위험 작업은 사람의 승인을 거쳐 실행하는 거버넌스 체계

### 1.2 Paperclip 프레임워크 채택

[Paperclip](https://github.com/paperclipai/paperclip)은 AI 에이전트 오케스트레이션 오픈소스 프레임워크입니다.

| 특징 | 설명 |
|------|------|
| 조직도 구조 | CEO → CTO → 개발자/QA 계층적 에이전트 관리 |
| 하트비트 시스템 | 에이전트가 주기적으로 깨어나 작업 수행 후 대기 |
| 이슈 추적 | GitHub 스타일의 태스크/이슈 관리 |
| 거버넌스 | 위험 수준에 따른 사람 승인 게이트 |

### 1.3 보안 원칙

> **외부 LLM/AI API 완전 금지** — 모든 AI 추론은 Ollama (localhost:11434) 를 통해 온프레미스에서 처리

---

## 2. 아키텍처 설계

### 2.1 전체 구조

```
┌──────────────────────────────────────────────────────────────────┐
│                        GUARDiA ITSM                              │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                     FastAPI Layer                           │ │
│  │  /api/agents/*  ←──────────────────── agents.html (SPA)    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                            │                                     │
│  ┌─────────────────────────▼─────────────────────────────────┐   │
│  │                  AgentEngine (core)                        │   │
│  │                                                            │   │
│  │   INCIDENT_TRIAGE  KB_CURATOR  SSL_WATCHER                │   │
│  │   WBS_MONITOR      PM_SUGGESTER  DEVELOPER                │   │
│  └─────────────────────────────────────────────────────────────┘ │
│                            │                                     │
│  ┌────────────────┐   ┌─────▼───────────────────────────────┐    │
│  │  APScheduler   │──▶│   OllamaClient (LLM 추론)           │    │
│  │  (9 cron jobs) │   │   localhost:11434                   │    │
│  └────────────────┘   └─────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  SQLite DB: tb_agent_config | tb_agent_task | tb_agent_approval│
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

외부(개발 시에만):
  Paperclip CLI ──── paperclip.config.json ──── agents/*.md
```

### 2.2 에이전트 조직도

```
            ┌─────────────┐
            │    CEO      │  전략·결재
            └──────┬──────┘
          ┌────────┴────────┐
   ┌──────▼──────┐    ┌────▼──────┐
   │    CTO      │    │ PM_AGENT  │  프로젝트 관리
   └──────┬──────┘    └───────────┘
   ┌──────┴────────┐
┌──▼──────┐  ┌────▼───┐
│DEVELOPER│  │  QA    │
└─────────┘  └────────┘

운영 자동화 에이전트 (Ops):
  INCIDENT_TRIAGE  ←  장애 자동 분류
  KB_CURATOR       ←  지식베이스 자동 등록
  SSL_WATCHER      ←  SSL 만료 감시
  WBS_MONITOR      ←  WBS 지연 감지
  PM_SUGGESTER     ←  PM 일정 제안
```

---

## 3. Phase 1 — Paperclip 개발 도구 설정

### 3.1 파일 구조

```
C:\GUARDiA\
└── paperclip\
    ├── paperclip.config.json     # 조직도 + 거버넌스 설정
    ├── README.md                  # 설치/사용 가이드
    └── agents\
        ├── ceo.md                 # CEO 에이전트 페르소나
        ├── cto.md                 # CTO 에이전트 페르소나
        ├── developer.md           # 개발자 에이전트 페르소나
        └── qa.md                  # QA 에이전트 페르소나
```

### 3.2 설치

```bash
npm install -g @paperclipai/paperclip

# Paperclip 초기화 (프로젝트 루트에서)
cd C:\GUARDiA
paperclip init

# 에이전트 시작
paperclip start
```

### 3.3 조직도 구성 (paperclip.config.json 요약)

```json
{
  "org_chart": {
    "ceo": { "reports_to": null, "can_approve": ["deploy", "code_commit"] },
    "cto": { "reports_to": "ceo" },
    "developer": { "reports_to": "cto" },
    "qa": { "reports_to": "cto" },
    "pm_agent": { "reports_to": "ceo" }
  },
  "llm": {
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "models": {
      "ceo": "guardia-agent",
      "developer": "codellama:7b",
      "qa": "codellama:7b"
    }
  },
  "governance": {
    "require_human_approval": ["code_commit", "deploy", "delete_data"]
  }
}
```

### 3.4 거버넌스 규칙

| 액션 | 승인 방식 | 승인자 |
|------|-----------|--------|
| code_commit | 사람 승인 필수 | CTO 또는 CEO |
| deploy | 사람 승인 필수 | CEO |
| delete_data | 사람 승인 필수 | CEO |
| 장애 분류 (일반) | 자동 승인 | — |
| 장애 분류 (CRITICAL) | 사람 승인 필수 | 담당자 |
| KB 등록 | 자동 승인 | — |
| SSL 갱신 SR 생성 | 자동 승인 | — |

---

## 4. Phase 2 — Ollama 로컬 LLM 설정

### 4.1 파일 구조

```
C:\GUARDiA\
└── ollama\
    ├── setup.ps1               # 자동 설치 스크립트
    └── Modelfile.guardia       # 커스텀 모델 정의
```

### 4.2 자동 설치 (setup.ps1)

```powershell
# 실행 방법:
Set-ExecutionPolicy Bypass -Scope Process -Force
.\setup.ps1

# 스크립트 동작:
# 1. OllamaSetup.exe 다운로드
# 2. 설치 후 ollama serve 시작
# 3. 헬스체크 (10회 재시도)
# 4. llama3.1:8b + codellama:7b 풀링
# 5. guardia-agent 커스텀 모델 생성
```

### 4.3 guardia-agent 모델 (Modelfile.guardia)

```
FROM llama3.1:8b
SYSTEM """당신은 GUARDiA ITSM AI 운영 에이전트입니다.
한국어로 응답하며, IT 서비스 관리(ITSM)에 특화되어 있습니다.
보안 원칙: 외부 API 호출 금지, 민감 정보 노출 금지."""
PARAMETER temperature 0.2
PARAMETER num_predict 2048
```

### 4.4 OllamaClient API

| 메서드 | 설명 |
|--------|------|
| `health_check()` | Ollama 서버 상태 확인 |
| `list_models()` | 설치된 모델 목록 조회 |
| `resolve_model(preferred)` | 선호 모델이 없으면 fallback 모델 반환 |
| `chat(messages, model)` | 대화형 추론 |
| `generate(prompt, model)` | 단일 프롬프트 추론 |
| `json_generate(prompt, model)` | JSON 응답 추출 (코드블록 자동 제거) |
| `pull_model(model)` | 모델 다운로드 |

---

## 5. Phase 3 — GUARDiA 에이전트 엔진

### 5.1 파일 구조

```
C:\GUARDiA\itsm\
├── models.py                    # AgentConfig, AgentTask, AgentApproval 모델 추가
├── core\
│   ├── llm_client.py            # OllamaClient 구현
│   └── agents.py                # AgentEngine 구현
└── routers\
    └── agents.py                # 16개 REST API 엔드포인트
```

### 5.2 데이터 모델

#### AgentConfig (tb_agent_config)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | INTEGER PK | 에이전트 ID |
| name | VARCHAR | 에이전트 이름 |
| role | VARCHAR | AgentRole enum |
| llm_provider | VARCHAR | ollama (고정) |
| llm_model | VARCHAR | 사용할 LLM 모델 |
| system_prompt | TEXT | 역할 설명 프롬프트 |
| heartbeat_cron | VARCHAR | 크론 표현식 |
| is_active | BOOLEAN | 활성화 여부 |
| status | VARCHAR | IDLE/ACTIVE/WORKING/ERROR/PAUSED |
| last_heartbeat | DATETIME | 마지막 실행 시각 |
| total_tasks | INTEGER | 누적 처리 태스크 수 |
| total_tokens | INTEGER | 누적 사용 토큰 수 |

#### AgentTask (tb_agent_task)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | INTEGER PK | 태스크 ID |
| agent_id | INTEGER FK | 에이전트 참조 |
| title | VARCHAR | 태스크 제목 |
| status | VARCHAR | PENDING/IN_PROGRESS/COMPLETED/FAILED |
| input_data | JSON | 입력 데이터 |
| output_data | JSON | LLM 출력 결과 |
| tokens_used | INTEGER | 사용된 토큰 수 |

#### AgentApproval (tb_agent_approval)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | INTEGER PK | 승인 ID |
| agent_id | INTEGER FK | 에이전트 참조 |
| task_id | INTEGER FK nullable | 연관 태스크 |
| action_type | VARCHAR | 액션 유형 |
| action_data | JSON | 액션 상세 데이터 |
| status | VARCHAR | PENDING/APPROVED/REJECTED/AUTO_APPROVED |
| reviewed_by | INTEGER FK nullable | 검토자 |

### 5.3 에이전트별 동작

#### INCIDENT_TRIAGE (15분마다 실행)

```
1. 미배정 장애(assigned_to=None, status=OPEN/RECEIVED) 조회
2. LLM JSON 분류 요청:
   { severity: CRITICAL/HIGH/MEDIUM/LOW,
     category: HARDWARE/SOFTWARE/NETWORK/...,
     reason: "분류 근거" }
3. CRITICAL → AgentApproval(PENDING) 생성
4. 그 외 → AUTO_APPROVED + Incident 등급 즉시 반영
```

#### KB_CURATOR (매시간 정각)

```
1. SR 완료 건 중 KB가 없는 건 조회
2. LLM KB 초안 생성:
   { kb_title, symptom, cause, solution, tags }
3. KBDocument 생성 (published=False, 검토 대기)
4. AgentApproval(AUTO_APPROVED) 기록
```

#### SSL_WATCHER (매일 08:30)

```
1. ssl_expire_date가 0~30일 이내인 서버 조회
2. 기존 SSL 갱신 SR이 없는 경우에만 SR 자동 생성
3. 긴급도: 7일 미만=CRITICAL, 30일 미만=HIGH
```

#### WBS_MONITOR (매일 08:00)

```
1. 진행 중 SI 프로젝트의 WBS 지연 항목 조회
2. 3일+ 지연: 주의, 10일+ 지연: CRITICAL
3. LLM 리스크 분석:
   { risk_level, probability, impact, title, mitigation_plan }
4. ProjectRisk 자동 등록
5. CRITICAL 리스크 → 사람 승인 필요
```

#### PM_SUGGESTER (매일 09:00)

```
1. PM 일정이 없는 서버 조회
2. 권장 PM 일정 제안 (AgentTask 기록)
```

#### DEVELOPER (수동 트리거 or 이슈 등록 시)

```
1. PENDING AgentTask 조회
2. LLM 코드/응답 생성
3. CODE_CHANGE 태스크 → AgentApproval(PENDING) 생성
```

### 5.4 하트비트 사이클

```
에이전트 등록 (AgentConfig 생성)
        │
        ▼
APScheduler Cron 잡 등록
        │
        ▼ (스케줄 도달)
status = ACTIVE
        │
        ▼
Ollama health_check()
        │ (실패)──────────────────► status = ERROR
        │ (성공)
        ▼
_handler(db, agent) 실행
        │
        ├─ 작업 완료 ──► AgentTask(COMPLETED) + status = IDLE
        └─ 오류 발생 ──► AgentTask(FAILED) + status = ERROR
                                last_error 기록
```

---

## 6. Phase 4 — 자율 운영 대시보드

### 6.1 접근 경로

```
http://localhost:8001/agents
```

### 6.2 대시보드 구성

| 영역 | 설명 |
|------|------|
| LLM 상태 배너 | Ollama 온라인/오프라인 상태 실시간 표시 |
| 통계 카드 | 총 에이전트 수, 활성, 오늘 태스크, 오늘 토큰, 승인 대기 |
| 에이전트 탭 | 에이전트 카드 (역할 배지, 상태 펄스 애니메이션) |
| 조직도 탭 | 계층적 트리 렌더링 |
| 승인 대기 탭 | 보류 중 승인 목록 (CRITICAL 강조) |
| 태스크 피드 탭 | 전체 에이전트 태스크 실시간 피드 |

### 6.3 에이전트 상태 색상 코드

| 상태 | 색상 | 설명 |
|------|------|------|
| IDLE | 회색 | 대기 중 |
| ACTIVE | 파랑 | 심장박동 시작 |
| WORKING | 주황 (펄스) | 작업 진행 중 |
| ERROR | 빨강 | 오류 발생 |
| PAUSED | 노랑 | 일시 중지 |

### 6.4 역할별 색상 배지

```
CEO       → 보라색  (#6C5CE7)
CTO       → 파랑색  (#0984E3)
DEVELOPER → 초록색  (#00B894)
QA        → 노랑색  (#FDCB6E)
PM_AGENT  → 청록색  (#00CEC9)

INCIDENT_TRIAGE → 빨강  (#E17055)
KB_CURATOR      → 민트  (#55EFC4)
SSL_WATCHER     → 주황  (#FD79A8)
WBS_MONITOR     → 남색  (#74B9FF)
PM_SUGGESTER    → 연두  (#A29BFE)
```

---

## 7. API 엔드포인트 설계

### 7.1 전체 목록 (16개)

| HTTP | 경로 | 설명 | 권한 |
|------|------|------|------|
| GET | /api/agents | 에이전트 목록 | USER+ |
| POST | /api/agents | 에이전트 생성 | ADMIN |
| GET | /api/agents/stats | 통계 요약 | USER+ |
| GET | /api/agents/orgchart | 조직도 | USER+ |
| GET | /api/agents/approvals | 승인 대기 목록 | USER+ |
| PATCH | /api/agents/approvals/{id}/review | 승인/거부 | USER+ |
| GET | /api/agents/llm/health | LLM 상태 확인 | USER+ |
| POST | /api/agents/llm/pull | 모델 다운로드 | ADMIN |
| GET | /api/agents/{id} | 에이전트 상세 | USER+ |
| PATCH | /api/agents/{id} | 에이전트 수정 | ADMIN |
| DELETE | /api/agents/{id} | 에이전트 삭제 | ADMIN |
| POST | /api/agents/{id}/heartbeat | 수동 하트비트 | USER+ |
| POST | /api/agents/{id}/pause | 에이전트 일시정지 | ADMIN |
| POST | /api/agents/{id}/resume | 에이전트 재개 | ADMIN |
| GET | /api/agents/{id}/tasks | 태스크 목록 | USER+ |
| POST | /api/agents/{id}/tasks | 태스크 생성 | USER+ |

> CUSTOMER 역할: 모든 에이전트 엔드포인트 접근 불가

### 7.2 주요 스키마

#### AgentConfigOut

```json
{
  "id": 1,
  "name": "장애 분류 에이전트",
  "role": "INCIDENT_TRIAGE",
  "description": "미배정 장애를 자동으로 분류합니다",
  "llm_model": "guardia-agent",
  "heartbeat_cron": "*/15 * * * *",
  "is_active": true,
  "status": "IDLE",
  "last_heartbeat": "2026-05-25T08:15:00",
  "total_tasks": 42,
  "total_tokens": 15300
}
```

#### AgentApprovalReview

```json
{
  "status": "APPROVED",
  "notes": "내용 확인 후 승인합니다"
}
```

#### AgentStatsOut

```json
{
  "total_agents": 6,
  "active_agents": 4,
  "today_tasks": 12,
  "today_tokens": 5240,
  "pending_approvals": 2
}
```

---

## 8. 보안 제약사항

### 8.1 런타임 LLM 보안

| 규칙 | 내용 |
|------|------|
| 외부 API 금지 | 모든 LLM 호출은 localhost:11434 (Ollama) 만 허용 |
| 토큰 최대값 | num_predict: 2048 (무한 루프 방지) |
| 온도 고정 | temperature: 0.2 (결정론적 응답) |
| 타임아웃 | HTTP 요청 30초 타임아웃 |

### 8.2 에이전트 액션 보안

| 규칙 | 내용 |
|------|------|
| CRITICAL 액션 | 반드시 사람 승인 후 실행 |
| 위험 명령어 | `rm -rf /`, `shutdown`, `mkfs` 등 차단 |
| 서버 정보 | `ip_addr`, `ssh_user`, `os_pw_enc` API 응답 미포함 |
| 파일 경로 | `file_path` 컬럼 API 응답 절대 미노출 |

### 8.3 접근 제어

| 역할 | 에이전트 조회 | 에이전트 생성/수정/삭제 | 승인 처리 |
|------|--------------|----------------------|----------|
| CUSTOMER | ✗ | ✗ | ✗ |
| USER | ✓ | ✗ | ✓ |
| OPERATOR | ✓ | ✗ | ✓ |
| ADMIN | ✓ | ✓ | ✓ |

---

## 9. 스케줄러 잡 설계

### 9.1 전체 잡 목록 (9개)

| ID | 잡 이름 | 스케줄 | 설명 |
|----|---------|--------|------|
| 1 | cert_check | 매일 09:00 | SSL 인증서 만료 확인 |
| 2 | pm_check | 매일 09:05 | PM 점검 일정 확인 |
| 3 | on_call_notify | 매일 08:55 | 온콜 교대 알림 |
| 4 | batch_cleanup | 매일 02:00 | 배치 결과 정리 |
| 5 | agent_incident_triage | 매 15분 | 장애 자동 분류 |
| 6 | agent_kb_curator | 매시간 정각 | KB 자동 생성 |
| 7 | agent_ssl_watcher | 매일 08:30 | SSL 만료 감시 |
| 8 | agent_wbs_monitor | 매일 08:00 | WBS 지연 감지 |
| 9 | agent_pm_suggester | 매일 09:00 | PM 일정 제안 |

### 9.2 에이전트 하트비트 흐름

```
APScheduler → _agent_heartbeat_by_role(role)
                        │
                        ▼
             AgentConfig WHERE role=? AND is_active=True 조회
                        │
              ┌─────────┴───────────┐
          없음│                     │있음
              ▼                     ▼
            skip              for each agent:
                           get_agent_engine().run_heartbeat(id)
```

---

## 10. 테스트 결과

### 10.1 구문 검사 (Syntax Check)

| 파일 | 결과 |
|------|------|
| `models.py` | ✅ 통과 |
| `main.py` | ✅ 통과 |
| `core/llm_client.py` | ✅ 통과 |
| `core/agents.py` | ✅ 통과 |
| `core/scheduler.py` | ✅ 통과 |
| `routers/agents.py` | ✅ 통과 |

### 10.2 심볼 검증

| 항목 | 검증 내용 | 결과 |
|------|-----------|------|
| AgentRole enum | 10가지 역할 정의 | ✅ |
| AgentEngine handlers | 6개 핸들러 구현 | ✅ |
| OllamaClient | 7개 메서드 구현 | ✅ |
| API 엔드포인트 | 16개 라우터 등록 | ✅ |
| 스케줄러 잡 | 9개 (기존 4 + 신규 5) | ✅ |
| main.py 라우터 | 34개 라우터 등록 | ✅ |

### 10.3 보안 검증

| 항목 | 결과 |
|------|------|
| 외부 LLM API 호출 없음 | ✅ |
| ServerOut에 ip_addr 미포함 | ✅ |
| CUSTOMER 역할 차단 | ✅ |
| CRITICAL 승인 게이트 | ✅ |

---

## 11. 운영 가이드

### 11.1 에이전트 등록

```bash
# 장애 분류 에이전트 등록
curl -X POST http://localhost:8001/api/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "장애 분류 에이전트",
    "role": "INCIDENT_TRIAGE",
    "description": "미배정 장애를 자동으로 분류하고 우선순위를 설정합니다",
    "llm_model": "guardia-agent",
    "system_prompt": "당신은 IT 장애 분류 전문가입니다...",
    "heartbeat_cron": "*/15 * * * *",
    "is_active": true
  }'
```

### 11.2 수동 하트비트 실행

```bash
# 에이전트 즉시 실행
curl -X POST http://localhost:8001/api/agents/1/heartbeat \
  -H "Authorization: Bearer <token>"
```

### 11.3 승인 처리

```bash
# 승인
curl -X PATCH http://localhost:8001/api/agents/approvals/5/review \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "APPROVED", "notes": "내용 확인 후 승인"}'

# 거부
curl -X PATCH http://localhost:8001/api/agents/approvals/5/review \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "REJECTED", "notes": "추가 검토 필요"}'
```

### 11.4 LLM 상태 확인

```bash
# Ollama 서버 상태
curl http://localhost:8001/api/agents/llm/health

# 응답 예시
{
  "healthy": true,
  "models": ["guardia-agent:latest", "llama3.1:8b", "codellama:7b"],
  "version": "0.1.x"
}
```

### 11.5 모니터링 대시보드

```
브라우저 접속: http://localhost:8001/agents
자동 갱신: 30초 간격
```

---

## 12. 향후 로드맵

| 단계 | 기능 | 예상 시기 |
|------|------|----------|
| v1.1 | 에이전트 간 메시지 전달 (CEO→CTO 위임) | 2026 Q3 |
| v1.2 | 에이전트 학습 (이전 태스크 기반 파인튜닝) | 2026 Q3 |
| v1.3 | 멀티모달 지원 (스크린샷 분석) | 2026 Q4 |
| v2.0 | 에이전트 마켓플레이스 (커뮤니티 에이전트) | 2027 Q1 |
| v2.1 | 엣지 배포 (경량 모델: llama3.2:1b) | 2027 Q1 |

---

*이 문서는 GUARDiA ITSM Paperclip × GUARDiA Phase 1~4 구현 내용을 담고 있습니다.*  
*Ollama 공식 문서: https://ollama.com*  
*Paperclip GitHub: https://github.com/paperclipai/paperclip*