zio/zioinfo-mail

Fork 0

$DESKTOP-TKLFCPR\ython$ DESKTOP-TKLFCPR\ython cfe2901a55 refactor(structure): consolidate all projects under workspace/

- itsm/    -> workspace/guardia-itsm/
- manager/ -> workspace/guardia-manager/
- app/     -> workspace/guardia-messenger/
- manual/  -> workspace/guardia-docs/

workspace/zioinfo-web/ unchanged.
git mv preserves full commit history.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-31 23:50:56 +09:00

22 KiB

Raw Blame History

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

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

개요 및 목적
아키텍처 설계
Phase 1 — Paperclip 개발 도구 설정
Phase 2 — Ollama 로컬 LLM 설정
Phase 3 — GUARDiA 에이전트 엔진
Phase 4 — 자율 운영 대시보드
API 엔드포인트 설계
보안 제약사항
스케줄러 잡 설계
테스트 결과
운영 가이드
향후 로드맵

1. 개요 및 목적

1.1 배경

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

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

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

1.2 Paperclip 프레임워크 채택

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 설치

npm install -g @paperclipai/paperclip

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

# 에이전트 시작
paperclip start

3.3 조직도 구성 (paperclip.config.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)

# 실행 방법:
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

{
  "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

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

AgentStatsOut

{
  "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 에이전트 등록

# 장애 분류 에이전트 등록
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 수동 하트비트 실행

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

11.3 승인 처리

# 승인
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 상태 확인

# 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

22 KiB Raw Blame History Unescape Escape