Beads Agent Mail 멀티에이전트 병렬작업 도입
배경
로컬 환경에서 Claude Code, OpenCode 등 여러 AI 에이전트를 병렬로 실행하여 작업 효율을 높이기 위한 Agent Mail 도입 검토.
관련 문서
문제 정의
Git-only 모드의 한계
| 항목 | Git-only | Agent Mail |
|---|---|---|
| 지연시간 | 2-5초 | <100ms |
| 충돌 감지 | 사후 (git pull 후) | 즉시 (HTTP 409) |
| 작업 예약 | 없음 | Reservation TTL |
발생 가능한 시나리오
Agent A: bd update sks-123 --status in_progress
↓ (30초 debounce)
↓ export to JSONL → git commit/push
Agent B: bd update sks-123 --status in_progress
↓ (동시 작업 시작 - 충돌!)해결책: Agent Mail
아키텍처
┌─────────────────────────────────────────────┐
│ bd (Beads CLI) │
│ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Git Sync │ │ Agent Mail │ │
│ │ (필수) │ │ (선택-권장) │ │
│ └─────────────┘ └─────────────────┘ │
│ │ │ │
└─────────┼──────────────────────┼────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ .beads/ │ │ Agent Mail │
│ issues.jsonl │ │ Server │
│ (git) │ │ (HTTP) │
└──────────────┘ └──────────────┘보호 메커니즘 계층
| 계층 | 메커니즘 | 보호 대상 | 지연시간 |
|---|---|---|---|
| 1 | Agent Mail Reservation | 이슈 충돌 방지 | <100ms |
| 2 | Exclusive Lock | 데이터베이스 전체 | 즉시 |
| 3 | Git Sync | 데이터 영속성 | 2-5초 |
| 4 | Daemon 격리 | 프로젝트 격리 | - |
설치 및 설정
1. Agent Mail 서버 설치
cd ~/repos/3rd
git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git
cd mcp_agent_mail
python3 -m venv .venv
source .venv/bin/activate
pip install -e .2. 서버 실행
# 별도 터미널에서 실행
cd ~/repos/3rd/mcp_agent_mail
source .venv/bin/activate
python -m mcp_agent_mail.cli serve-http
# http://127.0.0.1:8765 에서 실행3. 각 터미널 환경 변수 설정
# 터미널 1 (Claude Code - Agent Alpha)
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=claude-alpha
export BEADS_PROJECT_ID=sks-gateway
# 터미널 2 (OpenCode - Agent Beta)
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=opencode-beta
export BEADS_PROJECT_ID=sks-gateway # 동일해야 충돌 감지됨
# 터미널 3 (Claude Code - Agent Gamma)
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=claude-gamma
export BEADS_PROJECT_ID=sks-gateway워크플로우
병렬 작업 시작
# 1. 작업 시작 전 - 가용 이슈 확인
cd ~/repos/work/sks-gateway-forked
bd ready --json
# 2. 이슈 claim (먼저 claim한 에이전트가 소유)
bd update sks-xxx --status in_progress
# → Agent Mail이 자동으로 reservation 생성
# → 다른 에이전트가 같은 이슈 claim 시 HTTP 409 에러
# 3. 작업 수행...
# 4. 완료 시
bd close sks-xxx --reason "구현 완료"
# → Reservation 자동 해제
# 5. 세션 종료 시 (필수!)
bd sync
git push충돌 발생 시
# Agent B가 이미 예약된 이슈 claim 시도
bd update sks-123 --status in_progress
# Error: sks-123 already reserved by claude-alpha
# 해결: 다른 이슈 선택
bd ready --json
bd update sks-456 --status in_progressGraceful Degradation
Agent Mail 서버가 다운되어도 beads는 정상 동작:
# 서버 다운 시 경고 메시지
WARN Agent Mail unavailable, falling back to git-only mode
# 모든 명령어 정상 동작 (Git-only 모드)
bd ready
bd update sks-xxx --status in_progress운영 팁
서버 상태 확인
# 서버 health 확인
curl http://127.0.0.1:8765/api/health
# 현재 reservations 확인
curl http://127.0.0.1:8765/api/reservations
# Web UI
open http://127.0.0.1:8765/mailStale Reservation 정리
# 에이전트 crash 후 reservation 수동 해제
curl -X DELETE http://127.0.0.1:8765/api/reservations/sks-123
# 또는 서버 재시작 (모든 ephemeral 상태 초기화)
pkill -f "mcp_agent_mail"
python -m mcp_agent_mail.cli serve-http프로젝트 AGENTS.md 설정
## Agent Mail Configuration
이 프로젝트는 멀티에이전트 병렬 작업을 위해 Agent Mail을 사용합니다.
### 환경 변수 설정 (필수)
\`\`\`bash
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=<unique-agent-name>
export BEADS_PROJECT_ID=sks-gateway
\`\`\`
### 서버 실행
\`\`\`bash
cd ~/repos/3rd/mcp_agent_mail
source .venv/bin/activate
python -m mcp_agent_mail.cli serve-http
\`\`\`참고 자료
- Beads GitHub
- MCP Agent Mail GitHub
- ~/repos/3rd/beads/docs/AGENT_MAIL.md
- ~/repos/3rd/beads/docs/DAEMON.md
Comments