README.md

Virtual AI Agent Company

자율 멀티 에이전트 협업 플랫폼 — 사람은 결정적 순간에만 개입하고, 에이전트들이 자율적으로 협업하여 업무를 수행한다.

여러 AI 에이전트(codex, claude, gemini)를 회사 조직처럼 운영하는 플랫폼이다. 개발뿐 아니라 재무/회계, 사업기획, 법무, HR 등 어떤 업무 도메인이든 부서를 구성하면 에이전트들이 자율 협업한다.

왜 이 프로젝트를 만들었는가

• 단일 AI 에이전트로는 복잡한 업무에서 역할 분리와 품질 보증이 어렵다.
• 전문 에이전트들이 부서별로 분업하여 계획→실행→검증을 자율적으로 수행하면, 단일 에이전트보다 높은 품질을 낸다.
• 사람은 방향 설정과 결정적 순간의 승인만 하고, 나머지는 에이전트 조직이 자율 처리한다.
• 장기적으로 오픈소스 모델 기반 도메인 특화 자체 모델을 구축하여 비용을 절감하고 회사 고유 자산을 확보한다.

장기 비전

상세: 24개월 로드맵

1. 자율 에이전트 협업 — 에이전트 조직이 프로젝트 단위로 업무를 자율 수행, 사람은 결정적 순간에만 개입
2. 멀티 도메인 — 개발, 재무/회계, 사업기획, 법무 등 어떤 도메인이든 부서를 구성하면 동작
3. 자체 모델 = 회사 자산 — Opus/Codex로 시작하되, 데이터 플라이휠로 도메인 특화 자체 모델 구축
4. Web Dashboard 주력 — 멀티 프로젝트 × 멀티 부서를 웹에서 관제, CLI/IDE는 보조

현재 프로젝트 내용

새 아키텍처 (피벗 완료)

• 멀티 프로젝트 × 멀티 부서 × 멀티 에이전트 구조
  • Project → Department → Agent 3-tier 모델
  • 부서별 독립 워킹디렉터리, 부서 간 크로스 컨텍스트 공유 (EventBus)
  • 에이전트 자율 제안 → 승인 → 실행 플로우
• Web Dashboard (주력 인터페이스)
  • 프로젝트/부서/태스크 실시간 모니터링
  • 승인 게이트 UI, 에이전트 협업 흐름 시각화
  • 성능/비용 대시보드
• 자율 에이전트 실행
  • 부서별 독립 에이전트 실행 엔진
  • PLAN→WORK→REVIEW 사이클 자율 수행
  • 실패 시 자동 재시도, 에스컬레이션, 크로스 부서 협업
• 학습 시스템
  • 에피소드 기반 학습 (태스크 완료 → 패턴 추출 → 행동 최적화)
  • 에이전트별 컨텍스트 메모리, 인사이트 축적
• RAG 기반 지식 관리
  • 도메인별 지식 검색 (knowledge-base + ChromaDB + BM25)
  • 역할×단계별 36가지 표준 쿼리 패턴

레거시 (호환 유지)

• 단일 워크스페이스 + Chief→Lead→Member 고정 계층 모드
• /api/runtime/* 레거시 API (Strangler Fig 패턴으로 점진 교체)

현재 운영 방향 (2026-03-16)

자율성 단계적 확대

단계	사람 역할	에이전트 자율 범위
Level 0: 도구	매 단계 승인	지시받은 작업만 수행
Level 1: 어시스턴트	최종 결과 승인	계획→구현→검증 자율 수행
Level 2: 자율 팀	위험 작업만 승인	대부분 자율, 위험 시만 에스컬레이션
Level 3: 자율 조직	방향 설정 + 예외	태스크 발견→할당→실행→검증까지 자율
Level 4: 자기 진화	전략 결정만	스스로 약점 파악→학습 데이터 생성→자기 개선

멀티 도메인 확장 전략

플랫폼의 핵심은 "에이전트 협업 오케스트레이션"이므로 도메인에 관계없이 적용 가능하다. 첫 진입은 개발 도메인, 이후 재무/회계, 사업기획, 법무 등으로 확장한다.

자체 모델 전략

초반에는 Opus/Codex 같은 외부 모델로 시작하되, 데이터 플라이휠을 돌려 오픈소스 모델 기반 **도메인 특화 자체 모델(회사 자산)**로 점진 전환한다.

시스템 구성

• web/: React/Vite 기반 운영 UI
• mcp-server/: Rust 기반 Runtime/API/WebSocket 서버
• knowledge-base/: 조직/역할/운영/기술 문서(SoT)
• rag-engine/: knowledge-base 하이브리드 검색 파이프라인
• designsystem/: Material 3 디자인 토큰

로드맵

피벗 로드맵 (Phase 0~7 완료)

상세: roadmap/pivot-roadmap.md

• Phase 0~7 핵심 구현 완료 (데이터 모델 → API → 실행 엔진 → 크로스 부서 → 제안 시스템 → 대시보드 → 학습)

24개월 장기 로드맵

상세: external-to-own-llm-24month-roadmap.md

• Phase A (0~3개월): Web 기반 자율 에이전트 플랫폼 구축
• Phase B (3~6개월): 벤치마크 + 데이터 플라이휠 + 자율 팀
• Phase C (6~9개월): 검색 고도화 + 외부 연동 + 자율 조직화
• Phase D (9~18개월): 자체 모델 구축 + 서빙 — 회사 자산화
• Phase E (18~24개월): 자기 진화 + 멀티 도메인 확장

빠른 실행

1) API 서버 실행

cd mcp-server
cargo run

2) Web 실행

cd web
npm install
npm run dev

3) API + Web 동시 실행(개발)

cd mcp-server
cargo run -- --with-web

4) 로컬 배포 번들 생성/실행

# 번들 생성 (rag-engine/data 제외)
./scripts/package-local.sh

# 번들 실행 (브라우저 자동 오픈)
./dist/agent-company-local/bin/agent-company

다른 컴퓨터에서 npm 방식으로 설치해 agent-company 명령만 사용하려면:

# A 컴퓨터: 번들 생성 후 dist/agent-company-local.tar.gz 전달
./scripts/package-local.sh

# C 컴퓨터: tar.gz 압축 해제 후 패키지 설치
npm install -g /path/to/agent-company-local

# C 컴퓨터: 어디서든 실행
agent-company start

workdir는 웹에서 생성/초기화하고, /api/runtime/init 시점에 해당 workdir의 RAG 인덱스가 백그라운드로 자동 생성된다.

A/B 벤치마크 자동화

Baseline vs Candidate를 동일 snapshot/task/timeout으로 반복 실행하려면:

python3 scripts/benchmark-runtime-ab.py \
  --dataset scripts/benchmark-tasks.sample.json \
  --baseline-cmd "./scripts/agent-company run-task --mode baseline --workdir {worktree} --instruction '{instruction}' --timeout {timeout_sec}" \
  --candidate-cmd "./scripts/agent-company run-task --mode candidate --workdir {worktree} --instruction '{instruction}' --timeout {timeout_sec}" \
  --runs-per-task 3 \
  --regression-gate \
  --gate-min-runs 0 \
  --gate-category-weights "product-feature=1.0,bugfix=1.2,refactor=0.9,operations-policy=0.8"

• 결과물: .agentCompany/benchmarks/ab-<timestamp>/summary.json, summary.md, runs.ndjson, logs/*
• KPI: 성공률, First-pass 성공률, Median Time-to-Green, Blocked Rate(by reason), 제품 코드 변경 비율, 사용자 개입 횟수
• 회귀 게이트: regressionGate 섹션에 기준/체크 결과를 기록하고, --fail-on-regression 사용 시 실패 코드를 반환한다.

야간 자동 실행(회귀 게이트 포함):

export RUNTIME_BENCH_BASELINE_CMD="./scripts/agent-company run-task --mode baseline --workdir {worktree} --instruction '{instruction}' --timeout {timeout_sec}"
export RUNTIME_BENCH_CANDIDATE_CMD="./scripts/agent-company run-task --mode candidate --workdir {worktree} --instruction '{instruction}' --timeout {timeout_sec}"
./scripts/nightly-runtime-benchmark.sh

GitHub Actions(.github/workflows/runtime-nightly-benchmark.yml)를 사용하면 매일 UTC 18:00에 실행된다. 아래 secrets를 저장해야 한다.

• RUNTIME_BENCH_BASELINE_CMD
• RUNTIME_BENCH_CANDIDATE_CMD

agent-company run-task는 directive draft → submit → 상태 폴링을 자동으로 수행한다. 기본 workdir는 현재 디렉터리이며 --workdir로 명시할 수 있다.

Documentation

대상	위치	설명
사람 (개발자/운영자)	docs/	아키텍처 가이드, API 레퍼런스, Mermaid 다이어그램
AI 에이전트	knowledge-base/	RAG 인덱싱된 운영 지식 (에이전트 전용)
운영 헌장	AGENTS.md	프로젝트 규칙 단일 SoT

핵심 문서

• 운영 헌장: AGENTS.md
• 로드맵: knowledge-base/technical/roadmap.md
• 아키텍처: docs/architecture/overview.md
• API 레퍼런스: docs/backend/api-reference.md
• 빠른 시작: docs/operations/getting-started.md
• 프로그램 구성 SoT: knowledge-base/technical/program-composition.md
• CEO 지시 체계: knowledge-base/operations/ceo-command-orchestration.md
• 역할 스케일링: knowledge-base/governance/approval-rules/role-capacity-scaling.md
• API 계약: knowledge-base/technical/api-contract.md
• 교차 workdir 협업 지침: knowledge-base/technical/cross-workdir-collaboration.md