142 lines
19 KiB
Markdown
142 lines
19 KiB
Markdown
# Multi-Agent Mux (MAM) Architecture & Orchestration Report
|
|
|
|
본 보고서는 **Multi-Agent Mux (MAM)** 프로젝트의 개발 과정과 아키텍처를 바탕으로, 다중 자율 AI 에이전트(Claude, Agy/Antigravity, Cline, Hermes 등)를 효과적으로 오케스트레이션하기 위해 필요한 핵심 기능과 이를 구현한 방법론, 그리고 각 기능이 부재할 경우 발생하는 장애 문제점을 구체적 예시와 함께 종합 정리한 문서입니다.
|
|
|
|
---
|
|
|
|
## 1. 개요 (Executive Summary)
|
|
|
|
현대 AI 에이전트 워크플로우는 세션 타임아웃, 프로세스 격리 부재, 터미널 뷰포트 잘림, 단일 에이전트의 자기 과신(Self-Confidence) 오류 등 다양한 문제점을 내포하고 있습니다.
|
|
|
|
**Multi-Agent Mux**는 **Tmux/Herdr** 프로세스 관리자와 **MQTT 메시징 백플레인**을 결합하여, 여러 LLM 에이전트가 안전하게 프로세스를 격리받고 비동기로 이벤트를 주고받으며 **Planner ➡️ Creator ➡️ Reviewers** 간의 자율 검증 및 교차 리뷰 루프를 수행할 수 있도록 설계된 고신뢰성 오케스트레이션 프레임워크입니다.
|
|
|
|
---
|
|
|
|
## 2. 코어 스킬 구성 명세 (Core Skills Inventory)
|
|
|
|
프레임워크의 모든 핵심 제어 로직은 `.agents/skills/` 하위의 독립된 스킬 모듈로 응집되어 있으며, 각 스킬의 기능은 다음과 같습니다.
|
|
|
|
* **`multi-agent-mux-create`**
|
|
* 지정된 작업 공간에 최적화된 명칭으로 독립된 에이전트 세션을 새로 구동하고, 초기 메타데이터를 원자적으로 등록합니다.
|
|
* 에이전트 구동 즉시 워크스페이스 맥락과 자신의 역할(Role)을 스스로 파악하도록 자동 온보딩 지시서 주입을 지원합니다.
|
|
* **`multi-agent-mux-resume`**
|
|
* 이전에 중지되거나 중단된 에이전트의 대화 식별자(UUID)를 디스크 및 레지스트리에서 추적하여 이전 문맥 그대로 세션을 복원합니다.
|
|
* 에이전트 기동 직후 필요한 권한 우회 및 복구 수락 대화상자를 백그라운드 키스트로크 주입으로 자동 처리합니다.
|
|
* **`multi-agent-mux-stop`**
|
|
* 에이전트 TUI 화면 뷰포트를 최종 스냅샷으로 보존하고 `Safe Exit Key` ➡️ `SIGTERM` ➡️ `SIGKILL` 다단계 수순으로 안전하게 정지시킵니다.
|
|
* 에이전트의 대화 파일(JSONL/DB)을 디스크에 영구 보존하여 추후 언제든지 재개(`status=stopped`)할 수 있도록 상태를 기록합니다.
|
|
* **`multi-agent-mux-status`**
|
|
* 실제 실행 중인 OS 프로세스 현황과 레지스트리 기록 간의 불일치(Drift) 및 동작 상태를 안전하게 즉시 표기합니다.
|
|
* 데이터베이스나 프로세스 상태 변경을 유발하지 않는 순수 읽기 전용(Read-only) 모드로 시스템의 정합성을 검증합니다.
|
|
* **`multi-agent-mux-monitor`**
|
|
* 백그라운드에서 지속 구동되어 죽은 세션 격하, 신규 세션 자동 등록, 디스크 로그와 UUID 동기화를 자동 화해(Reconciliation)합니다.
|
|
* 운영체제 Tmux/Herdr 런타임과 YAML 레지스트리 데이터 간의 괴리를 실시간으로 자동 복구합니다.
|
|
* **`multi-agent-mux-delegate-job`**
|
|
* 타 에이전트에게 비동기 태스크를 위임하고, MQTT 메시징 백플레인을 통해 실행 상태(`started` ➡️ `completed`/`error`)를 관찰합니다.
|
|
* 단일 작업 위임(`direct`)부터 에이전트 간 1:1 토론(`discuss`), 검증 루프(`loop`)까지 다양한 비동기 작업 위임 패턴을 처리합니다.
|
|
* **`multi-agent-mux-loop`**
|
|
* 설계(Planner) ➡️ 구현(Creator) ➡️ 교차 검수(Reviewers)로 이어지는 자율 개발 및 검증 순환 루프를 오케스트레이션합니다.
|
|
* 지정되거나 자동 수집된 모든 리뷰어의 만장일치 `[VERDICT: PASS]` 판정을 얻을 때까지 자율 교정 작업을 자동 반복합니다.
|
|
|
|
---
|
|
|
|
## 3. Multi-Agent Orchestration을 위한 핵심 기능 및 구현 방법 (부재 시 장애 예시 포함)
|
|
|
|
다중 에이전트 협업 환경을 구축하기 위해 필수적이었던 8가지 주요 기능과, 각 기능이 부재할 경우 발생하는 실제 장애 문제점 및 구체적인 구현 기법입니다.
|
|
|
|
### 🔑 1) 프로세스 및 실행 환경 격리 (Environment Isolation)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *인증 및 설정 파일 오염*: 서로 다른 에이전트(예: Claude와 Agy)가 동일한 기본 홈 디렉토리(`~/.gemini`, `~/.claude`)를 공유하면, 한 에이전트가 설정을 덮어쓰거나 로그인 세션을 건드려 상대방 에이전트의 인증이 갑자기 해제되는 장애가 발생합니다.
|
|
* *초기 대화상자 차단 패닉*: 예컨대 Agy 에이전트가 격리되지 않은 환경에서 구동될 경우 약관 동의(TOS)나 테마 설정 마법사 화면이 매번 출력되어 프롬프트 입력창이 상시 차단(Prompt Lockout)되는 현상이 일어납니다.
|
|
* **필요성**: 에이전트 간 설정 파일, 캐시, 세션 이름 및 환경 변수 충돌을 물리적으로 막아야 합니다.
|
|
* **구현 방법**:
|
|
* `herdr --session <name>` 명령을 활용해 에이전트 그룹마다 완전히 독립된 소켓과 서버 세션을 부여했습니다.
|
|
* 에이전트별로 워크스페이스 내에 임시 홈 디렉토리(`.mam/agent_homes/<UUID>`)를 프로비저닝하고 `HOME` 또는 `CLAUDE_CONFIG_DIR` 환경변수를 덮어씌워 완벽히 독립된 가상 홈 디렉토리를 제공했습니다.
|
|
|
|
### 🗃️ 2) 에이전트 관리를 위한 이중 레지스트리 분리 (`agent-sessions.yaml` vs `agent-sessions.db`)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *YAML 단독 사용 시*: 여러 에이전트와 모니터링 프로세스가 동시 쓰기를 감행하다 텍스트 파일이 도중에 깨져 `YAML parsing syntax error`가 발생하여 전체 시스템 레지스트리가 즉시 마비됩니다.
|
|
* *DB 단독 사용 시*: 바이너리 데이터베이스로만 세션을 관리할 경우 개발자나 외부 도구가 `git status`, `cat`, 마크다운 뷰어 등으로 현재 에이전트 세션의 상태나 장애 원인을 직관적으로 디버깅할 수 없어 가시성이 완전 상실됩니다.
|
|
* **필요성**: 직관적 디버깅 가시성(Human-Readability)과 고성능 동시 트랜잭션 안전성(Transactional Integrity)이라는 두 가지 목적을 동시에 달성해야 합니다.
|
|
* **구현 방법**:
|
|
* `.mam/agent-sessions.db` (SQLite)를 내부 동시성 제어 및 원자적 상태 변경의 진실 원천(Single Source of Truth)으로 지정했습니다.
|
|
* DB 트랜잭션 커밋 완료 직후 PyYAML 기반 헬퍼 함수(`atomic_dump_yaml`)를 통해 정제된 데이터를 `.mam/agent-sessions.yaml` 파일로 원자적 동기화 덤프(`os.replace`)하여, 사람과 시스템 모두 만족하는 이중화 구조를 구축했습니다.
|
|
|
|
### 🔄 3) 역할별 에이전트 페르소나 기반 자율 품질 합의 및 리뷰 루프 (Persona-based Autonomous Consensus Loop)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *단일 에이전트 자기 환각(Hallucination) 머지*: 코드 작성 에이전트 혼자 작업을 진행하고 자가 승인(Self-Approve)하도록 두면, 자신이 유발한 메모리 누수, 잘못된 예외 처리, 안 보이는 타입 오류를 "정상 구현됨"으로 착각하고 버그가 포함된 코드를 저장소에 그대로 커밋/머지하는 치명적 결과가 초래됩니다.
|
|
* **필요성**: 객관적인 제3의 에이전트들이 부여된 역할(Planner, Creator, Reviewer) 및 특화된 페르소나(Persona)에 따라 엄격한 품질 기준(DoD)으로 교차 검증하고 승인해야만 코드에 반영되도록 제어해야 합니다.
|
|
* **구현 방법**:
|
|
* **Planner(설계)**, **Creator(구현)**, **Reviewers(검수)**의 페르소나와 역할을 엄격히 분리했습니다.
|
|
* 리뷰어 리포트 맨 마지막 단독 행에 `[VERDICT: PASS]` 또는 `[VERDICT: NOT PASS]` 토큰 입력을 규칙화하고, 파서가 모든 active 리뷰어의 만장일치 PASS를 확인할 때까지 자동으로 교정 수순을 반복(`run_loop.sh`)하도록 오케스트레이션했습니다.
|
|
|
|
### 📋 4) 작업 단위 구분 및 관리를 위한 태스크 데이터 구조화 (Job Schema & Task Management)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *작업 유실 및 상태 추적 불가*: 작업 위임 데이터 모델이 정의되어 있지 않으면, Orchestrator가 어떤 에이전트에게 무슨 지시문(`brief.md`)을 전달했는지, 현재 상태가 진행 중(`running`)인지, 성공(`completed`)인지, 에러(`error`)인지 추적할 수 없어 작업이 공중에 뜬 '고아(Orphaned) 상태'로 방치됩니다.
|
|
* *중복 태스크 수락 및 Race Condition*: 동일한 작업을 둘 이상의 에이전트가 동시에 중복 수락(Claim)하여 서로의 코드를 덮어쓰거나 엉뚱한 결과물을 교차 전송하는 상충 장애가 일어납니다.
|
|
* **필요성**: 에이전트 간 분동(Delegation)되는 작업 단위를 정형화하고, 각 태스크의 생명주기 및 충돌 없는 클레임 관리를 보장해야 합니다.
|
|
* **구현 방법**:
|
|
* 모든 위임 태스크마다 고유 ID(`job_id`)를 발급하고 `.mam/jobs/<job_id>.json` 파일에 작업 스키마(주 작업자, 부여된 역할, 실행 타입, 보안 토큰, 생명주기 상태 등)를 명확히 데이터 구조화했습니다.
|
|
* `registry.py` 모듈을 통해 작업 등록 및 클레임 시 `fcntl` 파일 자문 잠금(Advisory Lock)을 적용하여 다중 세션 간 작업 중복 수락 경쟁을 원자적으로 제어했습니다.
|
|
|
|
### 📡 5) 비동기 메시징 및 이벤트 백플레인 (Async Messaging Backplane)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *동기 블로킹 타임아웃 폭망*: 동기식 HTTP 요청으로 위임할 경우, 코드 구현 및 복잡한 리팩토링으로 10분 이상 소요되는 에이전트 작업을 기다리다가 오케스트레이터의 HTTP 커넥션 타임아웃이 발생하여 전체 작업이 붕괴됩니다.
|
|
* *블라인드 진행 장애*: 비동기 이벤트 채널이 없으면 에이전트가 백그라운드에서 무한 루프에 빠졌는지, 정상 동작 중인지 알 수 있는 진행 표기(`progress`)를 수신할 수 없습니다.
|
|
* **필요성**: 위임자와 실행자 간에 커넥션을 묶어두지 않고 비동기로 실시간 이벤트 및 중간 진행 상태를 주고받아야 합니다.
|
|
* **구현 방법**:
|
|
* 경량 메시징 표준인 **MQTT 브로커**를 백플레인으로 채택하고 `publish_event.py`와 `job_subscriber.py`를 연결했습니다.
|
|
* 구독을 먼저 개시하는 *Subscribe-before-Publish* 규칙과 terminal 이벤트의 `retain=True` 설정으로 메시지 유실을 방지했습니다.
|
|
* Payload 내에 단조 증가 시퀀스 번호(`seq`)와 HMAC-SHA256 서명을 포함시켜 리플레이 공격 및 메시지 변조를 차단했습니다.
|
|
|
|
### 📸 6) 컨텍스트 보존 및 화면 유실 방지 (Pane Snapshotting & Markdown Bridge)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *뷰포트 잘림으로 인한 디버그 정보 유실*: 터미널(TUI) 스크롤백 한계(예: 2000줄)로 인해 에이전트가 출력한 핵심 디버그 스택 트레이스나 긴 린트 에러 메시지가 상단으로 밀려 올라가 유실됩니다.
|
|
* *입력 깨짐 및 줄바꿈 돌발 실행*: 100줄이 넘는 복잡한 프롬프트나 한글/특수문자를 터미널 입력창에 직접 문자열로 보낼 경우, 멀티바이트 깨짐이나 줄바꿈 문자로 인해 에이전트가 입력을 받다 말고 중간에 명령어를 기습 실행하는 참사가 일어납니다.
|
|
* **필요성**: 장시간 터미널 출력 히스토리를 완벽하게 보존하고, 정교한 입력 데이터를 손상 없이 전달해야 합니다.
|
|
* **구현 방법**:
|
|
* **3단계 Pane Snapshotting** (작업 전, 루프 중 주기적 캡처, 작업 종료 후)을 적용해 터미널 출력을 파일로 상시 백업했습니다.
|
|
* 복잡한 지시문이나 리뷰 리포트는 TUI 입력창에 직접 타이핑하지 않고, `.mam/jobs/<id>/brief.md` 또는 `report.md` 파일로 작성한 뒤 에이전트에게 마크다운 파일 경로 포인터만 전송하는 **파일 기반 통신 구조**를 구축했습니다.
|
|
|
|
### 🔒 7) 이슈 트래킹 및 감사를 위한 원자적 상태 이력 관리 (Issue Tracking & Atomic Concurrency)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *이슈 추적 불능 및 블랙박스 장애*: 에이전트가 작업 도중 에러(exit code non-zero, 프롬프트 잠금, API 실패 등)로 붕괴했을 때, 어떤 세션에서 무슨 이유로 정지되었는지 이력이 남지 않아 문제 발생 지점을 찾지 못하고 원인 분석이 불가능해집니다.
|
|
* *갱신 유실(Lost Update)로 인한 감사 이력 파손*: 에이전트 A가 에러 발생 원인과 감사 로그(`status=error`, `stop_reason`)를 덤프하는 순간, 다른 모니터링 프로세스가 1초 전의 예전 정상 스냅샷으로 파일/DB를 덮어씌워 장애 이력이 완전히 증발합니다.
|
|
* **필요성**: 에이전트 작업 도중 예외나 문제 발생 시, 이슈 트래커(Issue Tracker)처럼 어느 지점에서 어떤 원인(StackTrace, Pane Snapshot, Job Detail)으로 오류가 났는지 완벽히 추적(Traceability)할 수 있어야 하며, 이 감사 데이터가 동시 쓰기 충돌로 훼손되지 않도록 원자적으로 보호되어야 합니다.
|
|
* **구현 방법**:
|
|
* 모든 비동기 위임 작업 및 세션 상태 변경 시 고유 작업 ID(`job_id`), 담당 에이전트명, 발생 시각, 상세 원인(`detail`), 뷰포트 스냅샷(`pane.capture`)을 `.mam/jobs/<id>/` 디렉토리 및 `.mam/agent-sessions.db`에 감사 이력(Audit Trail)으로 즉시 저장하도록 설계했습니다.
|
|
* SQLite의 `BEGIN IMMEDIATE` 배타 트랜잭션과 `atomic_dump_yaml`(`os.replace`)을 조합하여, 장애 원인 추적 이력 데이터가 다중 프로세스 충돌로 덮어씌워지거나 손상되지 않도록 원자적 동시성을 완벽히 제어했습니다.
|
|
|
|
### 🚀 8) 자동화된 배포 환경 구성 및 프로비저닝 (Deployment Automation & Provisioning)
|
|
* **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
|
|
* *환경설정 파편화 및 접속 불능*: 서버나 에이전트 런타임마다 필수 환경변수(`HERDR_SESSION_NAME`, MQTT 엔드포인트 등)가 누락되거나 수동 설정 오차로 인해, 에이전트 간 통신이 안 되거나 타 격리 세션에 오접속하여 운영 데이터를 덮어쓰는 시스템 파손 발생.
|
|
* *배포 재현성 상실 및 임포트 에러*: 파이썬 가상환경(`.venv`)이나 필수 라이브러리(`paho-mqtt`, `pyyaml`) 설치가 누락된 채 에이전트 세션이 기동되어, 작업 위임 직후 `ModuleNotFoundError`로 파이프라인이 즉시 마비되는 장애.
|
|
* **필요성**: 개발, 테스트, 운영 환경 전체에서 동일한 구동 환경과 패키지 의존성을 신속히 자동 구축하고 배포 재현성을 보장해야 합니다.
|
|
* **구현 방법**:
|
|
* `deploy/generate-env.sh` 자동화 스크립트를 제공하여 `.env` 및 `HERDR_SESSION_NAME` 환경 변수를 1초 만에 자동 생성하고 시스템에 유기적으로 주입하도록 구성했습니다.
|
|
* `.venv` 가상환경 구성 및 `requirements.txt` 의존성 패키지 자동 프로비저닝 단계를 선행 통합하여 완벽히 재현 가능한 배포 체계를 구현했습니다.
|
|
|
|
---
|
|
|
|
## 4. 실전 트러블슈팅 및 튜닝 사례 (Troubleshooting Cases)
|
|
|
|
시스템 구축 및 검증 과정에서 직접 발굴하여 해결한 주요 실전 기술 사례입니다.
|
|
|
|
### 🛠️ 사례 1: Agy(Antigravity) 에이전트의 TOS/약관 동의 화면 차단 문제 해결
|
|
* **증상**: `agy` 에이전트를 격리 홈(`HOME=$root`)에서 실행했을 때, 구동 시마다 **"Terms of Service & Data Use" 약관 동의 및 테마 선택 마법사**가 출력되며 프롬프트 입력이 블로킹됨.
|
|
* **원인**: `agy` 에이전트가 약관 및 초기 설정 상태를 사용자 계정 디렉토리(`~/.gemini/antigravity`, `~/Library/Application Support/Antigravity`, macOS `Preferences` plist 등)에서 가져오는데, 기존 격리 프로비저닝 로직에서 해당 경로들의 심볼릭 링크 시딩이 누락됨.
|
|
* **해결**: `lib.sh::provision_isolation` 함수를 수정하여 macOS의 `Preferences`(`com.google.antigravity.plist` 등), `Application Support/Antigravity`, `Group Containers`와 Linux의 XDG 표준 경로(`~/.config/Antigravity`, `~/.local/share/Antigravity`)를 격리 홈 디렉토리로 자동 링킹하도록 확장함으로써 플랫폼에 관계없이 약관 안내 화면을 건너뛰도록 원천 해결함.
|
|
|
|
### 🛠️ 사례 2: TUI 입력 버퍼 감지 오탐(False-Positive) 완화
|
|
* **증상**: `cline`이나 `claude` 에이전트에 긴 프롬프트(git diff 포함 지시문 등)를 주입할 때 `send_keys_safe: paste not visible` 타임아웃 오류가 발생하며 작업 위임이 중단됨.
|
|
* **원인**: `send_keys_safe` 유틸리티가 입력 텍스트의 끝 24글자 마커(`marker_norm`)가 화면 뷰포트에 출현했는지 검증하는데, `cline` TUI 등 일부 환경은 긴 텍스트 입력 시 입력창 스크롤로 인해 마커가 화면 밖으로 밀려나 오탐(False-Positive)이 발생함.
|
|
* **해결**: `cline` 및 `claude` 세션의 경우 실제 페이스트는 성공했으나 스크롤아웃으로 인해 검증이 실패하는 특성을 고려해, 엄격한 마커 노출 검사를 생략하고 C-m(엔터) 제출 대기 루프로 직행하도록 `lib.sh` 검증 조건문을 완화하여 오케스트레이션 루프의 연속성을 확보함.
|
|
|
|
---
|
|
|
|
## 5. 결론 및 향후 발전 방향
|
|
|
|
본 프레임워크는 프로세스 격리, 파일 기반 원자적 레지스트리, 비동기 MQTT 메시징, 그리고 마크다운 파일 통신을 결합함으로써 **다종 AI 에이전트를 결합한 안정적이고 강인한 자율 협업 오케스트레이션**을 성공적으로 입증했습니다.
|
|
|
|
추후 가상환경 의존성 자동 점검 강화, HMAC 보안 인증 키 자동 교환(FW-N6), 그리고 NFS 환경에서의 파일 락 추상화 레이어 보완을 통해 더욱 확장성 높은 에이전트 플랫폼으로 진화할 수 있습니다.
|