멀티 에이전트

지도 위치 : 3일차 · README 4장의 ⑤ 협업 층(마무리) | 이전: 21차시 전문 에이전트 구현 | 다음: 23차시 Human-in-the-Loop 키워드 : Supervisor 패턴, 위임, 응답 종합

이 차시를 다 읽으면

1. 오케스트레이션과 Supervisor 패턴을 유와 종차로 정의하고 그림으로 그릴 수 있다.
2. 위임의 두 방식(다음 담당 고르기 ↔ 전문 에이전트를 도구처럼 호출)을 구별할 수 있다.
3. Planner-Worker(20차시)와 Supervisor를 "미리 계획 ↔ 매번 판단" 으로 가를 수 있다.
4. StateGraph로 Supervisor를 만드는 원리(관리 노드 + 조건부 엣지 + 돌아오는 엣지)를 코드에서 짚을 수 있다.
5. 응답을 종합할 때 출처를 유지하고 모순을 처리 하며, 총 반복 · 총 비용 상한을 코드로 걸 수 있다.
6. 실행 추적으로 누가 무엇을 했는지 검수할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "전문 에이전트 여럿에게 누가, 어떤 순서로 일을 맡기고, 결과를 어떻게 하나의 답으로 묶나?" 입니다. 앞 차시(21차시)에서 인사 · IT · 규정 에이전트를 계약(AgentRequest → AgentResult)으로 만들었습니다. 이번에는 그들을 지휘하는 자리를 만듭니다. README 5.2 중심 축에서 이 과정이 가장 오른쪽 까지 가는 차시입니다.

---

1. 오케스트레이션과 Supervisor 패턴

1.1 정의

오케스트레이션 — [멀티에이전트의 운영 방식]인데, [ 여러 에이전트의 실행 순서 · 일 배분 · 결과 모음을 한 곳에서 조율한다 ]는 점에서 에이전트끼리 직접 말을 주고받는 분산 협업과 구별된다.

Supervisor 패턴 — [오케스트레이션 패턴]인데, [ 관리 에이전트(LLM)가 매 단계 결과를 보고 다음에 일할 전문 에이전트를 고르며, 끝낼 때를 스스로 정한다 ]는 점에서 실행 전에 작업 목록을 확정하는 Planner-Worker와 구별된다.

                  사용자 요청
                      ↓
              ┌──[supervisor]──┐       ← 매번 "다음은 누구?" 또는 "끝"
              │   ↑    ↑    ↑  │
         ┌────┘   │    │    │  └──── FINISH → [종합] → 답
         ↓        │    │    │
       [hr] ──────┘    │    │        ← 일이 끝나면 늘 supervisor로 돌아옴
       [it] ───────────┘    │
     [policy] ──────────────┘

1.2 반례 — 이건 Supervisor가 아닙니다

💡 비유 (기억 보조용) — 오케스트라의 지휘자 . 지휘자는 악기를 연주하지 않고, 지금 어느 파트가 들어갈지 매 순간 정합니다. 악보(계획)를 미리 나눠 주는 편곡자(Planner)와는 일하는 시점이 다릅니다.

---

2. 위임 — 두 가지 방식

위임 — [제어 넘기기]인데, [ 관리 에이전트가 하위 에이전트에게 일과 필요한 맥락을 넘기고 결과를 받는다 ]는 점에서 관리 에이전트가 직접 도구를 쓰는 것과 구별된다.

두 방식 모두 누가 흐름을 정하는가의 오른쪽 입니다. 다음 담당을 모델이 고르기 때문입니다. 다만 (가)는 갈 수 있는 길을 그래프가, (나)는 쓸 수 있는 도구 목록을 코드가 정해 두었다는 점에서 완전한 자유는 아닙니다. 이 노트는 23차시의 멈춤 · 재개와 이어지도록 (가)로 설명합니다.

---

3. 미리 계획 ↔ 매번 판단 — Planner-Worker와의 경계

⭐ 둘 중 하나만 고를 필요는 없습니다. 오피스봇은 복합 요청이 미리 보이면 Planner, 결과에 따라 흐름이 갈리면 Supervisor 로 보내도 됩니다. 판단 기준은 이번에도 문장 1 — 더 예측 가능한 쪽(왼쪽)으로 충분하면 오른쪽으로 가지 않습니다.

---

4. StateGraph로 구현하는 원리

세 부품만 있으면 됩니다. supervisor 노드 (다음 담당을 고름) + 조건부 엣지 (고른 담당에게 보냄, 19차시) + 돌아오는 엣지 (담당이 끝나면 supervisor로).

import operator
from typing import Annotated, Literal, TypedDict
from pydantic import BaseModel

class Decision(BaseModel):
    next: Literal["hr", "it", "policy", "FINISH"]
    task: str                                            # 다음 담당에게 줄 한 줄 지시
    reason: str

class State(TypedDict):
    question: str
    results: Annotated[list[dict], operator.add]         # AgentResult가 차례로 쌓임
    next: str
    task: str
    steps: int
    tokens: int

def supervisor(state: State) -> dict:
    if state["steps"] >= MAX_STEPS or state["tokens"] >= MAX_TOKENS:   # 코드가 먼저 끊음
        return {"next": "FINISH"}
    r = client.messages.parse(model="claude-opus-5-5", max_tokens=1024,
                              system=SUPERVISOR_PROMPT,
                              messages=[{"role": "user", "content": render(state)}],
                              output_format=Decision)
    d = r.parsed_output
    used = r.usage.input_tokens + r.usage.output_tokens
    return {"next": d.next, "task": d.task, "steps": state["steps"] + 1,
            "tokens": state["tokens"] + used}

g.add_conditional_edges("supervisor", lambda s: s["next"],
                        {"hr": "hr", "it": "it", "policy": "policy", "FINISH": "synthesize"})
for agent in ["hr", "it", "policy"]:
    g.add_edge(agent, "supervisor")                      # 일이 끝나면 늘 돌아옴
g.add_edge("synthesize", END)

🔍 읽는 포인트

• Decision.next: Literal[...] — 관리 에이전트가 고를 수 있는 담당은 이 넷뿐 입니다. 없는 에이전트를 지어낼 수 없습니다.
• if state["steps"] >= MAX_STEPS ... — 모델에게 묻기 전에 코드가 상한을 확인합니다. 6절의 가드레일입니다.
• g.add_edge(agent, "supervisor") — 돌아오는 엣지 . 담당은 끝나면 답을 사용자에게 바로 주지 않고 관리 에이전트에게 돌아갑니다. 이 선이 Supervisor 그림(1.1)의 화살표입니다.
• results: Annotated[..., operator.add] — 담당들의 AgentResult가 덮어써지지 않고 쌓입니다 (18차시 리듀서). 종합 단계가 이 목록을 읽습니다.
• 💡 Supervisor 구성을 도와주는 별도 패키지(예: langgraph-supervisor)도 있지만 버전에 따라 이름과 사용법이 다릅니다. 원리를 먼저 이 구조로 이해하고, 패키지를 쓸 때는 공식 문서를 확인하세요.

---

5. 응답 종합 — 출처 유지와 모순 처리

응답 종합 — [결과 처리 단계]인데, [ 여러 에이전트의 결과를 하나의 답으로 묶되 각 내용의 출처를 유지하고 결과끼리의 모순을 드러낸다 ]는 점에서 마지막 에이전트의 답을 그대로 내보내는 것과 구별된다.

⚠️ 종합 단계는 가장 그럴듯한 하나의 이야기 를 만들려는 경향이 있습니다. 그 과정에서 출처가 사라지고 모순이 매끄럽게 덮입니다. 앞에서 배운 근거 기반 답변(14차시)의 원칙 — 근거에 없으면 답하지 않는다 — 을 종합 단계에도 그대로 적용합니다. AgentResult.sources가 계약에 있던 이유입니다(21차시).

---

6. 가드레일 재적용 — 총 반복 · 총 비용

앞에서 배운 루프 가드레일(10차시)은 에이전트 하나 의 루프에 상한을 걸었습니다. 멀티에이전트에서는 상한이 두 층 이 됩니다.

⚠️ 에이전트마다 상한이 있어도 전체 상한이 없으면 폭주합니다. supervisor가 hr → policy → hr → policy를 오가면 각자는 상한 안에 있지만 전체 비용은 계속 늘어납니다. 그래서 4절 코드에서 모델에게 묻기 전에 전체 상한을 먼저 확인했습니다. 상한에 닿으면 그때까지의 결과로 종합하고 "일부만 처리했습니다"를 밝힙니다.

---

7. 실행 추적으로 검수 — 누가 무엇을 했나

앞에서 배운 트레이싱(11차시)은 각 단계의 입력 · 출력 · 토큰 · 시간을 기록했습니다. 멀티에이전트에서는 이것이 유일한 검수 수단 에 가깝습니다. Planner와 달리 미리 읽을 계획표가 없기 때문입니다(3절).

⚠️ 추적 기록은 외부 서비스로 전송될 수 있습니다(축 ④). 앞에서 배운 마스킹(8차시)과 장기 기억의 외부 전송 점검(17차시)을 추적에도 적용하세요.

앞으로 다시 만납니다 — 23차시에서 needs_approval을 받은 흐름을 멈추고 , 사람이 승인하면 재개 합니다. 24차시에서는 이 추적의 진행 상황을 화면에 스트리밍으로 보여 줍니다("인사 담당이 휴가 잔여를 확인하는 중...").

---

8. 실습 — 맡기고 검수하기

지시

21차시의 인사 · IT · 규정 에이전트 위에 Supervisor를 만들어줘.
참고 공식 문서: LangGraph StateGraph · 조건부 엣지 · recursion_limit, Claude API 구조화 출력, LangSmith 트레이싱.
  설치된 langgraph 버전을 출력하고 그 버전 문서 기준으로 작성할 것. 별도 supervisor 패키지는 쓰지 말 것.
구조: supervisor(Decision 스키마) → 조건부 엣지 → hr/it/policy → supervisor로 복귀 → FINISH면 synthesize → END.
제약:
- MAX_STEPS=6, MAX_TOKENS 상한(값은 보고)을 supervisor 노드에서 모델 호출 전에 검사.
- 같은 담당 · 같은 task 연속 2회면 FINISH.
- synthesize는 AgentResult.sources만 출처로 사용. needs_approval은 "승인 대기"로 답할 것.
- 트레이싱을 켜되 사번 · 전화번호는 마스킹 후 전송.
테스트: ① "다음 주 월요일 휴가 쓰려는데 잔여 확인하고, 노트북 반납 절차도 알려줘" ② 단일 의도 질문 2개
  ③ 담당끼리 답이 모순되게 만든 테스트 데이터 ④ supervisor가 계속 위임하도록 유도하는 질문 ⑤ 모니터 신청 요청
보고 형식: 시나리오마다 [단계 | supervisor 결정 | reason | 담당 | status | sources | 누적 토큰] 표 + 최종 답 원문.
  20차시 Planner-Worker 방식과 ①의 호출 수 · 토큰을 비교.
추측하지 말고 실행 출력 원문과 추적 화면 캡처(또는 추적 기록 원문)를 붙여.

받을 증거

• 시나리오별 단계 표 와 최종 답 원문
• ④에서 상한에 닿아 FINISH로 끊긴 단계 기록
• 추적 기록에서 사번 · 전화번호가 가려진 화면
• ①에 대한 Planner-Worker 대비 호출 수 · 토큰 비교

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 22차시 노트만 근거로 비전공자용 5문제를 내줘.
"Supervisor와 Planner-Worker의 경계(미리 계획 ↔ 매번 판단)", "돌아오는 엣지", "응답 종합의 출처와 모순", "전체 상한을 코드로"는 반드시 포함해줘.
내가 답한 뒤에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.