LangGraph 0.5 멀티에이전트 패턴 — Supervisor·Swarm·Hierarchical 실전 가이드

핵심 요약

LangGraph 0.5(2026-04 릴리스)는 멀티에이전트 토폴로지 3종을 표준 패턴으로 명문화했다. 각각 다른 문제 유형에 적합하고, 잘못 선택하면 토큰 낭비·디버깅 지옥을 겪는다.

• Supervisor: 1개 라우터가 여러 워커를 호출. 워크플로 명확할 때.
• Swarm: 워커들끼리 직접 핸드오프. 도메인 경계 명확할 때.
• Hierarchical: 슈퍼바이저의 슈퍼바이저. 조직형 워크로드.

1. Supervisor — 가장 간단

"라우팅 전담 LLM"이 도구처럼 워커를 호출. 결정은 슈퍼바이저가 다 한다.

from langgraph.prebuilt import create_supervisor
from langgraph.prebuilt.chat_agent_executor import create_react_agent

researcher = create_react_agent(
    model="claude-opus-4-7",
    tools=[web_search, fetch_url],
    name="researcher",
    prompt="당신은 리서처. 사실 수집·근거 인용에 집중."
)

writer = create_react_agent(
    model="claude-opus-4-7",
    tools=[],
    name="writer",
    prompt="당신은 카피라이터. 한국어 톤·SEO 키워드 반영."
)

app = create_supervisor(
    [researcher, writer],
    model="claude-opus-4-7",
    prompt="researcher로 자료 수집 후 writer가 글을 쓴다."
).compile()

장단점

2. Swarm — 동료 간 핸드오프

슈퍼바이저 없이 워커끼리 "이건 네 영역" 하며 넘김. 각 에이전트가 도메인 전문가.

from langgraph_swarm import create_swarm, create_handoff_tool

billing_agent = create_react_agent(
    model="claude-opus-4-7",
    tools=[lookup_invoice, create_handoff_tool(agent_name="tech_agent",
        description="기술 문제는 tech_agent로 위임")],
    name="billing_agent",
    prompt="결제·환불 전담."
)

tech_agent = create_react_agent(
    model="claude-opus-4-7",
    tools=[query_logs, create_handoff_tool(agent_name="billing_agent")],
    name="tech_agent",
    prompt="기술 트러블슈팅 전담."
)

app = create_swarm(
    [billing_agent, tech_agent],
    default_active_agent="billing_agent",
).compile()

핸드오프 함정

두 에이전트가 핑퐁(서로 미루기) 가능. 핸드오프 횟수 상한을 두고 그래도 결정 안 되면 인간 에스컬레이션 노드로.

3. Hierarchical — 팀의 팀

슈퍼바이저가 하위 슈퍼바이저를 가짐. 5개 이상 워커가 필요하거나 워커 그룹별 전문성이 다를 때.

research_team = create_supervisor([web_researcher, paper_searcher, ...]).compile()
writing_team  = create_supervisor([draft_writer, editor, fact_checker]).compile()

top = create_supervisor(
    [research_team, writing_team],
    prompt="research_team으로 조사 후 writing_team에 전달."
).compile()

4. 토폴로지 결정 기준

5. 운영 팁

• 토큰 한도: 각 워커에 max_iterations=10 같은 가드. 무한루프 방어.
• 관찰성: LangSmith·Phoenix 트레이싱 필수. 누가 누구를 호출했는지 시각화.
• 비용 모니터링: Supervisor 패턴은 라우터 토큰이 전체의 30~40% 차지. 라우터 모델은 Haiku로 다운그레이드 검토.
• 휴먼 인 더 루프: 결제·이메일 발송처럼 되돌릴 수 없는 단계는 interrupt_before로 강제 중단.

흔한 실수

1. 슈퍼바이저에 "creative" 지시 — 라우팅만 시키고 내용은 워커에게.
2. Swarm에서 핸드오프 사이클 검증 안 함 — 그래프 분석 필수.
3. 모든 단계에 Opus — 라우터·검증은 Haiku/Sonnet으로 충분.

참고

• langchain-ai/langgraph 공식 예제 폴더 examples/multi_agent
• Anthropic Cookbook의 multi-agent-orchestration.ipynb