Architecture on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

Fri, 08 May 2026 21:57:11 +0900

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

fleet.yaml — 워커 배치

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

claude.service.j2의 핵심 부분:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: fleet.yaml에 항목 추가

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

2단계: 미리보기

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

3단계: 실제 배포

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

[AgentForge] 블로그 자동화 서비스 전체 아키텍처 — AI 댓글, 번역, 포스트 생성까지

Tue, 05 May 2026 00:30:00 +0900

블로그를 운영하면서 가장 번거로운 작업 세 가지가 있습니다. 댓글에 답하기, 영문 번역 유지하기, 그리고 꾸준히 글 쓰기. AgentForge 프로젝트에서는 이 세 가지를 모두 AI 에이전트로 자동화했습니다.

이 글에서는 2개 서버에 걸쳐 동작하는 블로그 자동화 서비스의 전체 아키텍처를 정리합니다.

시스템 토폴로지

┌─────────────────────┐ HTTPS ┌─────────────────────┐
│ arm1 서버 │ ──────────────▶ │ ec1 서버 │
│ (에이전트 오퍼레이터) │ │ (블로그 호스팅) │
├─────────────────────┤ ├─────────────────────┤
│ blog-agent (:8081) │ │ Hugo (nginx) │
│ ├─ CommentHandler │ │ Blog API (:8000) │
│ ├─ TranslateHandler│ │ ├─ translator.py │
│ └─ PostGenerator │ │ ├─ blog_manager.py │
│ │ │ └─ git_handler.py │
│ NATS / PostgreSQL │ │ │
│ Prometheus / Grafana │ │ Git (yarang/blogs) │
└─────────────────────┘ └─────────────────────┘

서버	역할	핵심 서비스
arm1	에이전트 오퍼레이터	`blog-agent.service` — Flask + Scheduler + LLM Client
ec1	블로그 호스팅 + API	Hugo (nginx) + `blog-api.service` (FastAPI)

두 서버 간 통신은 HTTPS API 호출만 가능합니다. arm1에서 ec1로의 SSH 접속은 차단되어 있어, 모든 연동은 Blog API를 통해 이루어집니다.

arm1: 통합 블로그 에이전트

왜 통합했는가

초기에는 댓글 응답, 번역, 포스트 생성이 각각 독립 프로세스(3개 systemd 서비스)로 운영되었습니다. 문제는:

Claude Code CLI(--print) 호출 방식으로 응답 시간 9.7초, 디스크 688MB 소모
systemd 유닛 6개 관리 부담
프로세스 간 상태 공유 불가

이를 1개 프로세스로 통합하면서 직접 LLM API 호출로 전환했습니다. 결과:

지표	Before	After
응답 시간	9.7초	1.7초
디스크 사용	688MB	~50MB
systemd 유닛	6개	1개
프로세스	3개	1개

아키텍처

class BlogAgent:
 """1 프로세스 = Flask (webhook) + Scheduler (timer) + LLM Client"""
 
 def __init__(self):
 self.config = AgentConfig.from_credentials()
 self.llm = LLMClient(self.config) # ZAI glm-4.7
 self.api = BlogAPIClient(self.config) # ec1 Blog API
 
 # 핸들러
 self.comment = CommentHandler(self.llm, self.config)
 self.translate = TranslateHandler(self.api)
 self.post_gen = PostGenerator(self.llm, self.api)
 
 # 스케줄러
 self.scheduler = Scheduler()
 self.scheduler.every(hours=6, task=self.translate.check_and_sync)
 self.scheduler.daily_at(hour=9, task=self.post_gen.generate_and_publish)

모듈별 동작

1. CommentHandler — AI 댓글 응답

GitHub Discussions의 Webhook 이벤트를 수신하여 자동으로 AI 댓글을 생성합니다.

[사용자 댓글] → GitHub Webhook → arm1 Flask → CommentHandler
 → LLM 호출 (ZAI glm-4.7) → 답변 생성 → GitHub API로 댓글 게시

트리거: Webhook 이벤트 기반 (실시간)
필터링: 블로그 소유자 댓글, AI 생성 댓글은 건너뜀
보안: HMAC-SHA256 Webhook 시크릿 검증, Flask-Limiter 적용

2. TranslateHandler — 자동 번역 트리거

6시간마다 ec1의 Blog API에 번역 동기화를 요청합니다.

[Scheduler 6h] → TranslateHandler.check_and_sync()
 → POST /translate/sync → ec1 Blog API가 실제 번역 수행

arm1은 번역을 직접 수행하지 않고, ec1 API에 트리거만 보냅니다. 실제 번역 로직은 ec1의 translator.py에 있습니다.

3. PostGenerator — 자동 포스트 생성

매일 오전 9시에 기술 블로그 포스트를 자동 생성합니다.

[Scheduler 09:00 KST] → PostGenerator.generate_and_publish()
 → 기존 주제 수집 → RSS 트렌드 참조 → LLM으로 콘텐츠 생성
 → 중복 검사 → Blog API로 게시

중복 방지가 핵심입니다. difflib.SequenceMatcher로 새 제목과 최근 100개 기존 제목의 유사도를 비교합니다:

def _is_duplicate_title(self, new_title, existing_titles):
 """threshold 0.6 이상이면 중복으로 판정"""
 new_lower = new_title.lower().strip()
 for title in existing_titles[-100:]:
 ex_lower = title.lower().strip()
 ratio = difflib.SequenceMatcher(None, new_lower, ex_lower).ratio()
 if ratio >= 0.6:
 return True
 return False

ec1: Blog API 번역 시스템

Gemini로의 전환

초기에는 ZAI(glm-4.7)로 번역을 수행했으나, 치명적인 문제가 발생했습니다:

glm-4.7은 reasoning 모델로, max_tokens 예산을 reasoning_content(내부 사고 과정)에 먼저 소진합니다. max_tokens=256이면 reasoning에 256토큰을 모두 쓰고, 실제 content는 빈 문자열이 됩니다.

이로 인해 9개 영문 게시글의 제목이 빈 문자열로 번역되는 사고가 발생했습니다.

해결책: Gemini 2.5 Flash Lite로 교체.

항목	ZAI (이전)	Gemini (현재)
모델	glm-4.7 (reasoning)	gemini-2.5-flash-lite
번역 시간	~30초/포스트	~8초/포스트
비용	API 유료	무료 (1,500건/일)
빈 응답 문제	발생	없음

OpenAI-Compatible 엔드포인트

Gemini는 OpenAI 호환 API를 제공합니다. 기존 코드를 한 줄도 바꾸지 않고 base URL만 교체하면 됩니다:

LLM_BASE_URLS = {
 "GEMINI": "https://generativelanguage.googleapis.com/v1beta/openai",
 "ZAI": "https://api.z.ai/api/coding/paas/v4",
}

번역 매칭 로직

한국어↔영어 게시글 페어링은 날짜 접두사 매칭을 사용합니다:

ko: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
en: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
 ↑ 같은 접두사 = 같은 게시글

slug의 언어가 다를 수 있지만, YYYY-MM-DD-NNN 부분이 같으면 같은 게시글로 인식합니다. 이 방식의 전제 조건은 같은 날짜에 같은 번호가 2개 이상 존재하면 안 된다는 것입니다.

Title-in-Body 번역 기법

제목을 별도 API 호출로 번역하면 reasoning 모델에서 빈 결과가 나오는 문제가 있었습니다. 해결책은 제목을 본문 첫 줄에 포함시키는 것:

# 번역 요청 시
prompt = f"# {original_title}\n\n{original_body}"

# 번역 결과에서 제목 추출
if translated.lstrip().startswith("# "):
 lines = translated.lstrip().split("\n", 1)
 extracted_title = lines[0].lstrip("# ").strip()
 translated_body = lines[1].lstrip("\n")

하나의 API 호출로 제목과 본문을 동시에 번역하므로, 맥락이 보존되고 토큰도 절약됩니다.

LLM 전략: 역할별 모델 분리

하나의 LLM으로 모든 작업을 처리하지 않습니다. 작업 성격에 맞춰 모델을 분리했습니다.

작업	서버	모델	이유
댓글 AI 응답	arm1	ZAI glm-4.7	대화형, 한국어 품질 우수
포스트 생성	arm1	ZAI glm-4.7	긴 글 생성, 창의성 필요
번역 (ko→en)	ec1	Gemini Flash Lite	비추론형, 빠르고 무료

핵심 원칙: reasoning 모델은 번역에 쓰지 않는다. reasoning 모델은 내부 사고에 토큰을 소비하므로, 단순 변환 작업에는 비추론형 모델이 적합합니다.

모니터링과 운영

헬스체크 엔드포인트

# arm1 에이전트
curl http://arm1:8081/health
# → {"status":"healthy","agent":"blog-agent","scheduler_jobs":2,"uptime_sec":...}

curl http://arm1:8081/status
# → {"scheduler":[{"name":"auto-translate","last_run":...},{"name":"post-generator","last_run":"2026-05-04"}]}

# ec1 Blog API
curl https://blog.example.com/api/health
# → {"status":"healthy","version":"2.0.0"}

관찰 포인트

지표	정상 범위	알림 조건
arm1 uptime	>0	서비스 다운
scheduler_jobs	2	≠ 2
번역 동기화	ko=en 개수 일치	차이 발생
포스트 생성	매일 1건	24시간 이상 미생성

교훈과 운영 팁

1. Reasoning 모델의 함정

max_tokens가 reasoning과 content를 합산한다는 것을 문서에서 명시하지 않는 경우가 많습니다. 빈 응답이 나오면 finish_reason을 확인하세요 — "length"라면 토큰 예산 부족입니다.

2. OpenAI-Compatible 패턴의 가치

번역 제공자를 ZAI에서 Gemini로 바꿀 때 코드 변경이 base URL 1줄이었습니다. 처음부터 OpenAI-compatible 인터페이스로 추상화하면 LLM 교체 비용이 극적으로 줄어듭니다.

3. 날짜 접두사 매칭의 제약

YYYY-MM-DD-NNN 패턴에서 같은 날짜에 같은 번호가 2개 이상 존재하면 번역 매칭이 깨집니다. PostGenerator에서 새 게시글 생성 시 해당 날짜의 마지막 번호 + 1을 확인하는 로직이 필수입니다.

4. 통합 프로세스의 이점

3개 독립 서비스를 1개로 통합하면서 얻은 것:

상태 공유 (LLM 클라이언트, 설정, API 클라이언트를 한 번만 초기화)
배포 단순화 (systemd 유닛 1개)
디버깅 용이 (로그가 한 곳에 모임)

향후 계획

arm1 에이전트의 LLM도 Gemini로 통합 검토
댓글 품질 평가 파이프라인 (자동 생성 댓글의 적절성 모니터링)
번역 품질 자동 검증 (역번역 비교)
AgentForge 프레임워크를 통한 에이전트 간 협업 확대

블로그 자동화는 “완전 자동"이 아니라 “최소 개입"을 목표로 합니다. AI가 생성한 콘텐츠를 사람이 검토하고, 시스템이 이상 징후를 감지하면 운영자에게 알리는 구조가 안정적인 운영의 핵심입니다.

멀티모델 AI 에이전트 팀 설계: 조합형 아키텍처와 5팀 계층 구조

Mon, 30 Mar 2026 00:31:36 +0900

개요

블로그 시스템 구축을 위해 14명의 AI 전문가, 5개 팀, 4개 LLM 모델로 구성된 멀티모델 에이전트 팀을 설계했습니다. 핵심은 두 가지입니다.

조합형 에이전트(Composed Agent): 역할 정의와 실행 프로필을 분리해 재사용성 극대화
계층형 브릿지 리더십: 상위팀-하위팀 간 기술 리드의 이중 소속으로 소통 병목 해결

이 글에서는 최종 구조, 모델 배분 전략, 조합형 아키텍처 설계 과정을 공유합니다.

배경: 왜 멀티모델인가

하나의 LLM으로 모든 작업을 처리하면 두 가지 문제가 발생합니다.

비용: Claude Opus 수준의 모델로 14명 전문가를 실행하면 비용이 통제 불가능
적합성: 설계에는 빠른 추론이, 보안 분석에는 깊은 논리가, 구현에는 안정적인 코딩이 필요

그래서 작업 성격에 맞춰 모델을 분배했습니다.

최종 팀 구조

5개 팀, 14명 전문가, 4개 모델로 구성됩니다.

graph TD
 subgraph UPPER["상위팀 — 조정 팀 (steering-team) · consensus"]
 ORC["오케스트레이터
relay:steering-orchestrator"]
 DES["설계자
gemini:gemini-2.5-flash"]
 SEC["보안 검토자
codex:gpt-4o"]
 STL["백엔드 기술 리드
relay:developer-zai"]
 FTL["프론트엔드 기술 리드
relay:developer-zai"]
 DTL["데스크탑 기술 리드
relay:developer-zai"]
 INF["인프라 네트워크
gemini:gemini-2.5-flash"]
 SAD["서버 관리자
relay:developer-zai"]
 end

 subgraph LOWER_BE["백엔드 팀 · leader_decides"]
 BTL["백엔드 기술 리드"]
 BDEV["백엔드 개발자"]
 end

 subgraph LOWER_FE["프론트엔드 팀 · leader_decides"]
 FTL2["프론트엔드 기술 리드"]
 FDEV["프론트엔드 개발자"]
 FUX["UX 디자이너"]
 end

 subgraph LOWER_DT["데스크탑 팀 · leader_decides"]
 DTL2["데스크탑 기술 리드"]
 DDEV["데스크탑 개발자"]
 DUX["UX 디자이너"]
 end

 subgraph LOWER_INFRA["인프라 팀 · leader_decides"]
 SAD2["서버 관리자 (리더)"]
 INET["클라우드 네트워크"]
 DBA["DB 아키텍트"]
 end

 UPPER -.->|bridge| LOWER_BE
 UPPER -.->|bridge| LOWER_FE
 UPPER -.->|bridge| LOWER_DT
 UPPER -.->|bridge| LOWER_INFRA

 BTL --> BDEV
 FTL2 --> FDEV
 FTL2 --> FUX
 DTL2 --> DDEV
 DTL2 --> DUX
 SAD2 --> INET
 SAD2 --> DBA

팀별 상세

팀	유형	의사결정	리더	팀원 수
조정 팀	upper	consensus	오케스트레이터	8명 (브릿지 포함)
백엔드 팀	lower	leader_decides	백엔드 기술 리드	2명
프론트엔드 팀	lower	leader_decides	프론트엔드 기술 리드	3명
데스크탑 팀	lower	leader_decides	데스크탑 기술 리드	3명
인프라 팀	lower	leader_decides	서버 관리자	3명

인프라 팀 분리 결정

초기 설계에서는 DB 아키텍트와 서버 관리자가 백엔드 팀에 포함되어 있었습니다. 하지만 작업 공간(Workspace) 기준으로 분리했습니다.

graph LR
 subgraph 백엔드팀
 B["API 코드 작성
FastAPI, Python
workspace: VS Code / SSH"]
 end

 subgraph 인프라팀
 S["서버 관리
Docker, Ubuntu, Nginx
workspace: SSH 터미널"]
 N["클라우드 네트워크
Cloudflare Dashboard
workspace: 웹 콘솔"]
 D["DB 관리
PostgreSQL, 마이그레이션
workspace: psql / SSH"]
 end

 B -.->|API 배포| S
 B -.->|쿼리 최적화| D

분리 이유: 작업 공간이 다르면 같은 팀에 두는 것보다 분리하는 것이 자연스럽습니다.

모델 배분 전략

pie title 모델별 전문가 수
 "relay:developer-zai (GLM)" : 10
 "gemini:gemini-2.5-flash" : 2
 "codex:gpt-4o" : 1
 "zai:glm-4" : 1

모델	전문가 수	용도	선택 이유
relay:developer-zai	10명	구현, 운영, 리드	비용 효율적, 안정적 코딩
gemini:gemini-2.5-flash	2명	설계, 인프라 네트워크	빠른 응답, 외부 API 호출 용이
codex:gpt-4o	1명	보안 검토	높은 추론 능력, OWASP 지식
zai:glm-4	1명	컨텍스트 압축	무료 티어, 텍스트 요약 특화

10명의 구현 전문가를 GLM(저비용 모델)에 배정하여 전체 비용의 60-70%를 절감했습니다.

조합형 에이전트 아키텍처 (Composed Agent Pattern)

이번 설계의 핵심 혁신은 역할 정의(Expert)와 실행 프로필(Definition)의 분리입니다.

기존 방식의 문제

기존에는 역할과 실행 로직이 결합되어 변경 시 전체 재작성이 필요하고 재사용이 불가능했습니다.

조합형 방식

graph TD
 DEF["Definition
백엔드 개발자"]
 DEF --> BASE["Base: backend-core"]
 DEF --> CAP["Capabilities:
rest-api, crud, auth-jwt"]
 DEF --> PLAT["Platform: fastapi"]
 DEF --> POL["Policy: blog-default"]

 BASE --> |"조합"| RUN["런타임 에이전트"]
 CAP --> |"조합"| RUN
 PLAT --> |"조합"| RUN
 POL --> |"조합"| RUN

모듈 구조

agent-library/
├── definitions/ ← 14개 에이전트 정의
├── modules/
│ ├── base/ ← 6개 기본 모듈
│ ├── capabilities/ ← 15개 역량 모듈
│ ├── platforms/ ← 5개 플랫폼 모듈
│ └── policies/ ← 1개 정책
└── runs/ ← 실행 이력

장점

재사용성: rest-api 역량 모듈은 백엔드 개발자와 기술 리드가 공유
플랫폼 교체: platform: fastapi를 platform: django로 변경하면 즉시 전환
역량 확장: 새 역량 모듈을 추가하고 Definition에 연결만 하면 됨
정책 통일: 모든 에이전트가 동일한 blog-default 정책을 따름

전문가-Definition 매핑

전문가	Definition	Base	Capabilities	Platform
백엔드 개발자	backend-developer	backend-core	rest-api, crud, auth-jwt	fastapi
백엔드 기술 리드	backend-tech-lead	backend-core	rest-api, crud, code-review	fastapi
프론트엔드 개발자	frontend-developer	frontend-core	markdown-renderer, list-filter-sort	nextjs
서버 관리자	server-administrator	server-core	docker-management, nginx-config, postgres-admin	ubuntu
인프라 네트워크	infra-network-admin	infra-core	dns-management, ssl-certificates, rate-limiting	cloudflare
보안 검토자	security-auditor	specialist-core	security-audit	fastapi
컨텍스트 압축	context-compressor	specialist-core	context-compression	markdown

TLS 인증서 전략: Cloudflare Origin CA

프로덕션 환경의 TLS 인증서로 Let’s Encrypt 대신 Cloudflare Origin CA를 선택했습니다.

sequenceDiagram
 participant Client as 방문자
 participant CF as Cloudflare (Proxy)
 participant Nginx as Nginx (Origin)
 participant API as FastAPI

 Client->>CF: HTTPS 요청
 CF->>CF: Cloudflare 관리 인증서로 종료
 CF->>Nginx: Origin CA 인증서로 암호화
 Nginx->>API: HTTP (로컬)
 API-->>Nginx: 응답
 Nginx-->>CF: Origin CA로 암호화
 CF-->>Client: 응답

항목	Let’s Encrypt	Cloudflare Origin CA
유효 기간	90일 (갱신 필요)	15년 (갱신 불필요)
발급 방식	ACME 자동화 필요	Dashboard에서 수동 발급
복잡도	certbot 설정	인증서 파일 복사만

프로덕션 아키텍처:

Oracle Cloud ARM (4 OCPU, 24GB)
├── PostgreSQL (호스트 직접 설치)
├── Docker Compose
│ ├── blog-api (FastAPI)
│ ├── blog-frontend (Next.js standalone)
│ ├── MinIO (S3 호환 스토리지)
│ └── Nginx (Cloudflare Origin CA)
└── Cloudflare Proxy (Full Strict SSL)

Relay 플러그인: 에이전트 호출 메커니즘

팀 구조는 Relay 플러그인을 통해 Claude Code에서 실행됩니다.

sequenceDiagram
 participant User as 사용자
 participant Claude as Claude Code
 participant Plugin as Relay Plugin
 participant MCP as MCP 서버
 participant LLM as 외부 LLM

 User->>Claude: /relay:invoke-agent
 Claude->>Plugin: 전문가 slug로 정의 로드
 Plugin->>Plugin: Definition 조합 (base + capabilities + platform + policy)
 Plugin->>Plugin: backed_by 확인

 alt relay:developer-zai
 Plugin->>Claude: 내부 에이전트 실행
 else gemini:*
 Plugin->>MCP: gemini_mcp 서버 호출
 MCP->>LLM: Gemini API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 else codex:*
 Plugin->>MCP: codex_mcp 서버 호출
 MCP->>LLM: OpenAI API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 end

 Plugin-->>Claude: 최종 결과
 Claude-->>User: 응답

backed_by 네임스페이스

네임스페이스	MCP 서버	용도
`relay:developer-zai`	내부 에이전트	구현, 운영 (저비용)
`relay:steering-orchestrator`	내부 에이전트	조율, 최종 결정
`gemini:gemini-2.5-flash`	gemini_mcp	설계, 외부 API
`codex:gpt-4o`	codex_mcp	보안 분석
`zai:glm-4`	zai_mcp	컨텍스트 압축

설계 결정 이력

결정	대안	선택 이유
인프라 팀 분리	백엔드 팀에 포함	작업 공간이 다름 (SSH vs IDE)
Cloudflare Origin CA	Let’s Encrypt	15년 유효, 갱신 불필요
PostgreSQL 호스트 설치	Docker 컨테이너	단일 서버에서 메모리 효율 우선
조합형 에이전트	단일 정의 에이전트	모듈 재사용성, 플랫폼 교체 용이
GLM 다수 배정	Claude 다수 배정	60-70% 비용 절감

회고: 설계하며 배운 것

1. “완벽한 구조"보다 “실행 가능한 구조”

팀 구조, 모델 배정, 인프라 설정을 완벽하게 설계하려다 보면 시작조차 못 합니다.

2. 작업 공간이 곧 팀 경계

코드를 작성하는 사람과 서버를 관리하는 사람은 물리적 작업 환경이 다르고, 그것이 자연스러운 팀 경계가 됩니다.

3. 조합형 아키텍처의 가치

14명의 전문가, 5개 팀, 4개 모델이 얽히는 환경에서는 모듈 분리가 필수적입니다.

4. 비용은 설계 단계에서 결정된다

“이 작업에 꼭 고비용 모델이 필요한가?“를 매번 물어보면 자연스럽게 비용이 최적화됩니다.

다음 단계

Phase 1 구현 착수: DB, Auth, Post/Category CRUD, Docker
팀 운영 경험 공유: 실제 실행 중 겪은 문제와 해결 과정
성능 모니터링: 모델별 응답 시간, 비용 대비 품질 분석

이 글은 Claude Code + Relay 플러그인을 활용한 AI 에이전트 팀 구성 경험을 정리한 것입니다.

[Discord MCP] Gateway 아키텍처 설계

Sun, 01 Mar 2026 01:13:00 +0900

Claude Code 팀에서 Discord를 통한 사용자 소통을 위해 Discord Gateway Service를 설계했다. 이 글에서는 주요 아키텍처 결정 사항과 user_comm Agent 설계를 정리한다.

1. 전체 아키텍처

구성 요소

계층	구성요소	역할
Discord	Bot, Channel, Thread	사용자 인터페이스
Gateway	WebSocket, REST API, SSE	메시지 라우팅
MCP	gcp-mcp, oci-mcp, db-mcp	도구 실행
user_comm	Discord Agent	사용자 소통 담당

메시지 흐름

flowchart LR
 subgraph D[Discord]
 U[User]
 end
 subgraph G[Gateway :8081]
 WS[WebSocket]
 API[REST API]
 SSE[SSE]
 end
 subgraph A[Claude Code Team]
 UC[user_comm]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 DB[db-mcp]
 end

 U --> WS
 WS --> UC
 UC --> API
 API --> GCP
 API --> OCI
 API --> DB
 GCP --> UC
 OCI --> UC
 DB --> UC
 UC --> SSE
 SSE --> U

2. user_comm Agent (사용자 소통 담당)

역할 및 책임

user_comm Agent는 Claude Code 팀의 멤버로서 Discord 채널을 통해 사용자와 소통하고 다른 agent들과 협업합니다.

기능	설명
입력 수신	Discord 메시지를 받아 적절한 agent에게 전달
의견 요청	다른 agent의 요청으로 사용자 의견 질의
알림/보고	시스템 상태, 경고, 리포트 전송
팀 통신	다른 agent와 메시지 송수신

내부 구조

flowchart TB
 subgraph UC[user_comm Agent]
 DBot[Discord Bot]
 Agent[UserCommAgent]
 TComm[TeamCommunicator]
 DBot <--> Agent
 Agent <--> TComm
 end
 subgraph DAPI[Discord API]
 M[Messages]
 B[Buttons]
 T[Threads]
 end
 subgraph O[Other Agents]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 AL[alert-mcp]
 end

 DBot <--> M
 DBot <--> B
 DBot <--> T
 TComm --> GCP
 TComm --> OCI
 TComm --> AL

메시지 타입

class MessageType(Enum):
 TASK_REQUEST = "task_request" # 작업 요청
 NOTIFICATION = "notification" # 알림
 OPINION_REQUEST = "opinion_request" # 의견 요청
 OPINION_RESPONSE = "opinion_response" # 의견 응답
 STATUS_REPORT = "status_report" # 상태 보고
 ERROR = "error" # 에러

주요 기능 동작

입력 수신 (Discord → Agent)

사용자: "@gcp-monitor 서버 상태 확인"
 → DiscordBot.on_message
 → UserCommAgent._parse_command (target: gcp-monitor)
 → TeamCommunicator.send_to_agent
 → Discord: "gcp-monitor에게 요청을 전달했습니다."

의견 요청 (Agent → Discord)

gcp-monitor: "디스크 정리할까요?" → user_comm
 → DiscordBot.ask_opinion (버튼 또는 답장 대기)
 → 사용자 응답
 → TeamCommunicator.send_to_agent (응답 전달)

알림/보고 (Agent → Discord)

oci-monitor: "디스크 92% 경고" → user_comm
 → DiscordBot.send_message (Embed 형식)

3. Redis 없이 동작하는 가벼운 아키텍처

왜 Redis를 제거했나?

항목	Redis 사용	In-Memory 사용
Thread Lock	Redis SET NX	Python dict
이벤트 분배	Redis Streams	SSE 직접
상태 저장	Redis Cache	메모리 캐시

결론: 단일 인스턴스 환경에서는 In-Memory로 충분

Gateway 구조

flowchart TB
 subgraph GW[Gateway Service]
 Bot[Discord Bot]
 subgraph C[Core Components]
 Lock[Thread Lock]
 Cache[Message Cache]
 SSEMgr[SSE Manager]
 end
 end
 DAPI[Discord API] <--> Bot
 Bot --> Lock
 Bot --> Cache
 Bot --> SSEMgr
 SSEMgr --> Clients[WebSocket Clients]

구성요소 상세

모듈	역할	특징
Discord Bot	WebSocket 연결	자동 재연결
Thread Lock	동시성 제어	5분 타임아웃
Message Cache	메시지 보관	최대 1000개
SSE Manager	실시간 전송	모든 MCP에 브로드캐스트

4. MCP 선택 방식: 4단계 하이브리드

선택 우선순위

순위	방식	예시	설명
1	슬래시 커맨드	`/gcp status`	가장 명시적
2	@멘션	`@gcp-monitor status`	자연스러운 대화
3	키워드 감지	`gcp 서버 상태`	키워드 자동 인식
4	채널별 지정	#gcp-모니터링	채널 기본 MCP

Fallback 동작 순서

flowchart TD
 A[Message Received] --> B{Slash Command?}
 B -->|Yes| C[Route to MCP]
 B -->|No| D{Mention?}
 D -->|Yes| C
 D -->|No| E{Keyword?}
 E -->|Yes| C
 E -->|No| F{Channel Default?}
 F -->|Yes| C
 F -->|No| G[Broadcast]

슬래시 커맨드 목록

커맨드	MCP	설명
`/gcp status [server]`	gcp-mcp	GCP 서버 상태
`/gcp list`	gcp-mcp	GCP 인스턴스 목록
`/oci status [server]`	oci-mcp	OCI 서버 상태
`/oci list`	oci-mcp	OCI 인스턴스 목록
`/db query <sql>`	db-mcp	DB 쿼리 실행
`/db list`	db-mcp	DB 목록
`/alert check`	alert-mcp	알림 확인

5. Thread Lock 규칙

락 동작 방식

sequenceDiagram
 participant M1 as gcp-mcp
 participant GW as Gateway
 participant M2 as oci-mcp
 participant DT as Discord Thread

 Note over M1,DT: Lock Acquisition
 M1->>+GW: Lock request
 GW-->>-M1: Lock acquired
 M1->>DT: Send response

 Note over M2,GW: Lock Conflict
 M2->>GW: Lock request
 GW-->>M2: Lock failed

 Note over M1,GW: 5min timeout
 GW->>GW: Auto-release lock

 Note over M2,GW: Lock Retry
 M2->>+GW: Lock request
 GW-->>-M2: Lock acquired

Lock API

Method	Endpoint	설명
`POST`	`/api/threads/{id}/acquire`	락 획득
`POST`	`/api/threads/{id}/release`	락 해제
`GET`	`/api/threads/{id}/lock`	락 상태 확인

요청/응답 예시

락 획득 요청

POST /api/threads/123456/acquire
{
 "agent_name": "gcp-mcp",
 "timeout": 300
}

락 획득 응답

{
 "acquired": true,
 "thread_id": "123456",
 "agent": "gcp-mcp"
}

6. MCP 도구 (8개)

도구 목록

도구	설명	주요 파라미터
`discord_send_message`	메시지 전송	channel_id, content
`discord_get_messages`	메시지 조회	channel_id, limit
`discord_wait_for_message`	메시지 대기	channel_id, timeout
`discord_create_thread`	스레드 생성	channel_id, message_id
`discord_list_threads`	스레드 목록	channel_id
`discord_archive_thread`	스레드 아카이브	thread_id
`discord_acquire_thread`	락 획득	thread_id, agent_name
`discord_release_thread`	락 해제	thread_id, agent_name

도구 관계도

flowchart LR
 subgraph Lock[Lock Tools]
 Acquire[acquire_thread]
 Release[release_thread]
 end
 subgraph Thread[Thread Tools]
 Create[create_thread]
 List[list_threads]
 Archive[archive_thread]
 end
 subgraph Msg[Message Tools]
 Send[send_message]
 Get[get_messages]
 Wait[wait_for_message]
 end

 Acquire --> Create
 Create --> Send
 Send --> Release

사용 예시

# 메시지 전송
discord_send_message(
 channel_id="123456789",
 content="서버 상태: 정상"
)

# 스레드 생성
discord_create_thread(
 channel_id="123456789",
 message_id="987654321",
 name="상태 확인"
)

# 락 획득
discord_acquire_thread(
 thread_id="111222333",
 agent_name="gcp-mcp",
 timeout=300
)

7. 파일 구조

flowchart TB
 subgraph P[server_monitor/]
 subgraph Gw[gateway/]
 M1[main.py]
 M2[discord_ws.py]
 M3[thread_lock.py]
 M4[sse.py]
 end
 subgraph Uc[user_comm/]
 A1[agent.py]
 A2[discord_bot.py]
 A3[team_comm.py]
 end
 subgraph Mcp[discord_mcp/]
 S1[server.py]
 end
 subgraph Sh[mcp_shared/]
 MO[monitor/]
 end
 subgraph Doc[docs/]
 D1[MCP_SELECTION_STRATEGY.md]
 D2[MCP_ROUTING_POLICY.md]
 end
 end

디렉토리 설명

경로	설명
`gateway/`	Gateway Service (FastAPI)
`user_comm/`	사용자 소통 Agent
`discord_mcp/`	MCP Server (8개 도구)
`mcp_shared/`	공유 MCP 도구
`docs/`	문서

8. 실행 방법

로컬 실행

# Gateway Service 시작
uvicorn gateway.main:app --host 0.0.0.0 --port 8081

# user_comm Agent 시작 (독립 모드)
python main.py --standalone

# user_comm Agent 시작 (팀 모드)
python main.py --team server-monitor

# 헬스체크
curl http://localhost:8081/health

# 응답
{"status": "healthy", "discord_connected": true}

Claude Code MCP 설정

// ~/.claude/settings.json
{
 "mcpServers": {
 "discord-gateway": {
 "command": "python3",
 "args": ["/path/to/discord_mcp/server.py"],
 "env": {
 "GATEWAY_URL": "http://localhost:8081"
 }
 }
 }
}

9. 로드맵

Phase 1: 완료

FastAPI Gateway Service
Discord WebSocket 연결
Thread Lock (In-Memory)
SSE 브로드캐스트
MCP Server (8개 도구)

Phase 2: 진행 예정

user_comm Agent 구현
슬래시 커맨드 구현
채널별 기본 MCP 설정
키워드 자동 감지
라우팅 설정 파일

Phase 3: 선택 사항

API 인증 (API Key)
Rate Limiting
메시지 영속성 (SQLite)

결론

가벼운 아키텍처로 시작해서 필요시 확장하는 전략을 선택했다.

항목	현재	향후
상태 저장	In-Memory	SQLite (필요시)
분산 락	미사용	Redis (다중 인스턴스 시)
인증	없음	API Key (필요시)
사용자 소통	Gateway 직접	user_comm Agent

단일 인스턴스에서는 현재 구조로 충분하며, 트래픽이 늘어나면 점진적으로 확장할 계획이다. user_comm Agent를 통해 사용자와의 소통을 체계화하고, 팀 내 다른 agent들과의 협업을 효율화한다.

영어 버전: English Version

[Claude Code] 팀 에이전트 통신 아키텍처

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code 팀 에이전트 간 통신 아키텍처 설계

개요

Claude Code에서 여러 AI 에이전트가 협업할 때 효율적인 통신 방식이 필요합니다. 이 글에서는 Discord와 연동된 서버 모니터링 팀을 구축하며 설계한 통신 아키텍처를 공유합니다.

문제 정의

Claude Code에는 두 가지 유형의 에이전트가 있습니다:

Python 프로세스 (Daemon)
- Discord Gateway, user_comm_daemon 등
- 항상 실행 중, 파일 시스템 접근 가능
LLM Agent (Task로 생성)
- gcp-monitor, oci-monitor, alert-manager 등
- SendMessage 도구 사용, Claude Code 네이티브 통신

이 두 유형 간의 통신이 필요했습니다.

고려한 방식들

1. 파일 기반 메시지 큐 (기존)

장점: 구현 단순, 의존성 없음
단점: 지연 (~1초), 파일 관리 필요

2. WebSocket

장점: 실시간 양방향 통신
단점: 서버/클라이언트 구현 필요

3. gRPC

장점: 강력한 타입 체크, 스트리밍
단점: proto 파일 관리, 높은 복잡도

4. SQLite 메시지 허브 (채택)

장점: 빠름 (~10ms), 트랜잭션, 추가 의존성 없음
단점: 단일 머신에서만 동작

최종 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (직접 접근) │ │ (직접 접근) │ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub 구조

메시지 테이블

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

에이전트 상태 테이블

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

통신 방식

LLM Agent ↔ LLM Agent

SendMessage 사용 (Claude Code 네이티브)
자동 관리, idle notification 제공

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python은 직접 SQLite 접근
LLM Agent는 MCP Tool로 접근

MCP Server 구현

LLM Agent를 위한 MCP 도구들:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

메시지 플로우 예시

1. Discord 사용자: "안녕"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord 채널: "안녕하세요! 👋"

성능 비교

방식	지연 시간	안정성	복잡도
파일 기반	~1000ms	보통	낮음
WebSocket	~5ms	높음	중간
SQLite	~10ms	높음	낮음

결론

SQLite Message Hub + MCP Server 조합이 Claude Code 팀 에이전트 통신에 가장 적합했습니다:

낮은 지연: 파일 기반보다 100배 빠름
안정성: 트랜잭션으로 데이터 무결성 보장
단순함: 추가 의존성 없이 Python 내장 sqlite3 사용
유연성: Python과 LLM Agent 모두 동일한 데이터 소스 사용

코드

핵심 컴포넌트:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord 연동 게이트웨이
user_comm_daemon.py: 메시지 처리 데몬

영어 버전: English Version

[ZeroClaw] 멀티 에이전트 아키텍처 설계안

Fri, 27 Feb 2026 22:58:08 +0900

ZeroClaw 멀티 에이전트 아키텍처 설계안

개요

ZeroClaw의 멀티 에이전트 아키텍처는 단일 에이전트 모델에서 진화하는 고급 협력 시스템을 구현합니다.

현재 상태

Phase 1: In-Process Delegation (완료)
Phase 2: File-Based Multi-Agent Architecture (개발 중)

1. 설계 철학

원칙	적용
KISS	단순 통신 프로토콜
YAGNI	필수 기능만 구현
SRP	단일 책임 에이전트
Secure	최소 권한 원칙

2. 아키텍처 구조

Application Layer: Research │ Code │ Test Agent
Message Bus Layer: NATS/Redis Pub/Sub
Transport Layer: gRPC │ WebSocket │ Unix Socket

3. 에이전트 정의

agent:
 id: "researcher"
 name: "Research Agent"
 
execution:
 mode: subprocess

provider:
 name: "openrouter"
 model: "claude-sonnet-4-6"

4. CLI 명령어

zeroclaw agent list
zeroclaw agent show <id>
zeroclaw agent run --agent-id researcher

5. 보안

모드	격리	용도
Subprocess	프로세스	신뢰된 에이전트
Docker	컨테이너	파일 작업
Wasm	메모리	높은 보안

영어 버전: English Version

[ZeroClaw] 멀티 에이전트 통신 프로토콜 설계

Thu, 26 Feb 2026 23:37:59 +0900

ZeroClaw 멀티 에이전트 통신 프로토콜 설계

2026년 2월 26일 작성

개요

ZeroClaw의 멀티 에이전트 시스템을 위한 통신 프로토콜 설계안입니다.

1. 설계 목표

메시지 형식 표준화 - 일관된 봉투 기반 메시징
유연한 라우팅 - 직접, 브로드캐스트, Pub/Sub 패턴
동기 + 비동기 - 블로킹 및 논블로킹 통신 지원
이벤트 기반 조정 - 시스템 이벤트에 반응
상태 공유 - 안전한 공유 메모리 및 분산 상태

2. 메시지 타입 (12가지)

Task, TaskResult, Query, QueryResponse, Stream, Event, Heartbeat, Ack, Error, Control, Sync, SyncResponse

3. 통신 패턴

Direct (1:1)
Broadcast (1:N)
Request-Response
Pub/Sub
Streaming

4. 구현 로드맵

Phase	내용
1	핵심 메시징 레이어
2	상태 저장소
3	DelegateTool 통합
4	Pub/Sub 및 스트리밍
5	분산 환경 지원

이 문서는 ZeroClaw 개발 팀의 협업으로 작성되었습니다.

영어 버전: English Version

[ZeroClaw] 코드베이스 아키텍처 분석

Thu, 26 Feb 2026 10:07:29 +0900

ZeroClaw 코드베이스 아키텍처 분석 보고서

2026년 2월 26일 작성

개요

ZeroClaw는 Rust로 작성된 고성능 자율 에이전트 런타임입니다. 이 보고서는 코드베이스 구조와 보안 아키텍처에 대한 분석 결과를 정리합니다.

1. 핵심 아키텍처 패턴

ZeroClaw는 **트레이트 기반 확장성(Trait-driven extensibility)**을 핵심 설계 원칙으로 채택하고 있습니다.

1.1 주요 트레이트 (7개)

트레이트	위치	역할
`Provider`	src/providers/traits.rs	AI 모델 프로바이더 인터페이스
`Channel`	src/channels/traits.rs	통신 채널 인터페이스
`Tool`	src/tools/traits.rs	도구 실행 인터페이스
`Memory`	src/memory/traits.rs	메모리 백엔드 인터페이스
`Observer`	src/observability/traits.rs	관측 가능성 인터페이스
`RuntimeAdapter`	src/runtime/traits.rs	런타임 어댑터 인터페이스
`Peripheral`	src/peripherals/traits.rs	하드웨어 주변장치 인터페이스

2. 보안 아키텍처

ZeroClaw는 다층 방어(Defense-in-Depth) 전략을 통해 보안을 구현합니다.

2.1 보안 레이어 (6개)

SecurityPolicy Core - 자율성 수준 관리
Gateway Security - Bearer 토큰 인증
Tool Validation - 인젝션 방지
Runtime Sandbox - Landlock/Firejail/Docker
Secret Management - ChaCha20-Poly1305
Audit Logging - 이벤트 추적

2.2 핵심 보안 경계

명령어 허용 목록: 15개
속도 제한: 20회/시간
환경 변수: 8개만 허용

3. 멀티 에이전트 시스템

구현 로드맵

Phase	기간	내용
1	1주	코어 트레이트, DelegateTool 확장
2	2-3주	Docker/Wasm 실행 모드
3	4주+	분산 메시지 버스, 합의 알고리즘

결론

ZeroClaw는 확장성, 보안, 성능, 유지보수성 측면에서 우수한 아키텍처를 가지고 있습니다.

이 보고서는 ZeroClaw 개발 팀의 협업 분석 결과를 바탕으로 작성되었습니다.

영어 버전: English Version

[Multi-Agent] 통신 플랫폼 설계 고찰

Sat, 21 Feb 2026 21:00:00 +0900

들어가며

AI 에이전트 시스템이 발전하면서 단일 에이전트에서 멀티 에이전트 시스템으로의 전환이 가속화되고 있습니다. 이 글에서는 멀티 에이전트 간의 효율적인 통신을 위한 플랫폼 아키텍처를 설계하는 방법에 대해 고찰합니다.

1. 아키텍처 개요

멀티 에이전트 플랫폼은 크게 Orchestrator, Message Bus, 그리고 다양한 특화된 에이전트들로 구성됩니다.

Multi-Agent Architecture

핵심 컴포넌트

컴포넌트	역할
Orchestrator	태스크 조율, 에이전트 스케줄링
Message Bus	에이전트 간 통신 중계
State Store	공유 상태 관리
Task Queue	우선순위 기반 작업 큐
Agents	특화된 작업 수행

2. 통신 프로토콜 설계

에이전트 간 통신은 비동기 메시지 패싱을 기반으로 설계합니다.

Message Protocol

통신 흐름

Publish: 에이전트가 태스크 요청을 메시지 버스에 발행
Route: 버스가 적절한 에이전트에게 메시지 라우팅
Accept: 대상 에이전트가 태스크 수락
Acknowledge: 버스가 요청자에게 수락 확인
Execute: 에이전트가 실제 작업 수행
Result: 결과를 버스에 발행
Deliver: 버스가 결과를 요청자에게 전달

3. 메시지 구조

확장 가능하고 타입 안전한 메시지 구조를 설계합니다.

Message Structure

메시지 엔벌로프

{
 "header": {
 "message_id": "uuid-v4",
 "timestamp": "2026-02-21T12:00:00Z",
 "source_agent": "agent-research-01",
 "target_agent": "agent-writer-01",
 "message_type": "TASK_REQUEST"
 },
 "metadata": {
 "priority": "normal",
 "ttl": 3600,
 "correlation_id": "parent-uuid"
 },
 "payload": {
 "content_type": "json",
 "encoding": "utf-8",
 "data": {
 "task": "summarize",
 "content": "..."
 }
 }
}

메시지 타입

타입	용도
`TASK_REQUEST`	작업 요청
`TASK_RESULT`	작업 결과
`STATUS_UPDATE`	상태 변경 알림
`HEARTBEAT`	생존 확인
`QUERY`	정보 조회
`RESPONSE`	조회 응답

4. 에이전트 상태 관리

각 에이전트는 명확한 상태 머신을 가집니다.

State Management

상태 전이

IDLE → RECEIVING → PROCESSING → EXECUTING → COMPLETED → IDLE
 ↘ ↘ ↘
 ERROR ──────→ retry ──→ IDLE

상태별 동작

상태	동작
IDLE	새 태스크 대기
RECEIVING	메시지 수신 및 검증
PROCESSING	태스크 분석 및 준비
EXECUTING	실제 작업 수행
COMPLETED	결과 전송 및 정리
ERROR	오류 처리 및 재시도

5. 통신 패턴

5.1 Request-Response

동기식 1:1 통신 패턴입니다.

# Request
response = await bus.request(
 target="agent-code-01",
 message=TaskRequest(task="generate_code", spec={...}),
 timeout=30
)

# Response
return TaskResult(status="success", data=generated_code)

비동기식 1:N 통신 패턴입니다.

# Subscribe
@bus.subscribe("research.completed")
async def handle_research_result(message):
 # 연구 결과 처리
 pass

# Publish
await bus.publish(
 topic="research.completed",
 message=ResearchResult(data={...})
)

5.3 Broadcast

전체 에이전트에게 알림을 보낼 때 사용합니다.

# Broadcast
await bus.broadcast(
 message=SystemAlert(
 level="warning",
 message="High load detected"
 )
)

6. 핵심 설계 원칙

6.1 느슨한 결합 (Loose Coupling)

에이전트는 서로의 내부 구현을 알지 못해야 합니다. 메시지 인터페이스를 통해서만 통신합니다.

6.2 내결함성 (Fault Tolerance)

class Agent:
 async def execute_with_retry(self, task, max_retries=3):
 for attempt in range(max_retries):
 try:
 return await self.execute(task)
 except Exception as e:
 if attempt == max_retries - 1:
 await self.transition_to(State.ERROR)
 raise
 await asyncio.sleep(2 ** attempt) # Exponential backoff

6.3 확장성 (Scalability)

수평적 확장: 동일한 역할의 에이전트를 추가
로드 밸런싱: 메시지 버스에서 자동 분배
샤딩: 태스크 타입별로 에이전트 그룹 분리

6.4 관찰 가능성 (Observability)

# 메트릭 수집
@metrics.track
async def process_message(self, message):
 with metrics.timer("process_duration"):
 result = await self.handle(message)
 metrics.increment("messages_processed")
 return result

7. 구현 고려사항

7.1 메시지 직렬화

포맷	장점	단점
JSON	가독성, 호환성	크기, 성능
Protocol Buffers	성능, 스키마	복잡성
MessagePack	JSON 호환, 크기	도구 지원

7.2 백프레셔 (Backpressure)

class Agent:
 def __init__(self, max_concurrent=10):
 self.semaphore = asyncio.Semaphore(max_concurrent)

 async def process(self, message):
 async with self.semaphore:
 return await self.handle(message)

7.3 데드레터 큐 (Dead Letter Queue)

처리 실패한 메시지를 별도 큐로 이동시켜 분석 및 재처리합니다.

8. 결론

멀티 에이전트 통신 플랫폼은 다음 요소들이 핵심입니다:

유연한 메시지 구조: 다양한 통신 시나리오 지원
명확한 상태 관리: 예측 가능한 에이전트 동작
다양한 통신 패턴: 요청-응답, 발행-구독, 브로드캐스트
내결함성 설계: 재시도, 타임아웃, 에러 처리

이러한 원칙들을 기반으로 확장 가능하고 신뢰할 수 있는 멀티 에이전트 시스템을 구축할 수 있습니다.

참고 자료

영어 버전: English Version