LiXin97/agora-lab

LLM 연구소를 위한 멀티 에이전트 연구 오케스트레이션 (Multi-Agent Research Orchestration)

적대적 연구 회의 (Adversarial lab meetings), 논문 리뷰 워크플로우 (paper-review workflows), 선택 가능한 픽셀 아트 Lab View를 갖춘 대시보드 중심의 웹 워크벤치 (web workbench), 그리고 감사 가능한 마크다운 (Markdown) 워크플로우.

Claude / Codex / Copilot / Gemini · TypeScript · pnpm monorepo · Supervisor / Students / Research Staff / Paper Reviewers

빠른 시작 (Quick Start) · 웹 대시보드 (Web Dashboard) · 튜토리얼 (Tutorial) · 예제 (Examples) · 아키텍처 (Architecture)

Agora Lab은 Supervisor (관리자), Student (학생), Research Staff (연구원), Paper Reviewer (논문 리뷰어) LLM 에이전트들을 감사 가능한 AI 연구소로 오케스트레이션하기 위한 TypeScript 프레임워크입니다. 핵심 품질 메커니즘은 2단계 적대적 루프 (two-stage adversarial loop)입니다. 구조화된 연구 회의를 통해 토론으로 방향을 정교화하고, 이후 전담 논문 리뷰 단계를 통해 제출 준비 상태를 검증합니다. 모든 상호작용은 마크다운 (Markdown) 파일, 공유 작업 보드 (task board), 에이전트별 워크스페이스 (workspaces)를 통해 흐르므로, 첫 문헌 조사부터 최종 논문까지의 연구 과정을 검사 가능한 상태로 유지할 수 있습니다.

이 프로젝트는 4개의 패키지로 구성된 pnpm monorepo 구조로 되어 있습니다:

패키지	설명
packages/core	핵심 도메인 로직 — 칸반 (kanban), 회의 (meetings), 에이전트 (agents), 설정 (config), 템플릿 (templates)
packages/cli	Commander.js로 구축된 agora CLI — init, start, stop, agent/meeting/kanban 하위 명령
packages/server	WebSocket 서버 — chokidar를 통해 .agora/의 파일 변경을 감시하고, 이벤트를 브로드캐스트하며, 클라이언트 명령을 처리함
packages/web	대시보드 중심 웹 앱 — 에이전트/칸반/메시지를 위한 React 패널 및 보조적인 Canvas 기반의 Lab View

[2026-04-16] 대시보드 업데이트 — 기본적으로 분석가 워크벤치 셸 (analyst workbench shell)을 제공하며, 기존의 픽셀 랩 (pixel lab)은 보조적인 Lab View로 유지됨
[2026-04-10] 오픈 소스 출시 — Agora Lab이 이제 GitHub에 공개되었습니다.

graph TD
SUP["Supervisor<br/>연구 방향 할당"]
SUP --> SA["Student A<br/>방향 1"]
...

아래 예제들은 agora CLI가 사용자의 PATH에 설정되어 있다고 가정합니다. 로컬 클론에서 실행할 경우, packages/cli를 직접 전역(globally)으로 링크하거나 agora를 교체하여 사용할 수 있습니다.

with node /path/to/agora-lab/packages/cli/dist/index.js

.

# 1. Clone and build
git clone https://github.com/LiXin97/agora-lab.git
cd agora-lab
...

이 작업은 프로젝트 내에 .agora/ 디렉토리를 생성합니다 (git init이 .git/을 생성하는 것과 유사함):

your-project/
├── .agora/
│ ├── lab.yaml # Lab 설정 (git-committable)
...

대시보드 우선형 웹 UI (dashboard-first web UI)를 실행합니다:

agora dev # development: websocket server + Vite frontend
agora web # production-style: serves built frontend from packages/web/dist

터미널에 출력된 URL을 여세요. agora dev는 요청된 포트에서 실시간 서버 (realtime server)를 시작하고, 두 번째 로컬 포트에서 Vite 프론트엔드 (Vite frontend)를 시작합니다.

기본적인 경험은 분석가 워크벤치 (Analyst Workbench) 형태입니다:

좌측— 에이전트 명단 (agent roster) 및 상태 요약
중앙— 추가 / 이동 / 할당을 위한 칸반 워크벤치 (kanban workbench)
우측— 최근 메시지 및 회의 제어 (meeting controls)
하단— 결정 로그 (decision log) 및 시스템 상태 (system health)

두 뷰 (views) 상단에는 **상단 앱 크롬 (top app chrome)**이 위치하며 다음을 제공합니다:

• Lab 식별 정보 및 연결 상태 표시기 (connection health indicator)
• Dashboard / Lab View 탭을 통한 기본 화면 전환
• System / Light / Dark 테마 선택기

대화형 기능 (Interactive features):

단축키	동작
Dashboard	작업 추가, 상태 이동, 에이전트 할당, 회의 생성/진행, 결정 및 상태 검사
...
K 또는 화이트보드 (Lab View)	칸반 오버레이 (kanban overlay) 열기
M 또는 회의 테이블 (Lab View)	회의 오버레이 (meeting overlay) 열기
에이전트 클릭 (Lab View)	에이전트 사이드바 (agent sidebar) 열기
드래그 / 스크롤 (Lab View)	카메라 팬 및 줌 (Pan and zoom)
툴바 R (Lab View)	카메라를 중앙으로 리셋
Escape	오버레이 닫기 및 선택 해제

Lab View는 **저동작 모니터링 화면 (low-motion monitoring surface)**입니다. 에이전트들은 고정된 위치를 차지하며 연구(lab)가 진행됨에 따라 자신의 상태(작업 중 / 회의 중 / 검토 중)를 업데이트하지만, 지속적인 움직임 애니메이션이 일반적인 경험은 아닙니다. 캔버스 (canvas)는 더 이상 주요 제어 화면이 아닙니다.

전체 튜토리얼— 전체 연구 세션의 에이전트 출력 예시를 포함한 엔드 투 엔드 (End-to-end) 가이드.

출력 예시(Example Outputs)—연구 세션에서 생성된 샘플 아티팩트(artifacts), 연구진의 판단, 회의, 그리고 논문 리뷰(paper-review) 단계를 살펴보세요.

기능 (Capability)	Agora Lab	MetaGPT	AutoGen	CrewAI	AI Scientist	Co-Scientist
적대적 N x N 리뷰 (Adversarial N x N Review)	구조화된 교차 비판 (Structured cross-critique)	--	--	--	자기 리뷰 (Self-review) 전용	Elo 랭킹
회의 프로토콜 (Meeting Protocol)	5단계 구조화된 방식	--	라운드 로빈 채팅 (Round-robin chat)	--	--	토너먼트 (Tournament)
연구 파이프라인 (Research Pipeline)	7단계 연구 루프 + 논문 리뷰 게이트	SOP 기반 워크플로우	유연한 체인 (Flexible chains)	태스크 파이프라인	엔드 투 엔드 (End-to-end) 논문 작성	다단계 추론 (Multi-step reasoning)
멀티 백엔드 (Multi-Backend)	Claude / Codex / Copilot / Gemini	OpenAI 중심	멀티 모델 (Multi-model)	LLM 불가지론적 (LLM-agnostic)	OpenAI	Gemini
웹 대시보드 (Web Dashboard)	대시보드 우선 워크벤치 + 픽셀 랩 뷰 (pixel Lab View)	--	--	--	--	클라우드 UI
워크스페이스 격리 (Workspace Isolation)	훅(Hook)으로 강제된 에이전트별 격리	공유 메모리 (Shared memory)	공유 상태 (Shared state)	공유 상태 (Shared state)	단일 에이전트	클라우드 관리형
파일 기반 감사 추적 (File-Based Audit Trail)	전체 마크다운(Markdown) 추적	코드 파일	로그 (Logs)	로그 (Logs)	LaTeX 출력물	내부적
스택 (Stack)	TypeScript + React + Canvas 2D	Python	Python	Python	Python	클라우드 서비스
역할 기반 액세스 제어 (Role-Based Access)	Supervisor / Student / Staff / Reviewer RBAC	역할 할당	에이전트 역할	역할 위임	--	--

Supervisor가 연구 방향을 할당함
|
Students가 독립적으로 탐색함 (트리 탐색)
...

역할 (Role)	책임 (Responsibility)	백엔드 + 페르소나 (Backend + Persona)
Supervisor	방향 할당, 진행 상황 검토, 연구 회의 주관, 작업의 논문 리뷰 단계 진입 결정	지원되는 모든 백엔드; 기본값은 Claude Code. 페르소나는 최상위 PI (Principal Investigator) / 연구실 구축자 프로필.
PhD Student	독립적 연구: 문헌 조사, 가설 설정, 실험, 논문 초안 작성	지원되는 모든 백엔드; 기본값은 Claude Code. 페르소나는 MBTI, 배경, 주목할 만한 성과를 갖춘 엘리트 펠로우십 급 연구자.
Research Staff	정기적인 연구 루프 (research-loop) 회의 참여, 범위/증거/주장의 스트레스 테스트, 연구실 수준의 과학적 판단 제공	지원되는 모든 백엔드; 기본값은 Claude Code. 페르소나는 강력한 멘토링 및 평가 본능을 가진 시니어 포스트닥 (postdoc) 또는 주니어 교수 프로필.
Paper Reviewer	참신함 (novelty), 엄밀성 (rigor), 증거, 제출 준비 상태에 집중한 전용 논문 리뷰 라운드 수행	지원되는 모든 백엔드; 기본값은 Claude Code. 페르소나는 명확한 리뷰 관점과 업적을 가진 최상위 비판적 평가자.

대시보드 우선 웹 UI (Dashboard-first web UI): 에이전트를 위한 분석가 워크벤치, 칸반 (kanban), 회의, 최근 메시지, 결정 사항 및 시스템 상태 관리
보조 실험실 뷰 (Secondary Lab View): 공간 탐색 및 오버레이를 위해 기존의 픽셀 아트 캔버스 유지
동적 스케일링 (Dynamic scaling): 런타임(runtime) 중에 원하는 수의 학생, 연구진, 논문 심사위원을 추가 가능
멀티 런타임 (Multi-runtime): 모든 역할은 Claude Code, Codex, Copilot 또는 Gemini에서 실행 가능
페르소나 다양성 (Persona diversity): 각 에이전트는 가시적인 MBTI, 엘리트 배경, 주목할 만한 성과 및 역할별 연구 관점을 보유
적대적 연구 회의 (Adversarial research meetings): 학생 간 교차 비판(cross-critique)과 연구진의 판단이 포함된 5단계 프로토콜
별도의 논문 심사 게이트 (Separate paper review gate): 제출 전 심사 라운드를 위한 전용 논문 심사 워크플로
트리 탐색 (Tree search): 여러 학생이 동시에 서로 다른 방향을 탐색하며, 감독자(supervisor)가 가지치기(pruning) 및 병합(merging) 수행
파일 기반 통신 (File-based communication): 모든 에이전트 상호작용은 구조화된 마크다운 (Markdown) 파일을 통해 이루어짐
연구 작업 보드 (Research task board): 동시성 안전(concurrency-safe) 파일 작업을 지원하는 마크다운 기반 작업 추적
워크스페이스 격리 (Workspace isolation): 훅(Hooks)을 통해 에이전트별 워크스페이스 경계 강제
역할 템플릿 (Role templates, TS-native): agora init 및 agora agent add를 실행하고, 에이전트별로 CLAUDE.md를 작성. TypeScript 시대의 마크다운 템플릿에서 프롬프트를 가져오며, 셸 스텁(shell stubs)은 사용하지 않음; 각 템플릿에는 세션 시작 체크리스트와 현재 CLI 명령어가 포함됨
양방향 웹소켓 (Bidirectional WebSocket): 브라우저가 서버로 명령(칸반, 회의)을 전송하고, 서버는 파일을 감시하며 업데이트를 브로드캐스트(broadcast)함
런타임 자동화 (Runtime automation, L1+L2): 장시간 실행되는 와치독(watchdog)이 인간의 폴링(polling) 없이 유휴(idle) 상태인 에이전트를 다시 업무로 복귀시킴

• 시그니처 차이 주입 (Signature-diff injection): 에이전트의 편지함/작업/회의 상태가 변경되면, 와치독이 해당 에이전트의 tmux 창으로 새로운 프롬프트를 전송
• L1 유휴 하트비트 (L1 idle heartbeat): 이전에 활성화되었던 에이전트가 하트비트 임계값(기본값 20분)을 넘겨 침묵할 경우, 세션 시작 체크리스트를 다시 실행하도록 재프롬프트(re-prompt)를 보냄 — "이벤트 없음 ⇒ 주입 없음 ⇒ 데드락(deadlock)" 함정을 방지
• L2 감독자 오케스트레이터 (L2 supervisor orchestrator): 매 사이클마다 런타임은 글로벌 뷰를 집계하며, 정체된 in_progress

tasks, 활발한 작업이 있는 Review 컬럼, 정체된 회의, 블로킹 체인 휴리스틱 (blocking-chain heuristic))을 포함하는 빈 컬럼을 집계하고, 액션 정책(수행(act), 재할당(reassign), 또는 상태 노트 작성(write a status note) — 절대 조용히 유휴 상태로 있지 않음)과 함께 감독관을 대상으로 하는 프롬프트를 오버레이합니다. 중복 제거(Dedup)는 노이즈를 방지하기 위해 30분 단위의 윈도우(window)로 버킷팅됩니다 - Pane-busy guard: 대상인 Claude Code TUI가 추론(inference) 중인 동안에는 주입(injection)이 건너뛰어지므로, 프롬프트가 길을 잃은 붙여넣기 블록(stray paste blocks)으로 쌓이지 않습니다.

회의는 정기적인 연구 루프를 위한 핵심적인 적대적 메커니즘 (adversarial mechanism)입니다 — 실제 연구실 그룹 회의를 모델로 합니다:

PREPARE (준비): 학생들은 perspectives/에 관점(perspectives)을 작성하고, 연구진(research staff)은 judgments/에 판단(judgments)을 작성합니다.

CROSS-READ (교차 읽기): 모든 구성원이 모든 관점을 읽은 후 완료를 확인합니다.

CHALLENGE (도전): 학생들은 서로를 비판하며 (N x N), 연구진은 범위(scope), 증거(evidence), 포지셔닝(positioning)에 대해 더 넓은 과학적 판단을 적용합니다.

RESPOND (응답): 각 참가자는 자신의 작업을 대상으로 한 비판에 대응합니다.

DECISION (결정): 감독관이 모든 내용을 읽고 결정합니다: CONTINUE (계속) | PIVOT (피벗) | MERGE (병합) | SPLIT (분할)

회의 트리거는 수동입니다. 자동적인 주기(cadence)는 없습니다. 감독관은 적대적 토론을 위한 충분한 자료가 축적되면 회의를 호출합니다 (agora meeting new 또는 대시보드의 Start Review Meeting).

회의 사이의 기간 동안, 연구실은 칸반(kanban) 할당 및 shared/messages/의 파일 메시지를 통해 이벤트 기반(event-driven)으로 운영됩니다. lab.yaml은 meeting.trigger: manual, min_participants, decision_maker를 기록하며, 참가자는 회의마다 학생과 연구진 중에서 선택됩니다. 논문 심사위원(Paper reviewers)은 절대 선택되지 않습니다 — 서버는 이들이 포함된 회의를 거부하며, 대시보드의 참가자 선택기(participant picker)에서 이들을 필터링합니다.

단계는 산출물(artifacts)이 존재할 때만 진행됩니다. PREPARE는 모든 참가자의 관점 파일(및 연구진의 경우 판단)을 요구합니다; CROSS_READ는 모든 참가자의 판단을 요구합니다; CHALLENGE는 최소 하나 이상의 비판을 요구합니다; RESPOND는 결정권자가 아닌 모든 참가자의 응답을 요구합니다. DECISION

is 종결(terminal)입니다.

논문 리뷰어(Paper reviewers)는 정기적인 연구실 루프(lab loop) 외부에 존재합니다: 그룹 미팅 없음, 학생/지도교수와의 교류 없음, 일반적인 칸반(kanban) 작업 할당 없음. 이들은 오직 지도교수가 자신들에게 배정하는 명시적인 리뷰 작업에 대해서만 행동합니다.

모든 리뷰어 작업은 제목/설명에 두 가지 필드를 반드시 포함해야 합니다 — 논문 포인터(paper pointer) 및 대상 컨퍼런스(target conference):

# 특정 논문
agora kanban add -a paper-reviewer-1 -p P2 \
-T "Review arxiv:2403.12345 | target: NeurIPS 2025 (main track)"
...

포인터나 대상 컨퍼런스 중 하나라도 누락된 작업은 사용할 수 없습니다 — 리뷰어가 작업을 가져가기 전에 설명을 수정하십시오.

각 리뷰어는 작업당 3단계 파이프라인(pipeline)을 실행합니다:

논문 찾기 (Locate the paper)— 주어진 arXiv ID / PDF를 가져오거나, 명시된 시간 범위 내에서 arXiv를 검색하여 해당 주제에 가장 관련성이 높은 단일 논문을 선택합니다.
대상 컨퍼런스 식별 (Identify the target conference)— 해당 컨퍼런스의 공식 리뷰어 지침(reviewer instructions)을 로드하고, 그 리뷰 양식(review form)을 글자 그대로 재현합니다 (헤딩, 필수 필드, 평점 척도(rating scale), 신뢰도 척도(confidence scale), 체크리스트 포함). 컨퍼런스 간에 임의로 생성하거나 병합된 필드를 사용하지 마십시오.
리뷰 작성 (Write the review)— 모든 필수 필드를 채웁니다. 출력물은 YAML 프런트매터(YAML frontmatter) (paper_arxiv_id, paper_title, target_conference, reviewer, completed_at)와 함께 shared/paper-reviews/<paperId>/rounds/R1/reviews/<reviewer-name>.md 경로로 저장됩니다.

각 라운드(round)별 지도교수 종합(Supervisor synthesis)은 여전히 케이스 디렉토리 아래의 supervisor-resolution.md로 전달됩니다. 초안이 제출 가능한 상태가 될 때까지 라운드를 반복합니다.

각 학생은 7단계 파이프라인을 따릅니다:

문헌 조사 (Literature survey) -> .agora/shared/artifacts/{name}/literature_{topic}.md

가설 (Hypothesis) -> .agora/shared/artifacts/{name}/hypothesis_{id}.md

실험 설계 (Experiment design) -> .agora/shared/artifacts/{name}/experiment_plan_{id}.md

구현 (Implementation) -> .agora/agents/{name}/workspace/ (개인용)

실행 (Execution) -> 워크스페이스(workspace)에서 실험 실행

분석 (Analysis) -> .agora/shared/artifacts/{name}/experiment_results_{id}.md

논문 작성 (Paper writing) -> .agora/shared/artifacts/{name}/paper_draft_{version}.md