Files

T

Godopu c1b74c1b5c docs(report): add architecture and multi-agent orchestration report

2026-07-22 08:53:41 +09:00

19 KiB

Raw Blame History

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 환경에서의 파일 락 추상화 레이어 보완을 통해 더욱 확장성 높은 에이전트 플랫폼으로 진화할 수 있습니다.

19 KiB Raw Blame History