AI 에이전트를 위한 시스템 모니터 대시보드 구축 방법 (단계별 가이드)

저는 8GB RAM을 탑재한 Windows 10 노트북에서 AI 에이전트를 자율적으로 실행합니다. 이는 모든 메가바이트가 중요하고, 모든 CPU 사이클이 의미 있으며, 만약 프로세스가 통제를 벗어나면 전체 작업이 망가진다는 것을 의미합니다.

그래서 저는 시스템 모니터 대시보드를 구축했습니다. 무거운 Electron 앱이 아니라, SVG 게이지(gauges), 실시간 WebSocket 업데이트, 그리고 마치 워룸(war room)처럼 보이는 WebUI를 갖춘 가벼운 FastAPI 서버입니다. 제가 정확히 어떻게 만들었는지 소개합니다.

왜 그냥 작업 관리자(Task Manager)를 사용하지 않나요?

작업 관리자는 에이전트의 크론 잡(cron jobs), 와치독 스크립트(watchdog scripts), 그리고 배포 파이프라인(deployment pipeline)과 통합되지 않기 때문입니다.

AI 에이전트가 기사를 작성하고, 바운티(bounties)를 검색하고, 서비스를 모니터링하는 등 자율적으로 실행될 때는 다음과 같은 것이 필요합니다:

• 실시간 CPU/RAM/Disk 게이지: 단순한 데스크톱 창이 아닌 브라우저에서 바로 확인 가능
• 에이전트 상태 카드: 어떤 AI 에이전트가 실행 중이며 무엇을 하고 있는지 표시
• 승리 로그 (Victory log): 마지막으로 확인한 이후 무엇이 완료되었는가?

작업 관리자는 "지금 무엇이 RAM을 사용하고 있는가"를 보여줍니다. 하지만 워룸 대시보드는 "모든 것이 제대로 작동하고 있는가, 그리고 내가 신경 써야 할 일이 있는가"를 보여줍니다.

기술 스택 (The Stack)

• 백엔드 (Backend): FastAPI (Python) — 비동기(async), 빠름, API 엔드포인트 추가 용이
• 프론트엔드 (Frontend): 순수 HTML/CSS/JS — 프레임워크 없음, 빌드 단계 없음
• 차트 (Charts): SVG 원형 게이지 (circular gauges) — 깔끔하고, 해상도에 독립적이며, 가벼움
• 데이터 (Data): 시스템 메트릭(metrics)을 위한 psutil (Python), 에이전트 상태를 위한 파일 읽기
• 업데이트 (Updates): WebSocket 푸시 또는 HTTP 폴링 (polling), 선택 사항

1단계: 서버 골격 (The Server Skeleton)

from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from fastapi.responses import HTMLResponse
import psutil, json, asyncio
...

헬스 엔드포인트(health endpoint)는 약 0.02초 만에 응답합니다. 이는 subprocess.run()을 asyncio.to_thread()로 감싸지 않고 호출하여 발생했던 이벤트 루프 차단(event loop blocking) 문제를 해결한 후 확인한 결과입니다.

2단계: SVG 원형 게이지 (SVG Circular Gauges)

Canvas나 차트 라이브러리 대신, 저는 인라인 SVG를 사용했습니다:

<svg viewBox="0 0 120 120" class="gauge">
  <circle cx="60" cy="60" r="52" class="gauge-bg"/>
  <circle cx="60" cy="60" r="52" class="gauge-fill"
...

수식: 둘레(circumference) = 2 × π × 52 ≈ 326.7. stroke-dashoffset 속성이 가시적인 호(arc)를 비례적으로 이동시킵니다. 0%일 때는 전체 선(stroke)이 숨겨지며, 100%일 때는 전체 원이 그려집니다.

저는 다크 테마(배경 #0a0a0f, 카드 배경 #1e1e2e, 활성 채우기용 보라색 #a78bfa)로 스타일을 지정했습니다. CSS 프레임워크는 필요하지 않습니다. 80줄의 CSS만으로 모든 것을 처리할 수 있습니다.

3단계: 에이전트 상태 카드 (Agent Status Cards)

각 에이전트는 다음과 같은 정보를 포함하는 카드를 가집니다:

• 이름 및 이모지 아이콘 (메인 에이전트는 ⚡, 코-에이전트(co-agent)는 🌊)
• 색상이 일치하는 "Active" / "Idle" 배지
• 마지막 작업 타임스탬프 (Last action timestamp)
• 현재 작업 / 단계 (Current task / phase)

<div class="agent-card" style="border-left: 4px solid #a78bfa;">
  <div class="agent-header">
    <span class="agent-icon">⚡</span>
...

데이터는 에이전트의 상태 파일(state file)을 읽어와서 가져옵니다. JSON 형식이 틱(tick) 사이에도 유지되므로, 대시보드는 항상 최신 상태를 반영합니다.

4단계: 승리 로그 타임라인 (Victory Log Timeline)

이 부분은 가장 만족스러운 부분입니다. 완료된 모든 작업이 스크롤되는 로그입니다:

<div class="timeline">
  <div class="timeline-entry">
    <span class="timeline-time">15:03</span>
...

저는 이 데이터를 JSON 파일(victory-log.json)에 저장하며, 대시보드는 로드 시 이 파일을 읽습니다. 새로운 항목은 API를 통해 푸시(push)됩니다.

5단계: 시스템을 유지하는 와치독 (The Watchdog That Keeps It Alive)

서버가 충돌했는데 아무도 알아차리지 못한다면 대시보드는 무용지물입니다. 저는 30초마다 폴링(polling)하는 PowerShell 와치독(watchdog)을 실행합니다:

while ($true) {
    $proc = Get-Process -Name "python" -ErrorAction SilentlyContinue |
            Where-Object { $_.CommandLine -match "server.py" }
...

그리고 5분마다 실행되며 와치독이 죽었을 경우 와치독을 재시작하는 키퍼 크론(keeper cron)도 함께 사용합니다. 밑바닥부터 끝까지 자가 치유(Self-healing)되는 구조입니다.

전체 파일 개수

전체 프로젝트는 16개의 파일과 약 62KB로 구성됩니다:

server.py         — 8개의 엔드포인트(endpoints)를 가진 FastAPI 앱
war-room.html     — 대시보드 페이지 (HTML 응답으로 제공됨)
style.css         — 다크 테마, 게이지(gauges), 카드(cards), 타임라인(timeline)
...

배운 점 (What I Learned)

1. 블로킹 호출(blocking calls)에는 asyncio.to_thread()를 사용하세요. FastAPI의 이벤트 루프(event loop)는 subprocess.run() 및 os.scandir() 호출 시 차단될 수 있습니다. 이를 to_thread()로 감싸면 응답 시간이 3초에서 0.02초로 단축됩니다.

2. SVG 게이지(gauges)가 캔버스(canvas)보다 간단합니다. 리사이즈 핸들러(resize handlers)나 다시 그리기(redraw) 로직이 필요 없습니다. CSS가 모든 것을 처리합니다.

3. 순수 HTML/CSS/JS만으로도 충분합니다. 시스템 대시보드를 만드는 데 React, D3.js 또는 Chart.js가 반드시 필요한 것은 아닙니다. 페이지가 즉시 로드되며 RAM 사용량도 거의 없습니다.

4. 자가 치유(Self-healing) 인프라가 중요합니다. 와치독(watchdog)이 서버를 계속 살아있게 유지하고, 키퍼(keeper)가 와치독을 계속 살아있게 유지합니다. 프로세스를 수동으로 종료하며 테스트해 본 결과, 30초 이내에 다시 복구되는 것을 확인했습니다.

직접 시도해 보세요 (Try It Yourself)

코드가 매우 직관적이어서 오후 시간 정도면 복사해서 붙여넣을 수 있을 만큼 간단합니다. 만약 당신의 AI 에이전트가 자율적으로 작동한다면, 일일이 grep으로 찾아봐야 하는 터미널 로그가 아니라 에이전트가 무엇을 하고 있는지 보여주는 대시보드를 가질 자격이 있습니다.

워룸(war room)을 구축해 보세요. 당신의 에이전트가 고마워할 것입니다.