멀티 에이전트 하네스 개념

멀티 에이전트 하네스의 핵심 개념을 배웁니다. 에이전트, 스킬, PM 오케스트레이션, 3-Tier 전략, PM Gateway, 디스패치 흐름, 핸드오프 계약 — 이 장에서 하네스의 모든 뼈대를 이해합니다.

에이전트란

에이전트의 정의

에이전트(Agent)는 특정 역할을 부여받고, 정해진 행동 지침에 따라 작업을 수행하는 AI 어시스턴트입니다. 일반적인 챗봇과 달리, 에이전트는 자신만의 이름, 역할, 행동 규칙을 가지며, 파일을 읽고 쓰고, 도구를 사용할 수 있는 권한이 부여됩니다.

1장에서 비유했듯, 에이전트는 회사의 직원과 같습니다. PM은 팀장이고, 전문 에이전트는 각 부서의 전문가입니다. 기획 담당 에이전트, 디자인 담당 에이전트, 코딩 담당 에이전트가 각자 맡은 바를 수행하면 전체 프로젝트가 효율적으로 진행됩니다.

에이전트의 구성 요소

각 에이전트는 네 가지 핵심 요소로 구성됩니다. 이 네 가지가 모여 하나의 에이전트를 정의합니다.

구체적으로 설명하면 다음과 같습니다.

하네스 내 에이전트 유형

코덱 하네스는 프레젠테이션 파이프라인의 각 단계별로 책임지는 여러 전문 에이전트를 정의합니다.

에이전트 파일 예시

아래는 에이전트 정의 파일이 어떤 모습인지 보여주는 단순화된 예시입니다. 실제 파일은 훨씬 더 많은 세부 사항을 담고 있지만, 이 예시로 전체적인 감을 잡을 수 있습니다.

# agents/research.md
---
name: research
tier: medium
phases: 1
role: >
  웹 자료를 수집하고 스토리라인 설계를 위한
  research_notes.md를 작성합니다.
dispatch_triggers:
  - "주제를 조사해줘"
  - "자료를 수집해줘"
  - "리서치 노트를 작성해줘"
---
## Instructions
- 한국어와 영어 자료를 모두 검색합니다.
- 조사 결과를 research_notes.md에 작성합니다.
- URL, 핵심 사실, 출처 신뢰도 메모를 포함합니다.
- 슬라이드 콘텐츠는 만들지 않습니다 — 이는 storyline 에이전트의 역할입니다.

이 파일이 에이전트가 무엇을 하는지(role), 언제 디스패치되는지(dispatch_triggers), 무엇을 하면 안 되는지(Instructions의 금지 규칙)를 명확히 정의하고 있다는 점에 주목하세요. 이러한 명확성이 멀티에이전트 협업을 안정적으로 작동하게 만드는 핵심입니다.

스킬이란

스킬의 정의

스킬(Skill)은 에이전트가 수행할 수 있는 재사용 가능한 워크플로우입니다. 에이전트가 "누구"라면, 스킬은 그 에이전트가 "무엇을 하는지"를 정의합니다. 하나의 스킬은 여러 단계(steps)로 구성된 작업 절차이며, 특정 트리거(trigger)에 의해 자동으로 활성화됩니다.

쉽게 말해, 에이전트가 요리사라면 스킬은 요리 레시피입니다. 요리사(에이전트)는 여러 요리 레시피(스킬)를 가지고 있으며, 주문이 들어오면(트리거) 해당 레시피에 따라 요리를 준비합니다.

스킬의 구성 요소

각 스킬은 다음 네 가지 요소로 구성됩니다.

스킬 vs 에이전트

에이전트와 스킬은 자주 혼동되지만, 뚜렷한 차이가 있습니다.

스킬의 계층 구조

co-deck에서는 스킬이 세 가지 위치에 정의될 수 있으며, 우선순위가 다릅니다.

PM 오케스트레이션

PM(Project Manager) 에이전트의 역할

PM 에이전트는 멀티 에이전트 하네스의 중심이자 단일 창구(Single Point of Entry)입니다. 사용자는 PM에게만 직접 요청을 하고, PM이 요청을 분석하여 적절한 전문 에이전트를 선택하고 작업을 할당합니다.

PM의 핵심 역할을 단계별로 정리하면 다음과 같습니다.

PM 오케스트레이션 흐름도

PM은 직접 실행하지 않는다

PM의 가장 중요한 특징은 직접 파일을 작성하거나 코드를 실행하지 않는다는 점입니다. PM은 오케스트레이터(지휘자)로서 전문 에이전트들에게 작업을 지시할 뿐, 스스로 결과물을 만들지 않습니다.

이 규칙이 중요한 이유는 다음과 같습니다.

• 책임 소재의 명확화 — 어떤 결과물에 문제가 있으면, 그 분야의 전문 에이전트가 수정합니다. PM이 직접 만든 파일이라면 "PM이 수정해야 할지 전문 에이전트가 수정해야 할지" 혼란이 생깁니다.
• 전문성의 보장 — 각 분야는 전문 에이전트가 가장 잘 알고 있습니다. PM이 디자인 파일을 직접 만들면 전문성이 떨어질 수 있습니다.
• 거버넌스 분리 — 조율(관리)과 실행(작업)을 분리하면 시스템이 더 안정적으로 동작합니다. 인간 조직에서도 관리자와 실무자의 역할이 분리되는 것과 같은 원리입니다.

품질 게이트

파이프라인의 특정 지점에서 PM은 작업을 일시 중지하고 검토를 위해 결과물을 제시합니다. 이러한 체크포인트를 게이트라고 부릅니다. 게이트에는 두 가지 유형이 있습니다.

• 필수 게이트 — 명시적으로 승인하기 전까지는 파이프라인이 진행될 수 없습니다. 게이트 2(콘텐츠 준비 완료 후)와 게이트 5(샘플 PDF 생성 후)는 필수입니다.
• 선택 게이트 — PM이 요약을 보여준 후 자동으로 계속 진행됩니다. 게이트 1.5(소스 검증), 게이트 3(디자인 사양), 그리고 게이트 4(HTML 초안)는 선택 사항입니다.

3-Tier 전략

왜 여러 AI 모델이 필요한가?

AI 모델은 성능이 높을수록 비용도 높아집니다. 복잡한 설계 작업에 최고급 모델을 사용하면 좋은 결과를 얻을 수 있지만, 간단한 파일 검색이나 스크립트 실행에도 최고급 모델을 쓰면 비효율적입니다.

이러한 비용과 성능의 균형을 맞추기 위해, 하네스는 AI 모델을 세 가지 계층(Tier)으로 나누어 할당합니다. 마치 회사에 수석 엔지니어, 시니어, 주니어가 있는 것처럼, 작업의 복잡도에 따라 적절한 모델을 선택합니다.

세 가지 티어

3-Tier 비교표

핵심 규칙

위 비교표와 함께 기억해야 할 3-Tier 전략의 핵심 규칙은 다음과 같습니다.

• 티어는 낮출 수 있지만 올릴 수는 없다. PM은 단순한 작업의 비용을 아끼기 위해 더 낮은 티어의 모델을 배정할 수 있지만, 에이전트에게 정의된 기본 티어보다 높은 모델을 배정할 수는 없습니다. 낮춘 티어에서 작업이 실패하면, 재시도 시에는 반드시 에이전트의 기본 티어를 복원합니다.
• 오케스트레이터는 항상 High 티어를 사용한다. PM은 어떤 에이전트를 디스패치할지, 어떤 순서로 실행할지 같은 가장 중요한 결정을 내리므로, 항상 가장 높은 추론 수준에서 동작합니다.
• 검토자는 독립적이어야 한다. 작업을 수행한 에이전트가 그 결과물을 검토하는 일은 없습니다. 이러한 분리는 별도의 QA 팀을 두는 것과 같은 원리로, 실질적인 품질 관리를 보장합니다.

PM Gateway

PM Gateway의 정의

PM Gateway는 모든 전문 에이전트가 PM을 통해서만 호출되도록 강제하는 규칙입니다. 사용자는 PM에게만 요청하고, PM이 적절한 전문 에이전트를 선택하여 작업을 위임합니다. 사용자가 전문 에이전트(예: research, design)에게 직접 요청하는 것은 허용되지 않습니다.

이 규칙은 "왜" 필요할까요? 세 가지 핵심 이유가 있습니다.

• 통제 (Control) — 모든 요청이 PM을 거치면, 전체 작업의 흐름을 한 곳에서 관리할 수 있습니다. 여러 전문 에이전트가 동시에 같은 파일을 수정하거나 충돌하는 작업을 수행하는 것을 방지합니다.
• 일관성 (Consistency) — PM이 요청의 우선순위를 결정하고, 적절한 순서로 에이전트를 배치합니다. 이를 통해 프로젝트 전체가 일관된 흐름을 유지합니다.
• 품질 (Quality) — 각 단계에서 PM이 결과물을 검토하고, 다음 단계로 진행할지 수정을 요청할지 결정합니다. 이를 통해 최종 결과물의 품질이 보장됩니다.

왜 게이트웨이인가?

모든 직원이 자유롭게 CEO에게 찾아가 지시를 내릴 수 있는 회사를 상상해 보세요. 큰 혼란이 생길 것입니다. 하네스에서도 마찬가지입니다. 사용자가 design이나 research 같은 전문 에이전트를 직접 호출할 수 있다면, PM은 워크플로우를 계획하고 순서를 정하고 품질을 검토하는 능력을 잃게 됩니다. 게이트웨이는 바로 이것을 막아줍니다.

게이트웨이 동작 방식

PM Gateway는 네 겹의 방어선으로 강제됩니다. 여러 층위의 방어(defense in depth)가 서로를 보완합니다.

바로 다음에 이어지는 섹션에서는 이 네 단계 강제 계층을 다이어그램으로 확인할 수 있습니다.

4단계 강제 계층

PM Gateway는 네 가지 수준에서 강제됩니다. 이 중 어느 하나라도 위반되면 전문 에이전트는 실행되지 않습니다.

PM 직접 실행 범위

PM 자체에도 직접 수행할 수 있는 작업에 대한 제한 사항이 있습니다.

디스패치 흐름

디스패치란?

디스패치(Dispatch)는 PM이 전문 에이전트에게 작업을 할당하는 과정을 의미합니다. 사용자의 요청이 들어오면, PM은 요청의 성격을 분석(트라이어지, Triage)하고, 적절한 전문 에이전트를 선택하여 작업을 지시합니다.

병렬 디스패치 vs 순차 디스패치

디스패치에는 두 가지 모드가 있습니다. 작업의 성격에 따라 적절한 모드가 선택됩니다.

디스패치 흐름도

디스패치 의사결정 흐름

PM이 요청을 받은 후, 어떤 방식으로 디스패치할지 결정하는 과정은 다음과 같습니다.

핸드오프 계약

핸드오프란?

핸드오프(Handoff)는 에이전트 간에 작업 결과를 전달하는 방식을 의미합니다. 멀티 에이전트 하네스에서는 한 에이전트가 완료한 결과물이 다음 에이전트의 입력으로 사용됩니다. 이때 "어떤 형식으로", "어떤 경로에", "어떤 품질 기준을 만족시켜" 전달할지 미리 정의해 두어야 합니다. 이러한 약속을 핸드오프 계약(Handoff Contract)이라고 부릅니다.

핸드오프 계약의 3요소

핸드오프 계약은 세 가지 핵심 요소로 구성됩니다.

핸드오프 예시: research → storyline

co-deck에서 가장 대표적인 핸드오프는 research 에이전트에서 storyline 에이전트로의 전달입니다.

위 다이어그램에서 볼 수 있듯, research 에이전트가 research_notes.md라는 형식으로 출력하면, storyline 에이전트가 동일한 파일을 입력으로 받아 자신의 작업을 수행합니다. 이때 research_notes.md의 경로, 파일 이름, 내부 구조(마크다운 형식, 섹션 구성 등)가 핸드오프 계약에 의해 미리 정의되어 있어야 합니다.

핸드오프 계약이 중요한 이유

• 오류 방지 — 파일 이름이 틀리거나 경로가 잘못되면, 다음 에이전트가 입력을 찾지 못해 전체 파이프라인이 중단됩니다. 핸드오프 계약이 있으면 이런 실수를 방지할 수 있습니다.
• 독립성 보장 — 에이전트 간의 의존 관계가 명확해지면, 각 에이전트를 독립적으로 개발하고 테스트할 수 있습니다. "입력이 A면 출력이 B"라는 약속만 지키면 되므로, 내부 구현을 자유롭게 변경할 수 있습니다.
• 대체 가능성 — 핸드오프 계약만 지키면, 특정 에이전트를 다른 에이전트로 교체할 수 있습니다. 예를 들어 research 에이전트를 더 성능이 좋은 버전으로 바꿔도, 출력 형식이 같으면 storyline 에이전트는 아무 변경 없이 그대로 동작합니다.

하네스 아키텍처 전체도

이 장에서 설명한 모든 개념을 하나의 그림으로 정리해 보겠습니다. 다음은 co-deck 하네스의 전체 아키텍처를 나타낸 다이어그램입니다.