Blog로컬에서 AI 멀티 에이전트 만들기 (3) — 실전과 확장

로컬에서 AI 멀티 에이전트 만들기 (3) — 실전과 확장

시리즈 (3편 중 3편)

편제목핵심
1편설계와 환경 구성AgentEngine 추상화, CLI/API 팩토리
2편에이전트 구현EventBus, Orchestrator, 3개 에이전트
→ 3편실전과 확장실행 결과, 피드백 루프, 비용 최적화

1편에서 설계, 2편에서 구현을 마쳤다. 이제 실행하고, 결과를 분석하고, 프로덕션까지 확장하는 방법을 본다.

파이프라인 실행

실행

터미널 1: 워커 시작

docker compose up -d   # Redis
npm start              # 워커 + 오케스트레이터
Starting agent-basic...
  Redis: redis://localhost:6379
  Engine: claude-cli
[orchestrator] Listening for events...
All workers started. Waiting for tasks...

터미널 2: 태스크 실행

npm run task -- "React로 간단한 카운터 앱 만들어줘"

실제 실행 결과:

[orchestrator] task.created → planner-queue

[planner] Starting: "React로 간단한 카운터 앱 만들어줘"
[planner] Plan created: React 카운터 앱
[planner]   Steps: 7, Files: 8
[planner]   Duration: 7598ms
[orchestrator] plan.completed → coder-queue

[coder] Starting: "React 카운터 앱"
[coder] Code written
[coder]   Duration: 106699ms
[orchestrator] code.completed → reviewer-queue

[reviewer] Starting review
[reviewer] Verdict: APPROVE (8/10)
[reviewer]   Feedback: A clean, correct React + TypeScript counter app.
              The project structure, tooling (Vite, strict TypeScript),
              component separation, and styling are all solid.
              Minor suggestions: use functional state updates (prev => prev + 1)
              and add a .gitignore.
[reviewer]   Duration: 42860ms
============================================================
PIPELINE COMPLETE
  Verdict: approve (8/10)
============================================================

결과 분석

에이전트별 성능

에이전트시간역할
Planner~8초계획 JSON 생성 (7 steps, 8 files)
Coder~107초실제 파일 생성 (Claude CLI)
Reviewer~43초코드 리뷰 (8/10 APPROVE)
합계~158초 (~2.5분)

Claude Max 구독이라 비용은 $0이지만, API 모드에서는 Planner/Reviewer가 각 $0.0030.005, Coder가 $0.050.10 정도다. 시간의 68%가 Coder에 집중된다. Planner와 Reviewer는 텍스트만 생성하지만, Coder는 도구를 사용해서 파일을 만들기 때문이다.

생성된 파일 확인

ls output/2026-02-19T14-30-00/
# package.json  src/  public/  ...

Claude CLI 엔진을 쓰면 실제로 동작하는 프로젝트가 나온다. npm install && npm start로 바로 실행 가능.

엔진 전환: API로 바꿔보기

# .env
ENGINE_TYPE=anthropic-api
ANTHROPIC_API_KEY=sk-ant-...

API 엔진으로 전환하면:

  • Planner/Reviewer: 거의 동일하게 동작
  • Coder: 파일을 직접 생성하지 못하고, 코드를 텍스트로 반환

사용 시나리오:

  • 프로토타입/테스트: API 엔진 (빠르고 저렴)
  • 실제 코드 생성: CLI 엔진 (도구 사용 가능)
  • 하이브리드: Planner/Reviewer는 API, Coder만 CLI

에이전트별로 엔진을 다르게 설정하는 것도 config.ts를 수정하면 된다.

확장 포인트

피드백 루프

1. 피드백 루프

현재는 Planner → Coder → Reviewer로 단방향이다. Reviewer가 suggest를 반환하면?

// orchestrator.ts에 추가
await this.eventBus.subscribe("review.completed", async (event) => {
  if (event.payload.verdict === "suggest") {
    await this.coderQueue.add("code", {
      ...event.payload,
      feedback: event.payload.feedback,  // 피드백 포함
    });
  }
});

이 3줄로 자동 수정 루프가 완성된다. codemon-make에서는 QA 실패 시 최대 2회 재시도한다.

2. 승인 게이트

프로덕션에서는 자동 실행이 위험할 수 있다. 사람이 확인하는 단계를 추가:

await this.eventBus.subscribe("plan.completed", async (event) => {
  // 자동 모드면 바로 진행
  if (config.approvalMode === "auto") {
    await this.coderQueue.add("code", event.payload);
  }
  // 수동 모드면 승인 대기
  // → UI나 CLI에서 approve 이벤트를 발행
});

3. 모델 분리

에이전트마다 다른 모델을 사용해서 비용을 최적화:

PLANNER_MODEL=claude-haiku-4-5-20251001   # 저렴, 계획에 충분
CODER_MODEL=claude-sonnet-4-20250514      # 코딩 성능 필요
REVIEWER_MODEL=claude-haiku-4-5-20251001  # 저렴, 리뷰에 충분

codemon-make에서 실제로 이 전략을 쓴다. 비용이 40% 이상 절감된다.

4. 에이전트 추가

새 에이전트를 추가하려면:

  1. src/agents/tester-agent.ts 생성
  2. src/workers/tester-worker.ts 생성
  3. Orchestrator에 이벤트 라우팅 1줄 추가

기존 에이전트를 수정할 필요가 없다. 이것이 이벤트 기반 아키텍처의 장점.

agent-basic vs codemon-make

agent-basiccodemon-make
에이전트 수37
DB없음 (파일시스템)PostgreSQL + Drizzle
이벤트3개10개+
승인없음auto/manual 모드
GitHub없음PR 생성, 브랜치 관리
QA리뷰만자동 테스트 + 재시도
배포없음Preview Deploy

agent-basic은 패턴을 이해하기 위한 최소 구현이다. 프로덕션으로 가려면 DB, GitHub 연동, QA 루프가 필요하다. 하지만 핵심 아키텍처는 동일하다.

배운 점

1. 프로세스 > 프롬프트

멀티 에이전트에서 가장 중요한 것은 프롬프트 엔지니어링이 아니라 프로세스 설계다. 어떤 순서로, 어떤 데이터를 넘기고, 실패하면 어떻게 할 것인가. 이 구조가 탄탄하면 프롬프트는 간단해도 된다.

2. 역할 분리의 힘

Planner가 나쁜 계획을 만들면 Planner만 고치면 된다. Coder가 버그를 만들면 Reviewer가 잡는다. 단일 에이전트에서는 불가능한 디버깅이 멀티 에이전트에서는 자연스럽다.

3. 추상화는 투자다

AgentEngine 인터페이스를 만드는 데 30분이 걸렸다. 이후로 CLI/API 전환, 모델 교체, 새 엔진 추가에 걸리는 시간은 각각 1분이다. 초기 추상화가 나중에 수백 배로 돌아온다.

4. 이벤트 버스는 과소평가된다

47줄의 EventBus가 전체 시스템의 확장성을 결정한다. 에이전트끼리 직접 호출했다면 새 에이전트를 추가할 때마다 기존 코드를 수정해야 했을 것이다.

마무리

3편에 걸쳐 BullMQ + Redis + Claude로 멀티 에이전트 시스템을 만들었다.

핵심은 간단하다:

  1. 엔진으로 LLM을 추상화하고
  2. 이벤트로 에이전트를 연결하고
  3. 큐로 작업을 관리한다

이 3가지 패턴만 있으면 에이전트가 3개든 30개든 같은 방식으로 확장할 수 있다.

전체 코드: github.com/codemon-ai/agent-basic

← 이전: 2편 — 에이전트 구현

질문이나 피드백은 GitHub Issues로.

로컬에서 AI 멀티 에이전트 만들기 (2) — 에이전트 구현AI 봇에게 파일 정리를 맡겼더니 — 옵시디언 + iCloud + 에이전트 자동화 실전기