docs: add seminar scripts & assets, update Herdr guide and multi-agent documentation
This commit is contained in:
Godopu committed
1 parent
d4e1246138
commit
b3ad3831a6
38 files changed
+363
-22
No files matched your search
Vendored
BIN
Binary file not shown.
@@ -2,7 +2,34 @@
|
||||
|
||||
## 소개
|
||||
|
||||
Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워크스페이스 매니저(agent multiplexer)입니다. 여러 AI 코딩 에이전트(Claude Code, Codex 등)를 각각 실제 터미널 pane에서 실행하면서, 어떤 에이전트가 작업 중인지 / 입력을 기다리는지(blocked) / 끝났는지를 사이드바에서 한눈에 확인할 수 있고, detach해도 백그라운드에서 계속 실행됩니다. Rust로 작성된 로컬 바이너리이며 별도의 GUI 앱이나 클라우드 계정이 필요 없습니다.
|
||||
### TMUX란?
|
||||
|
||||
**TMUX(Terminal Multiplexer)**는 하나의 터미널 창/세션 안에서 여러 개의 가상 터미널(Window 및 Pane)을 생성, 접근, 제어할 수 있게 해주는 텍스트 기반 터미널 다중화(Multiplexing) 도구입니다.
|
||||
|
||||
#### 등장 배경
|
||||
- **세션 유실 문제**: 기본 터미널 환경에서는 SSH 원격 접속이 끊어지거나 터미널 창을 닫으면 실행 중이던 장시간 작업(서버 실행, 빌드, 데이터 처리 등)이 강제 종료되는 한계가 있었습니다.
|
||||
- **멀티태스킹의 불편함**: 단일 원격 세션에서 여러 작업을 동시에 모니터링하고 제어하려면 매번 새 SSH 접속을 추가로 열어야 했습니다.
|
||||
- 이러한 한계를 극복하고 **세션의 지속성(Persistence)**과 효율적인 터미널 멀티태스킹을 지원하기 위해 등장했습니다.
|
||||
|
||||
#### 주요 기능
|
||||
- **세션 분리 및 재연결 (Detach & Attach)**: 터미널 접속이 끊겨도 백그라운드에서 프로세스가 계속 실행되며, 언제든 기존 세션에 다시 재연결(Attach)하여 이전 상태 그대로 작업을 이어갈 수 있습니다.
|
||||
- **화면 분할 및 창 관리 (Window & Pane)**: 하나의 터미널 화면을 상하/좌우 패널(Pane)로 자유롭게 분할하거나 여러 탭(Window)을 생성하여 다중 작업을 한눈에 관리할 수 있습니다.
|
||||
- **세션 공유**: 동일한 tmux 세션에 여러 사용자가 동시 접속하여 실시간 화면 공유 및 원격 협업이 가능합니다.
|
||||
|
||||
### HERDR란?
|
||||
|
||||
**Herdr**는 AI 코딩 에이전트 다중화 및 상태 관리에 특화된 **터미널 워크스페이스 매니저(Agent Multiplexer)**입니다. "코딩 에이전트를 위한 tmux"로서 여러 AI 에이전트(Claude Code, Codex 등)를 개별 터미널 패널(Pane)에서 병렬로 실행하고 통합 제어할 수 있는 Rust 기반 로컬 바이너리 도구입니다.
|
||||
|
||||
#### 등장 배경
|
||||
- **AI 에이전트 모니터링의 복잡성**: 기존 tmux 환경에서는 여러 AI 에이전트를 동시 실행할 때 각 패널의 입출력 및 완료/대기 상태(`blocked`, `working`, `done`)를 한눈에 파악하기 어려웠습니다.
|
||||
- **오케스트레이션 및 자동화 한계**: 스크립트나 외부 오케스트레이터가 개별 터미널 패널과 프로그래밍 방식으로 상호작용(명령 입력, 결과 캡처, 상태 대기)할 표준 인터페이스가 부족했습니다.
|
||||
- 이러한 한계를 극복하여 **AI 에이전트 중심의 상태 모니터링**과 **소켓 기반 프로그래밍 제어**가 가능한 터미널 작업 환경을 제공하기 위해 등장했습니다.
|
||||
|
||||
#### 주요 기능
|
||||
- **에이전트 상태 모니터링 사이드바**: 각 패널에서 실행 중인 에이전트의 상태(`working`, `blocked`, `done`, `idle`)를 사이드바에서 한눈에 확인 가능합니다.
|
||||
- **소켓 API & CLI 프로그래밍 제어**: CLI 및 소켓 인터페이스를 통해 명령 전송(`pane run`), 결과 읽기(`pane read`), 상태 대기(`wait agent-status`) 등 자동화 연동을 지원합니다.
|
||||
- **세션 지속성 및 원격 재연결 (Detach & Attach)**: 클라우드 계정이나 GUI 없이 백그라운드 세션을 유지하여 SSH/원격 접속 시에도 기존 에이전트 세션에 그대로 재연결할 수 있습니다.
|
||||
- **워크스페이스/세션 격리**: 프로젝트 단위의 워크스페이스(Workspace)와 독립 세션(Session) 분리를 통해 복수의 코딩 작업을 완전히 격리하여 운용할 수 있습니다.
|
||||
|
||||
공식 사이트: [herdr.dev](https://herdr.dev)
|
||||
|
||||
@@ -16,14 +43,13 @@ Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워
|
||||
|
||||
## 개념 정리
|
||||
|
||||
| 개념 | 설명 |
|
||||
|---|---|
|
||||
| Session | 지속되는 Herdr 서버 하나(런타임 인스턴스). `herdr`는 기본 세션에 붙고, `herdr --session <name>`으로 named session을 launch-or-attach 할 수 있음 |
|
||||
| Workspace | 세션 안의 최상위 프로젝트 컨테이너. 보통 repo/작업 단위로 하나씩 |
|
||||
| Tab | workspace 안의 레이아웃 |
|
||||
| Pane | 실제 터미널 하나 |
|
||||
| Agent | Herdr가 pane 안에서 인식하는 프로세스 (Claude Code, Codex 등). 상태: blocked/working/done/idle/unknown |
|
||||
| Channel | Herdr 바이너리 자체의 업데이트 트랙 (stable/preview) — session과 무관한 별개 개념 |
|
||||
| 개념 | 설명 |
|
||||
| --------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Session | 지속되는 Herdr 서버 하나(런타임 인스턴스). `herdr`는 기본 세션에 붙고, `herdr --session <name>`으로 named session을 launch-or-attach 할 수 있음 |
|
||||
| Workspace | 세션 안의 최상위 프로젝트 컨테이너. 보통 repo/작업 단위로 하나씩 |
|
||||
| Tab | workspace 안의 레이아웃 |
|
||||
| Pane | 실제 터미널 하나 |
|
||||
| Agent | Herdr가 pane 안에서 인식하는 프로세스 (Claude Code, Codex 등). 상태: blocked/working/done/idle/unknown |
|
||||
|
||||
## 주요 단축키
|
||||
|
||||
@@ -68,7 +94,7 @@ Herdr의 세션은 launch-or-attach 모델이라 이 한 줄로 세션이 없으
|
||||
attach된 pane 안에서:
|
||||
|
||||
```bash
|
||||
claude
|
||||
claude --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
(테스트용으로 권한 프롬프트를 건너뛰려면 `claude --dangerously-skip-permissions`. 신뢰된 환경에서만 사용 권장.)
|
||||
@@ -85,7 +111,7 @@ herdr --session new_session agent get claude
|
||||
텍스트 입력 + Enter 제출을 원자적으로 수행:
|
||||
|
||||
```bash
|
||||
herdr --session new_session pane run <pane_id> "정렬 프로그램을 작성해줘"
|
||||
herdr --session new_session pane run <pane_id> "파이썬으로 정렬 프로그램을 작성해줘"
|
||||
```
|
||||
|
||||
### 4. Claude의 결과 화면 출력
|
||||
|
||||
@@ -6,10 +6,6 @@ AI 에이전트 간의 소통이 단절되는 상황을 방지하기 위해 왜
|
||||
|
||||
|
||||
|
||||
**프로토콜**은 이러한 혼란을 방지하는 플레이북입니다. 프로토콜은 에이전트가 자신을 소개하는 방식(기능), 작업을 요청하는 방식(요청), 진행 상황을 공유하는 방식(스트리밍), 안전하게 실패하는 방식(에러), 권한을 증명하는 방식(권한 부여)을 표준화합니다. 프로토콜이 준비되면 팀들은 시스템을 한 번만 구축하여 어디서나 재사용할 수 있으므로, 전체 프로세스가 투명하고 안전하며 예측 가능해집니다. 그리고 이것이 바로 A2A가 해결하고자 하는 핵심 과제입니다.
|
||||
|
||||
**시작하기에 앞서, 간단하게 생각해 보겠습니다:** A2A는 에이전트들이 예기치 못한 문제 없이 서로 도움을 요청하고 결과를 공유할 수 있도록 마련된 공통 규칙의 집합입니다.
|
||||
|
||||
## A2A란 무엇인가요?
|
||||
|
||||
**Agent2Agent (A2A) 프로토콜**은 본래 구글에서 개발된 오픈 표준으로, 서로 다른 팀이나 프레임워크로 구축된 AI 에이전트들이 안전하고 효율적으로 서로를 검색하고 소통하며 협업할 수 있도록 지원합니다. 이 프로토콜은 공통 언어와 상호작용 모델을 제공하여 에이전트들이 서로의 비공개 메모리, 도구, 또는 내부 정보에 직접 접근하지 않고도 구조화된 데이터, 텍스트, 파일을 교환하며 정보를 공유하고 작업을 관리하며 유저의 목표를 달성할 수 있도록 돕습니다.
|
||||
@@ -821,20 +817,15 @@ curl http://0.0.0.0:8000/.well-known/agent-card.json
|
||||
향후 실무형 고급 에이전트를 설계할 때도 다음 핵심 수칙들을 기억하고 준수해 주시기 바랍니다.
|
||||
|
||||
- **모든 요소에 고유 ID 배포:** 추적 및 디버깅을 원활하게 하기 위해 태스크, 메시지, 컨텍스트 전체에 UUID 등의 고유 ID를 부여해야 합니다.
|
||||
|
||||
- **안정적인 예외 처리:** 서버 다운이나 비정상 실행 시 생으로 에러를 뿜게 두지 말고, 클라이언트가 식별할 수 있도록 규격에 맞춰 에러 객체를 리턴해야 합니다.
|
||||
|
||||
- **스펙 완벽 준수:** A2A 프로토콜의 진정한 매력은 강력한 규칙 일관성에서 나옵니다. 조그마한 스펙 일탈도 에이전트 간 상호 호환성을 파괴할 수 있습니다.
|
||||
|
||||
- **태스크 중심 설계:** 단순 연산조차 태스크 구조에 감싸서 리턴해 버릇하면 로깅, 모니터링 및 향후 대규모 확장 시 시스템 통합이 매우 쉬워집니다.
|
||||
|
||||
- **선 검증 후 로직 처리:** Pydantic 등의 모델을 사용해 최우선으로 들어오는 데이터 형식이 적합한지 검사한 뒤 비즈니스 로직에 전달하십시오.
|
||||
|
||||
|
||||
이제 여러분은 완성되어 작동하는 A2A 기초 시스템을 완전히 소유하게 되었습니다. 하지만 이것은 위대한 시작일 뿐입니다. 오늘 구축한 가벼운 에코 에이전트는 향후 마주할 복잡한 설계 기법들의 단단한 기반이 되어 줄 것입니다. 핵심 소통 패턴을 확실하게 익혔으니, 앞으로 마주하게 될 고급 기법들도 이미 알고 있는 지식을 바탕으로 어렵지 않게 쌓아 올리실 수 있습니다. 더 중요한 것은 여러분이 글로벌 A2A 생태계에 성공적으로 합류했다는 사실입니다. 여러분의 에이전트는 이제 규격을 준수하는 타 에이전트들과 자유롭게 통신할 수 있으며, 클라이언트는 세계 각지의 팀들이 공개한 유용한 에이전트들을 자유롭게 검색하여 협업을 요청할 수 있습니다. 이것이 바로 서로 다른 전문적인 에이전트들이 상호 작용하며 복잡한 사회적 문제를 해결해 나가는 A2A 프로토콜이 그리는 미래상입니다.
|
||||
|
||||
---
|
||||
|
||||
# A2A SDK 사용법
|
||||
|
||||
FastAPI 등을 이용한 직접 구현 방식에서 공식 A2A SDK를 사용한 에이전트 개발 방식으로 업그레이드하는 방법을 알아봅니다. `AgentExecutor`, `DefaultRequestHandler` 등 SDK의 핵심 컴포넌트들과 태스크 라이프사이클 관리법을 이해합니다. 향상된 프로토콜 처리 기능과 상용화 스펙을 갖춘 확장 가능하고 유지 관리가 용이한 에이전트를 구축하는 방법을 학습합니다.
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
# Multi-Agent Mux (MAM) Architecture & Orchestration Report
|
||||
|
||||
## 1. 개요 (Executive Summary)
|
||||
|
||||
현대 AI 에이전트 워크플로우는 세션 타임아웃, 프로세스 격리 부재, 터미널 뷰포트 잘림, 단일 에이전트의 자기 과신(Self-Confidence) 오류 등 다양한 문제점을 내포하고 있습니다.
|
||||
|
||||
**Multi-Agent Mux**는 **Tmux/Herdr** 프로세스 관리자와 **MQTT 메시징 백플레인**을 결합하여, 여러 LLM 에이전트가 안전하게 프로세스를 격리받고 비동기로 이벤트를 주고받으며 다수의 에이전트 간 자율 검증 및 교차 리뷰 루프를 수행할 수 있는 기능을 지원하는 오케스트레이션 스킬 도구 입니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 코어 스킬 구성 명세 (Core Skills Inventory)
|
||||
|
||||
multi-agent-mux 도구는 다양한 스킬들로 구성되어 있습니다:
|
||||
|
||||
* **`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 환경에서의 파일 락 추상화 레이어 보완을 통해 더욱 확장성 높은 에이전트 플랫폼으로 진화할 수 있습니다.
|
||||
@@ -0,0 +1,8 @@
|
||||
- https://twentytwentyone.tistory.com/454
|
||||
- Agent SDK
|
||||
- [Claude](https://jjeongil.tistory.com/3360#google_vignette)
|
||||
- [OpenAI](https://openai.github.io/openai-agents-python/)
|
||||
- [Google ADK](https://github.com/google/adk-python)
|
||||
- [Antigravity SDK](https://antigravity.google/product/antigravity-sdk)
|
||||
- [crewai a2a protocol](https://docs.crewai.com/v1.15.5/en/learn/a2a-agent-delegation)
|
||||
- [LangChain and LangGraph](https://www.youtube.com/watch?v=W_uwR_yx4-c)
|
||||
Reference in new issue
Block a user