분산 Agent 시스템

단일 에이전트의 한계

단일 에이전트 시스템은 단순하고 디버깅이 쉽습니다. 하지만 규모가 커지면 한계에 부딪힙니다.

단일 에이전트 한계:
- 컨텍스트 윈도우 한도 (대규모 코드베이스 처리 불가)
- 직렬 실행 (병렬 작업 불가)
- 단일 실패 지점 (에이전트 실패 시 전체 중단)
- 특화 불가 (모든 작업을 동일한 에이전트가 처리)

분산 에이전트 시스템은 이 문제를 마이크로서비스와 유사한 방식으로 해결합니다.

마이크로서비스 스타일 에이전트

각 에이전트가 명확한 책임 영역을 갖고 독립적으로 동작합니다.

에이전트 서비스 분해 예시

코드 생성 팀
├── spec-agent: 요구사항 분석, 스펙 작성
├── architect-agent: 설계 결정, 아키텍처 다이어그램
├── coder-agent: 실제 코드 구현
├── test-agent: 테스트 코드 작성
└── reviewer-agent: 코드 리뷰, 피드백

에이전트 서비스 인터페이스

agents/base-agent-service.ts

interface AgentServiceConfig {
  name: string
  version: string
  capabilities: string[]
  model: string
  maxConcurrency: number
  timeoutMs: number
}

interface AgentTask {
  id: string
  type: string
  payload: Record<string, unknown>
  priority: 'low' | 'normal' | 'high'
  deadline?: Date
}

interface AgentResult {
  taskId: string
  success: boolean
  output: unknown
  tokensUsed: number
  durationMs: number
  error?: string
}

abstract class BaseAgentService {
  constructor(protected config: AgentServiceConfig) {}

  abstract canHandle(task: AgentTask): boolean
  abstract execute(task: AgentTask): Promise<AgentResult>

  async handleWithTimeout(task: AgentTask): Promise<AgentResult> {
    const timer = new Promise<AgentResult>((_, reject) =>
      setTimeout(
        () => reject(new Error(`Task timeout after ${this.config.timeoutMs}ms`)),
        this.config.timeoutMs
      )
    )
    return Promise.race([this.execute(task), timer])
  }
}

이벤트 드리븐 아키텍처

에이전트들이 직접 통신하는 대신 이벤트 버스를 통해 느슨하게 결합됩니다.

이벤트 버스 패턴

개발자 작업 요청
      ↓
  EventBus.publish('task.created', taskData)
      ↓
  ┌───────────────────────────────────┐
  │            Event Bus              │
  └───────────────────────────────────┘
      ↓             ↓              ↓
spec-agent    coder-agent    reviewer-agent
(구독 중)      (구독 중)       (구독 중)

각 에이전트가 관련 이벤트만 처리

이벤트 버스 구현

harness/event-bus.ts

type EventHandler<T = unknown> = (event: AgentEvent<T>) => Promise<void>

interface AgentEvent<T = unknown> {
  id: string
  type: string
  payload: T
  timestamp: Date
  source: string
  correlationId?: string
}

class AgentEventBus {
  private handlers: Map<string, EventHandler[]> = new Map()
  private eventLog: AgentEvent[] = []

  subscribe<T>(eventType: string, handler: EventHandler<T>): () => void {
    const existing = this.handlers.get(eventType) ?? []
    this.handlers.set(eventType, [...existing, handler as EventHandler])

    // 구독 취소 함수 반환
    return () => {
      const current = this.handlers.get(eventType) ?? []
      this.handlers.set(
        eventType,
        current.filter(h => h !== handler)
      )
    }
  }

  async publish<T>(eventType: string, payload: T, source: string): Promise<void> {
    const event: AgentEvent<T> = {
      id: crypto.randomUUID(),
      type: eventType,
      payload,
      timestamp: new Date(),
      source
    }

    this.eventLog.push(event as AgentEvent)

    const handlers = this.handlers.get(eventType) ?? []
    await Promise.all(handlers.map(h => h(event as AgentEvent)))
  }

  getEventLog(filter?: { type?: string; since?: Date }): AgentEvent[] {
    return this.eventLog.filter(e => {
      if (filter?.type && e.type !== filter.type) return false
      if (filter?.since && e.timestamp < filter.since) return false
      return true
    })
  }
}

이벤트 로그의 중요성

이벤트 버스의 이벤트 로그는 분산 시스템 디버깅의 핵심 도구입니다. 어떤 에이전트가 어떤 순서로 어떤 이벤트를 처리했는지 추적할 수 있어야 합니다. 프로덕션에서는 이벤트 로그를 외부 스토리지(Redis, Kafka)에 영구 저장하세요.

오케스트레이터 패턴

복잡한 작업을 여러 에이전트에게 분배하고 결과를 집계하는 오케스트레이터가 필요합니다.

harness/orchestrator.ts

interface SubTask {
  agentType: string
  task: AgentTask
  dependsOn?: string[] // 다른 서브태스크 ID
}

class AgentOrchestrator {
  constructor(
    private agents: Map<string, BaseAgentService>,
    private eventBus: AgentEventBus
  ) {}

  async executeWorkflow(subtasks: SubTask[]): Promise<Map<string, AgentResult>> {
    const results = new Map<string, AgentResult>()
    const pending = new Map(subtasks.map(st => [st.task.id, st]))

    while (pending.size > 0) {
      // 의존성이 모두 완료된 태스크 찾기
      const ready = [...pending.values()].filter(st =>
        (st.dependsOn ?? []).every(dep => results.has(dep))
      )

      if (ready.length === 0) {
        throw new Error('순환 의존성 감지: 실행 불가능한 워크플로우')
      }

      // 준비된 태스크 병렬 실행
      await Promise.all(
        ready.map(async st => {
          const agent = this.agents.get(st.agentType)
          if (!agent) throw new Error(`에이전트 미발견: ${st.agentType}`)

          const result = await agent.handleWithTimeout(st.task)
          results.set(st.task.id, result)
          pending.delete(st.task.id)

          await this.eventBus.publish('subtask.completed', result, 'orchestrator')
        })
      )
    }

    return results
  }
}

분산 vs 중앙화 결정 가이드

기준	중앙화 선택	분산화 선택
팀 규모	1~5명	10명 이상
작업 복잡도	단순, 순차적	복잡, 병렬 가능
컨텍스트 크기	단일 컨텍스트로 충분	다수의 대용량 컨텍스트 필요
실패 허용도	단순 재시도로 충분	부분 실패 허용 필요
운영 복잡도	낮게 유지 선호	복잡도 수용 가능

분산 시스템의 복잡성

분산 에이전트 시스템은 단일 에이전트보다 훨씬 복잡합니다. 네트워크 지연, 부분 실패, 이벤트 순서 보장, 중복 처리 방지 등 분산 시스템 고유의 문제가 모두 발생합니다. 정말 필요할 때만 분산 아키텍처를 선택하세요. 대부분의 팀은 단일 또는 소수의 에이전트로 충분합니다.

스케일링 패턴

수평 확장

동일한 에이전트를 여러 인스턴스로 실행합니다.

harness/agent-pool.ts

class AgentPool {
  private instances: BaseAgentService[] = []
  private queue: AgentTask[] = []
  private activeCount = 0

  constructor(
    private factory: () => BaseAgentService,
    private maxInstances: number
  ) {
    // 초기 인스턴스 생성
    for (let i = 0; i < Math.min(2, maxInstances); i++) {
      this.instances.push(factory())
    }
  }

  async submit(task: AgentTask): Promise<AgentResult> {
    if (this.activeCount < this.maxInstances) {
      return this.executeImmediate(task)
    }
    return this.enqueue(task)
  }

  private async executeImmediate(task: AgentTask): Promise<AgentResult> {
    this.activeCount++
    const agent = this.instances[this.activeCount - 1] ?? this.factory()

    try {
      return await agent.handleWithTimeout(task)
    } finally {
      this.activeCount--
      this.processQueue()
    }
  }

  private enqueue(task: AgentTask): Promise<AgentResult> {
    return new Promise((resolve, reject) => {
      this.queue.push({ ...task, _resolve: resolve, _reject: reject } as AgentTask & {
        _resolve: (r: AgentResult) => void
        _reject: (e: Error) => void
      })
    })
  }

  private processQueue(): void {
    const next = this.queue.shift() as (AgentTask & {
      _resolve?: (r: AgentResult) => void
    }) | undefined
    if (next && next._resolve) {
      this.executeImmediate(next).then(next._resolve)
    }
  }
}

요약

분산 에이전트 시스템은 단일 에이전트의 컨텍스트 한계와 직렬 실행 제약을 극복합니다. 이벤트 드리븐 아키텍처로 에이전트 간 느슨한 결합을 유지하고, 오케스트레이터 패턴으로 복잡한 워크플로우를 관리하세요. 하지만 분산 시스템의 복잡성은 실제로 필요한 팀에게만 정당화됩니다. 단순함을 기본값으로 유지하세요.