AI 에이전트가 여론을 예측한다고? MiroFish로 시작하는 스웜 인텔리전스

최근 개인적으로 멀티 에이전트(Multi-Agent) 관련 프로젝트들을 이것저것 찾아보다가 "오, 이건 좀 재밌는데?" 하고 시선이 멈춘 게 바로 MiroFish 입니다.

한마디로, 가상 세계에 수천 개의 AI 에이전트를 풀어놓고 자유롭게 상호작용하게 만들어서 여론의 흐름이나 트렌드를 예측하는 오픈소스 엔진입니다. 게다가 단순한 PoC(개념 증명) 수준이 아니라, 실제로 로컬에 배포(Deploy)해서 돌려볼 수 있습니다. 커밋 수도 220개가 넘고, Docker도 지원하며, 공식 웹사이트에 데모까지 준비되어 있어서 "제대로 굴러가는 프로덕트"라는 느낌을 줍니다.

이번에 직접 세팅하고 돌려보면서 겪은 과정과 중간에 피눈물 흘렸던 삽질 포인트들을 공유해보려고 합니다.

MiroFish란? — "하이파이(High-Fidelity) 디지털 평행 세계"를 만드는 엔진

MiroFish는 샨다 그룹(Shanda Group)의 지원을 받아 개발 중인 스웜 인텔리전스(군집 지능) 기반의 AI 예측 엔진입니다. 대략적인 메커니즘은 이렇습니다:

1. 시드 데이터(뉴스 기사, 정책 초안, 소설 텍스트 등)를 주입한다.
2. 텍스트에서 지식 그래프(Knowledge Graph)를 자동 구축한다.
3. 그래프 구조를 바탕으로 독립적인 페르소나, 기억, 행동 로직을 가진 에이전트를 대량으로 생성한다.
4. 가상 공간에서 에이전트끼리 자유롭게 인터랙션하며 사회적 움직임을 시뮬레이션한다.
5. ReportAgent가 최종 상태를 분석하여 구조화된 예측 리포트를 출력한다.

요컨대 "디지털 평행 세계"를 만들고, 그 안에서 무슨 일이 일어나는지 관찰하는 어프로치입니다.

공식 웹사이트 데모에서는 대학 내 여론 시뮬레이션이나 중국 고전문학 '홍루몽'의 유실된 결말 예측 등 꽤 유니크한 유즈케이스를 소개하고 있습니다.

📎 공식 웹사이트: mirofish.ai

셋업: 가장 빠르게 돌려보기

배포 방법은 소스코드와 Docker, 이렇게 두 가지가 있습니다. 상세한 방법은 공식 README의 '🚀 Quick Start' 섹션에 잘 정리되어 있으니, 여기서는 핵심만 짚고 넘어가겠습니다.

환경 요구사항

항목	요구사항
Node.js	v18 이상 (node -v 확인)
Python	3.11〜3.12 (python --version 확인)
uv	파이썬 패키지 매니저 (uv --version 확인)
LLM API	OpenAI SDK 호환 API (GPT, Claude, Qwen 등)
Zep Cloud	에이전트 장기 메모리 관리 (선택이지만 강력 권장)

주의⚠️:
공식 README에서는 Alibaba Cloud의 qwen-plus 모델을 추천하고 있습니다. LLM 토큰 소모량이 장난 아니기 때문에, 처음에는 40라운드 이하의 소규모 시뮬레이션부터 돌려보면서 간을 보는 것이 정신건강에 좋습니다.

소스코드 배포 (추천)

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env          # .env에 API 키 등 입력
npm run setup:all             # 프론트/백엔드 의존성 일괄 설치
npm run dev                   # 프론트(3000) + 백엔드(5001) 동시 띄우기

프론트엔드와 백엔드를 따로 띄우고 싶다면 npm run frontend / npm run backend를 쓰면 됩니다.

Docker 배포 (빠르게 맛보고 싶은 분들)

cp .env.example .env          # .env에 API 키 등 입력
docker compose up -d          # 포트 3000/5001로 서비스 기동

활용법: 뭘 할 수 있을까?

세팅이 끝났으면 브라우저에서 http://localhost:3000으로 접속해 다음 흐름대로 사용합니다.

1. 시드 데이터 임포트 — 텍스트, 이벤트 설명, 데이터 리포트 등을 주입
2. 시뮬레이션 변수 설정 — 소셜 구조, 인터랙션 규칙, 에이전트 수 등 세팅
3. 시뮬레이션 실행 — 지식 그래프 구축 → 에이전트 생성 → 다수 라운드의 인터랙션 자동 진행
4. 예측 리포트 확인 — 트렌드 추이, 감정 분포, 행동 클러스터링 등 출력 결과물 확인
5. 인터랙티브 파고들기 — 특정 에이전트나 ReportAgent와 직접 채팅하며 심층 분석

개발자 입장에서 매력적인 점은, 노코드(No-code)로도 시뮬레이션을 돌려볼 수 있지만 본인만의 이벤트 처리 처리 로직을 심거나 에이전트 파라미터를 세밀하게 튜닝하고, 결과를 콜백(Callback) API로 받아보는 등 입맛대로 확장이 가능하다는 것입니다.

아키텍처 개요: 뒷단에선 뭐가 돌아갈까

엔진의 내부 플로우를 러프하게 정리하면 이렇습니다:

텍스트 입력
  ↓
① 지식 그래프 구축 (GraphRAG)
  — 엔티티(Entity)와 릴레이션(Relation) 자동 추출
  ↓
② 환경 & 에이전트 생성
  — 그래프 구조에서 페르소나 및 행동 규칙 생성
  ↓
③ 멀티 에이전트 시뮬레이션
  — 병렬 환경에서 에이전트들이 서로 인터랙션하며 메모리 업데이트
  ↓
④ 리포트 생성
  — ReportAgent가 분석 후 구조화된 리포트 출력

단순히 LLM 하나 덜렁 띄워놓고 "예측해줘"라고 던지는 것과는 접근 방식이 근본적으로 다릅니다. 지식 그래프 주도(Knowledge Graph-driven) × 멀티 에이전트 협업 패턴으로 예측을 수행하거든요. 내부 시뮬레이션 엔진으로는 OASIS(CAMEL-AI)가 채택되어 있습니다.

셋업 중 마주친 삽질 포인트와 해결책

실무 뛰는 분들에겐 여기서부터가 진짜 알짜배기 파트 아닐까 싶네요. 제가 직접 세팅하면서 지뢰 밟았던 부분들을 정리해 둡니다.

1. uv 명령어를 찾을 수 없음

'uv' is not recognized as an internal or external command

Conda 환경에 uv를 깔아뒀는데, npm run dev로 백엔드를 띄우면 Conda 환경이 activate되지 않아 패스가 꼬이는 전형적인 케이스입니다.

해결책: 프론트엔드와 백엔드를 따로따로 띄우는 게 제일 확실합니다.

# 백엔드 (Conda 환경을 거쳐서 띄우기)
cd backend
conda run -n your_env_name python run.py

# 프론트엔드 (다른 터미널 창에서)
cd frontend
npm run dev

아니면 그냥 쿨하게 uv를 글로벌로 설치해 버리는 것도 방법입니다:

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Rollup 네이티브 모듈 에러 (Windows 환경)

Error: Cannot find module @rollup/rollup-win32-x64-msvc

윈도우에서 npm의 optional dependencies가 제대로 안 깔려서 생기는 뻔한 에러입니다. 수동으로 박아주면 그만이죠.

cd frontend
npm i -D @rollup/rollup-win32-x64-msvc

그래도 안 먹힌다면 node_modules랑 package-lock.json 밀어버리고 클린 인스톨 하세요. Node.js는 웬만하면 18 LTS나 20 LTS 버전을 추천합니다.

3. API 키 관련 소소한 팁

• API 키는 무조건 .env 파일에 짱박아두기. 소스코드에 하드코딩하는 건 금물입니다.
• 리포지토리 안에 test_api_key.py / test_bailian_api_key.py 같은 테스트 스크립트가 동봉되어 있으니 접속 테스트할 때 요긴하게 써먹으세요.

python test_bailian_api_key.py

운영 시 주의할 점

항목	포인트
API 비용	대규모 시뮬레이션은 LLM 호출 횟수가 기하급수적으로 늘어납니다. 사전에 견적을 파악해 두는 게 필수입니다.
메모리 영속화	Zep Cloud를 연동하면 에이전트들의 장기 기억(Long-term Memory) 성능이 압도적으로 좋아집니다.
버전 호환성	파이썬과 Node 버전이 요구사항에 안 맞으면 의존성 에러로 멘붕오기 십상입니다. nvm / pyenv 등의 버저닝 툴 활용을 권장합니다.
결과 해석	시뮬레이션 결과는 어디까지나 '확률 분포'이지, '절대적인 미래 예측'이 아닙니다. 기존 정통 모델과 교차 검증하는 것을 추천합니다.

마무리: 단순한 '개념'이 아니라 진짜 '돌아가는 프로덕트'

솔직히 말해서 처음에 "멀티 에이전트로 미래를 예측한다"는 말을 들었을 땐 "또 입만 산 컨셉트 프로젝트 아냐?" 하고 의심했습니다. 그런데 막상 배포해서 돌려보니까 지식 그래프 빌드부터 시작해서 에이전트 생성, 시뮬레이션 과정, 마지막 리포트 출력까지 말끔하게 하나의 파이프라인으로 연결되어 있더군요.

• 개발 페이즈 → 소스코드 배포로 핫 리로드(Hot Reload) 및 디버깅 쾌적화
• 데모 / 프로덕션 → Docker 원콤으로 환경 격리 & 안정적인 가동
• 확장성 → 커스텀 로직 주입이나 외부 시스템 연동까지 자유로움

멀티 에이전트 응용 분야에 관심 있는 분들이라면 꼭 한 번쯤 찍먹해 볼 만한 가치가 있습니다. 특히 시뮬레이션 계열의 유즈케이스(여론 시나리오 분석, 복잡계 다이내믹스 예측 등)를 찾고 계신 분들에게는 찰떡같은 프로젝트라 봅니다.

직접 돌려본 후기나 "나는 이런 제정신 아닌 유즈케이스로 써봤다" 싶은 썰이 있다면 댓글이나 SNS로 많이 공유해 주세요! 같이 삽질의 늪에 빠져봅시다 🐟

---

참고 링크:

• MiroFish GitHub
• MiroFish 공식 웹사이트
• OASIS — CAMEL-AI 시뮬레이션 엔진
• Zep Cloud — 에이전트 메모리 관리