/Part 5: 멀티 에이전트/코디네이터와 스웜
🤝
Part 5고급⏱ 약 50분 · 2개 섹션

코디네이터와 스웜

에이전트 군단의 지휘

코디네이터와 스웜 대표 이미지
이 챕터에서 배울 것
  • 코디네이터는 Agent, TaskStop, SendMessage, SyntheticOutput만 사용
  • 워커는 제한된 도구 풀로 독립 실행
  • 스웜은 UDS/인프로세스 통신으로 에이전트 간 메시지 전달
전체 아키텍처에서 현재 위치
⚙️코어 엔진
🔧도구 시스템
🛡️보안
🧠컨텍스트
🤝멀티 에이전트
🌐생태계
인프라
1

코디네이터 모드

코디네이터-워커 아키텍처와 도구 접근 제어

코디네이터워커도구 제한태스크 알림|coordinator/coordinatorMode.ts

코디네이터 모드는 CLAUDE_CODE_COORDINATOR_MODE 환경변수로 활성화됩니다. 코디네이터는 워커를 생성하고 조율하는 역할만 수행합니다.

src/coordinator/coordinatorMode.ts
1// src/coordinator/coordinatorMode.ts — 핵심 구현
2
3const INTERNAL_WORKER_TOOLS = new Set([💡
4 TEAM_CREATE_TOOL_NAME,
5 TEAM_DELETE_TOOL_NAME,
6 SEND_MESSAGE_TOOL_NAME,
7 SYNTHETIC_OUTPUT_TOOL_NAME,
8])
9
10export function isCoordinatorMode(): boolean {💡
11 if (feature('COORDINATOR_MODE')) {
12 return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
13 }
14 return false
15}
16
17// 세션 재개 시 모드 일치 확인
18export function matchSessionMode(
19 sessionMode: 'coordinator' | 'normal' | undefined,
20): string | undefined {
21 const currentIsCoordinator = isCoordinatorMode()
22 const sessionIsCoordinator = sessionMode === 'coordinator'
23 if (currentIsCoordinator === sessionIsCoordinator) return undefined
24 // 환경변수를 동적으로 변경하여 모드 전환
25 if (sessionIsCoordinator) {
26 process.env.CLAUDE_CODE_COORDINATOR_MODE = '1'
27 } else {
28 delete process.env.CLAUDE_CODE_COORDINATOR_MODE
29 }
30 return sessionIsCoordinator
31 ? 'Entered coordinator mode to match resumed session.'
32 : 'Exited coordinator mode to match resumed session.'
33}
34
35// 워커에게 보이는 도구 목록 생성
36export function getCoordinatorUserContext(mcpClients, scratchpadDir) {
37 if (!isCoordinatorMode()) return {}💡
38 const workerTools = Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
39 .filter(name => !INTERNAL_WORKER_TOOLS.has(name))
40 .sort()
41 .join(', ')
42 return { workerCapabilities: `Workers have access to: ${workerTools}` }
43}
2

스웜 통신

에이전트 간 메시지 전달과 팀 관리

UDS 백엔드인프로세스 백엔드메시지 라우팅인박스 폴링|utils/swarm/swarm.tstools/SendMessageTool/SendMessageTool.ts

스웜 시스템은 에이전트 간 메시지 전달을 담당합니다. UDS(Unix Domain Socket) 또는 인프로세스 백엔드를 사용합니다.

스웜 통신 메커니즘
1// 스웜 통신 패턴
2
3// SendMessageTool → 에이전트 간 메시지 전달
4SendMessage({ to: "worker-1", content: "파일 분석 완료" })
5
6// useInboxPoller → 수신 메시지 폴링
7// 각 에이전트는 자신의 인박스를 주기적으로 확인
8const messages = await pollInbox(agentId)
9
10// 팀 기반 라우팅
11// agentId@teamName 형태로 에이전트 식별
12// 같은 팀 내에서만 메시지 전달 가능
13
14// 인프로세스 백엔드 (InProcessTeammateTask)
15// AsyncLocalStorage로 격리된 컨텍스트
16// 대기 중 메시지 큐 (pendingMessages)
17// 정상 종료 지원 (requestShutdown)