AI 에이전트를 위한 라이브 빌리지 대시보드 구축 방법

_Originally published on garystow.co.uk. The free starter code is on GitHub.

Written by Gary Stow with help from AI tools. Every fact is checked and every article is approved by Gary before it goes live.

저는 많은 자동화 작업을 수행합니다. 한 팀은 이 사이트를 위해 기사를 작성하고 검토하며, 다른 팀은 세 가지 데모 트레이딩 전략을 실행하고, 감독관이 둘 모두를 지켜보며 무엇이 필요한지 결정합니다. 몇 달 동안 제가 이것들을 볼 수 있는 유일한 방법은 테이블로 가득 찬 대시보드였습니다. 저에게는 효과적이었지만, 아내나 아이들이 매일 저에게 제가 실제로 무엇을 만들고 있는지 물어볼 때, 작업 이름으로 된 표는 그들에게 아무 의미가 없었습니다.

그래서 저는 이 모든 것을 마을(village)로 바꿨습니다. 가족들에게 제 작업을 설명하는 데 도움이 되도록 그것을 구축했고, 시각적인 접근 방식은 제가 말할 수 있는 어떤 것보다도 그들이 이해하기 훨씬 쉽게 만들었습니다. 스타일은 RimWorld와 South Park의 교차점입니다. 저는 RimWorld를 플레이하는 것을 좋아하고, 항상 South Park의 팬이었습니다.

이 사이트의 모든 페이지는 집입니다. 모든 트레이딩 전략은 결과에 따라 자라거나 시드는 밭입니다. 모든 요청은 타운 홀(Town Hall)로 걸어오고, 건축가들은 항상 다음 집을 짓고 있습니다. 빌리지에서 라이브 버전을 볼 수 있습니다.

라이브 빌리지 열기 ↗ 빌리지가 작동하는 방식

이 가이드는 여러분 스스로 구축할 수 있는 방법을 한 단계씩 보여줍니다. 게임 엔진이 필요하지 않으며, 여기에 있는 모든 것은 무료입니다. Python 스크립트를 실행할 수 있다면, 이것을 할 수 있습니다.

시작하기 전에 필요한 것들

• 컴퓨터에 설치된 Python 3
• 텍스트 편집기 (저는 VS Code를 사용합니다)
• 웹 브라우저
• 관찰하고자 하는, 자체적으로 실행되는 무언가 (예: 예약 스크립트, AI 에이전트 또는 봇)
• 선택 사항: 공개 버전으로 사람들이 방문할 수 있는 무료 GitHub Pages 웹사이트

마을의 작동 방식

움직이는 부분은 단 세 가지이며, 이들을 분리해 두는 것이 관리가 용이하게 만드는 핵심입니다.

1. 자동화(automations)가 무언가를 수행할 때마다 로그 파일에 한 줄을 작성합니다.
2. 작은 Python 스크립트가 해당 로그를 읽어 마을을 설명하는 JSON 파일을 작성합니다.
3. 하나의 HTML 페이지가 그 JSON 파일을 읽어 캔버스 위에 마을을 그려냅니다.

이 그림(drawing)은 자동화와 직접적으로 통신하지 않습니다. 이는 마을에 버그가 생겨도 실제 작업에는 영향을 줄 수 없으며, 원하는 만큼 자주 그림을 재구축할 수 있음을 의미합니다.

1단계: 모든 자동화가 흔적을 남기도록 만들기

마을은 오직 여러분의 자동화가 기록한 내용만을 보여줄 수 있습니다. 모든 스크립트에 활동 로그에 한 줄을 추가하는 공유 기능을 부여하세요. 이벤트당 하나의 JSON 라인으로 구성된 형식(JSON Lines)이 가장 간단합니다. 왜냐하면 파일 끝에만 내용을 추가하기 때문입니다.

    import json
    from datetime import datetime
...

중요한 순간마다 호출하세요: 작업 시작, 완료, 실패, 또는 사람의 개입을 기다리는 경우.

2단계: 각 건물이 무엇을 의미하는지 결정하기

무언가를 그리기 전에, 각 건물이 무엇을 상징하는지 문서로 작성하세요. 이 과정이 아무리 시스템을 본 적 없는 사람에게도 마을의 작동 원리를 이해시키는 부분입니다. 제 시스템은 다음과 같습니다:

• 읍사무소(Town Hall)는 감독관 역할을 합니다. 모든 요청은 이곳을 거칩니다.
• 각 팀은 자신만의 구역을 가집니다: 한쪽에는 웹사이트, 다른 쪽에는 거래가 있습니다. 한 곳에서 발생한 작업이 다른 곳으로 넘어가지 않습니다.
• 집들은 웹 페이지입니다. 큰 집일수록 더 많은 방문을 받습니다.
• 밭(Fields)은 거래 전략입니다. 모두 같은 크기로 시작하며, 이익이나 손실에 따라 성장하거나 줄어듭니다.
• 읍사무소 밖에 서 있는 사람들은 제 결정이 필요한 대기 요청입니다.

로그에 있는 이름과 해당 작업이 발생하는 건물 간의 간단한 조회(lookup)를 유지하세요.

3단계: 로그를 하나의 데이터 파일로 변환하기

이것을 village_data.py로 저장하세요. 이 스크립트는 지난 48시간 동안의 로그를 읽고 페이지가 데이터를 가져올 파일에 내용을 작성합니다. 주기적으로 실행하거나, (9단계에서 하듯이) 페이지가 요청할 때마다 실행하면 됩니다.

    import json
    from datetime import datetime, timedelta
...

페이지 뷰는 이미 가지고 있는 모든 분석(analytics) 내보내기 파일에서 가져올 수 있습니다. 일단 임의의 숫자로 시작하여 그림이 작동하는 것을 확인한 후 실제 숫자로 교체하세요.

4단계: 등각 투영 타일로 지면 그리기

RimWorld 스타일의 모습은 등각(isometric) 타일에서 나옵니다. 이는 높이보다 너비가 두 배인 마름모꼴입니다. 작은 함수 하나가 격자 칸을 화면상의 위치로 변환하며, 나머지 모든 것은 이 위에 구축됩니다.

    const TW = 64, TH = 32; // 하나의 타일: 가로 64, 세로 32

...

격자를 순회하면서 각 칸에 대해 tile을 호출하세요. 잔디에는 한 가지 색상, 도로에는 다른 색상, 그리고 구역 사이의 강에는 파란색을 사용하세요.

5단계: 종이 오려 붙인 스타일로 건물 그리기

건물은 세 가지 모양으로 구성됩니다. 더 어두운 왼쪽 벽, 더 밝은 오른쪽 벽, 그리고 지붕입니다. 두꺼운 검은 윤곽선이 오려낸 듯한(cut-out) 느낌을 줍니다. 지도 뒤쪽에서 앞쪽 순서로, x + y를 기준으로 정렬하여 그리면 가까운 건물이 뒤에 있는 건물을 가리게 됩니다.

    function poly(ctx, pts, fill) {
      ctx.beginPath();
...

상자 모양이 제대로 작동하는 것을 확인한 후에 창문, 문, 간판을 추가하세요. 너무 일찍 예쁘게 만들고 싶은 충동을 참으세요. 먼저 평범한 상자로 레이아웃이 작동하도록 만드세요.

6단계: 사람들에게 실제 작업을 시키기

이 부분이 생명력을 불어넣는 부분입니다. 데이터 파일의 모든 이벤트는 작은 사람을 한 건물에서 다른 건물로 이동시킵니다. 감독관(supervisor)이 무언가를 승인하면, 누군가가 청사(Town Hall)에서 실행자(executor)에게 걸어가게 합니다. 기사가 게시되면, 건설자가 주거 구역으로 걸어갑니다.

    const walkers = [];
...

몇 초마다 하나의 이벤트를 재생하고 소진되면 처음으로 돌아가도록 루프를 만드세요. 각 팀의 흐름에 색깔 있는 경로를 그려서, 웹사이트 작업과 트레이딩 작업이 절대 교차하지 않는 것을 한눈에 볼 수 있게 하세요.

7단계: 데이터가 세상을 변화하게 하라

이제 그림을 실제 숫자에 연결하세요. 이 두 가지 규칙이 제 작업의 대부분을 수행합니다.

    function fieldScale(net) {              // net = profit or loss in pounds
      return Math.max(0.6, Math.min(1.45, 1 + net / 400));
...

클램핑(Clamping)이 중요합니다. 제한이 없으면 한 번의 큰 성공이나 최악의 주가 변동으로 인해 필드가 화면 전체를 채우거나 사라질 수 있습니다. 마을을 읽기 좋게 유지하는 제한을 선택하세요.

8단계: 그리기 루프 실행하기

페이지를 데이터 파일 옆에 village/index.html로 저장하고, 여기에 <canvas id="village" width="1200" height="750">를 포함시키세요. 데이터를 한 번 가져온 다음, 초당 약 60번 다시 그리세요.

    const canvas = document.getElementById("village");
    const ctx = canvas.getContext("2d");
...

drawGround, drawBuildings, 그리고 drawWalkers는 위에서 설명한 조각들로 직접 만든 함수입니다.

9단계: 자신의 컴퓨터에서 비공개 버전 서비스하기

제 개인 마을은 로컬 대시보드와 동일한 작은 Flask 앱에서 실행되므로, 저를 기다리는 실제 요청을 포함하여 모든 것을 보여줄 수 있습니다. 타운 홀(Town Hall) 밖에 있는 사람을 클릭하면 결정이 열립니다.

    from flask import Flask, send_from_directory
    import village_data          # 3단계 스크립트
...

pip install flask로 Flask를 한 번 설치하고, 스크립트를 실행한 다음, 브라우저에서 localhost:5007/village/를 열면 자신만의 시스템을 관찰할 수 있습니다.

10단계: 안전한 공개 버전 게시하기

공개 버전은 다른 데이터 파일을 사용하는 동일한 페이지를 사용합니다. 어떤 것이든 제 컴퓨터를 떠나기 전에, 함수가 사적인 모든 것을 제거합니다. 요청은 일반적인 제목이 되고, 돈은 반올림됩니다.

    def make_public(data):
        pub = dict(data)
...

예약된 작업(scheduled task)은 페이지와 공개 데이터 파일을 새 브랜치에 복사한 다음, 풀 리퀘스트(pull request)를 열고, 헤드리스 브라우저에서의 자동 레이아웃 검사와 SEO 체크리스트가 모두 통과했을 때만 병합합니다. 둘 중 하나라도 검사에 실패하면 아무것도 라이브되지 않습니다. 저는 왜 자동화가 스스로의 작업을 확인하게 하는지에 대해 독립 감사(the independent audit)에서 글을 썼습니다.

단계 11: 모두가 읽기 쉽게 만들기

작은 픽셀의 텍스트는 멋져 보이지만 읽기가 불가능합니다. 라벨에는 크고 명확한 글꼴(저는 저시력을 위해 설계된 Atkinson Hyperlegible을 사용합니다)을 사용하고, 대비를 높이며, 누군가 확대할 때 더 작은 라벨이 쌓여서 문제가 생기는 것을 방지하기 위해 숨기세요. 공유하기 전에 휴대폰에서 테스트하세요.

처음에는 무엇이 잘못되었나요

저에게는 세 가지 문제점이 있었고, 여러분은 이를 건너뛰셔도 됩니다.

• 마을이 성장하자 라벨들이 겹쳤습니다. 확대했을 때만 부서 이름을 표시하는 것으로 해결했습니다.
• 제 첫 번째 버전에서는 무역 작업(trading work)이 주거 지구로 들어갈 수 있었습니다. 각 팀의 흐름에 대해 별도의 구역과 색상을 지정하여 그림을 사실적으로 만들었습니다.
• 제가 예약한 작업은 창 없이 실행되지만, 시작하는 모든 git 명령어는 자체 검은색 콘솔 상자를 띄웠습니다. Windows에서는 Python의 subprocess 모듈에서 CREATE_NO_WINDOW 플래그를 사용하여 해당 명령어를 시작해야 합니다. 그렇지 않으면 깜빡이는 창으로 화면이 가득 찰 것입니다.

이것을 구축하는 데 JavaScript를 알아야 하나요?

아닙니다. 저는 독학으로 했고 AI 도구의 도움을 받아 만들었습니다. 코드를 복사하고, 실행하고, 오류가 발생했을 때 오류 메시지를 읽고 그 오류에 대해 도움을 요청할 수 있어야 합니다. 위의 캔버스 드로잉이 필요한 유일한 JavaScript입니다.

자동화 내용을 공개해도 안전한가요?

네, 만약 공개 버전이 자체 데이터 파일을 갖게 된다면 안전합니다. 절대로 공개 페이지를 개인 데이터에 직접 연결하지 마세요. 이름, 요청 세부 정보, 정확한 금액 수치를 제거하는 make_public과 같은 함수를 만들고, 게시하기 전에 항상 그 출력을 확인하세요.

비용 없이 구축할 수 있나요?

네, 가능합니다. Python, Flask, 브라우저 캔버스(canvas), GitHub Pages, Windows Task Scheduler 모두 무료입니다. 마을에 AI 비서도 원한다면, 토큰 요금 없이 집에서 실행할 수 있습니다. 자세한 내용은 자신만의 로컬 AI 비서 구축 방법을 참고하세요.

게임 엔진을 사용하지 않는 이유는 무엇인가요?

사용할 수는 있지만, 게임 엔진은 무언가를 보기 전에 배워야 할 것이 너무 많습니다. 캔버스가 있는 단일 HTML 페이지는 어디든 로드할 수 있고, 무료로 호스팅할 수 있으며, AI 비서가 변경하는 것을 도와주기 쉽습니다. 간단하게 시작하고, 그것으로 더 이상 부족해질 때만 엔진을 사용하세요.

작게 시작하세요

첫날부터 열한 단계가 필요하지 않습니다. 실제 로그 파일에서 작동하는 건물 하나와 걸어 다니는 사람 한 명만 만드세요. 자신의 자동화 기능이 화면을 가로지르는 것을 처음 볼 때, 나머지 부분을 만들고 싶어질 것입니다.

완성된 마을 보기 (실시간) ↗

만약 자신만의 마을을 구축한다면 보여주시면 좋겠습니다. 제 전체 버전은 garystow.co.uk/village에서 실시간으로 실행되며, 저는 마케터를 위한 실용적인 AI에 대해 garystow.co.uk에서 글을 쓰고 있습니다.