LangGraph Multi-Agent Swarm: 협력형 AI 시스템의 새로운 접근

대규모 언어 모델(LLM)을 활용한 에이전트 시스템이 점점 복잡해지고 있습니다. 한 명의 “스마트한 에이전트”만으로는 복잡한 업무를 완벽히 처리하기 어려운 경우가 많습니다. 바로 이때, 여러 개의 특화된 에이전트가 서로 협력하며 문제를 해결하는 “Swarm(군집)” 구조가 주목받고 있습니다.
이번 글에서는 LangGraph 기반의 LangGraph Multi-Agent Swarm 라이브러리를 중심으로, 다중 에이전트 협업 시스템의 개념과 특징, 설치 및 활용 방법을 자세히 살펴보겠습니다.

반응형

---

1. LangGraph Swarm이란 무엇인가?

LangGraph Swarm은 LangGraph 프레임워크 위에 구축된 Python 라이브러리로, 여러 에이전트가 협력하여 작업을 처리하는 다중 에이전트(Multi-Agent) 시스템을 쉽게 구현할 수 있도록 돕습니다.

이 시스템의 핵심은 각 에이전트가 자신의 역할에 따라 문제를 처리하고, 필요 시 다른 에이전트에게 제어를 넘기는(handoff) 구조입니다.
Swarm은 “현재 어떤 에이전트가 활성화되어 있었는지”를 기억하여 대화나 작업 흐름을 자연스럽게 이어갈 수 있도록 설계되었습니다.

즉, 단순히 에이전트를 여러 개 두는 것이 아니라, 에이전트 간의 협업 흐름과 기억 상태를 자동으로 관리하는 것이 LangGraph Swarm의 핵심입니다.

---

2. 왜 Multi-Agent Swarm이 필요한가?

단일 에이전트 기반의 시스템은 특정한 한 가지 작업에는 뛰어나지만, 다양한 영역의 문제를 복합적으로 처리하기에는 한계가 있습니다.

예를 들어,

• 한 에이전트는 수학적 계산에 강하고,
• 다른 에이전트는 문체나 자연어 응답에 특화되어 있다면,
  이 둘을 협력시켜 더 정교한 결과를 얻는 것이 훨씬 효율적입니다.

Swarm 구조는 이런 문제를 해결합니다. 각 에이전트가 자신의 전문 분야에서 최적의 판단을 내리고, 필요할 때 다음 에이전트에게 자연스럽게 업무를 넘겨주며, 전체 작업이 유기적으로 진행됩니다.

---

3. LangGraph Swarm의 주요 특징

LangGraph Swarm은 단순한 멀티에이전트 프레임워크를 넘어 다음과 같은 강점을 제공합니다.

1) Multi-Agent 협력 구조

여러 에이전트를 한 네트워크로 구성하고, 각자의 역할에 맞게 협력하도록 구성할 수 있습니다. 예를 들어, ‘Alice’와 ‘Bob’ 두 에이전트를 생성해 서로의 전문 분야에 맞춰 역할을 주고받을 수 있습니다.

2) Customizable Handoff Tools

에이전트 간의 역할 전환(handoff)을 지원하는 내장 도구가 있으며, 이를 사용자가 직접 커스터마이즈할 수도 있습니다. 어떤 데이터를 다음 에이전트로 넘길지, 어떤 설명을 추가할지 자유롭게 설정할 수 있습니다.

3) 메모리 및 상태 관리

Swarm은 단기(Short-term) 및 장기(Long-term) 메모리 시스템을 모두 지원합니다.
이 기능을 통해 “대화의 흐름”이나 “마지막으로 활성화된 에이전트”를 잊지 않고 기억하여, 복잡한 상호작용도 자연스럽게 이어집니다.

4) Human-in-the-loop 지원

개발자가 직접 개입하거나 의사결정을 유도할 수 있도록 설계되어 있어, 완전 자동화뿐만 아니라 반자동 협력 시스템 구축도 가능합니다.

---

4. 설치 및 Quickstart 예제

LangGraph Swarm은 PyPI에서 쉽게 설치할 수 있습니다.

pip install langgraph-swarm langchain-openai

환경 변수로 OpenAI API 키를 설정한 후 아래 예제를 실행합니다.

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.prebuilt import create_react_agent
from langgraph_swarm import create_handoff_tool, create_swarm

model = ChatOpenAI(model="gpt-4o")

def add(a: int, b: int) -> int:
    return a + b

# Alice: 덧셈 전문가
alice = create_react_agent(
    model,
    [add, create_handoff_tool(agent_name="Bob")],
    prompt="You are Alice, an addition expert.",
    name="Alice",
)

# Bob: 해적 말투로 대화하는 에이전트
bob = create_react_agent(
    model,
    [create_handoff_tool(agent_name="Alice", description="Transfer to Alice, she can help with math")],
    prompt="You are Bob, you speak like a pirate.",
    name="Bob",
)

checkpointer = InMemorySaver()

# Swarm 구성
workflow = create_swarm([alice, bob], default_active_agent="Alice")
app = workflow.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "1"}}

turn_1 = app.invoke({"messages": [{"role": "user", "content": "I'd like to speak to Bob"}]}, config)
print(turn_1)

turn_2 = app.invoke({"messages": [{"role": "user", "content": "What's 5 + 7?"}]}, config)
print(turn_2)

이 예제에서는 ‘Alice’와 ‘Bob’ 두 에이전트가 상호작용합니다.
사용자가 “Bob과 이야기하고 싶다”고 하면 제어가 Bob에게 넘어가고,
그 다음 “5 + 7은 얼마야?”라고 묻는 순간, 계산 전문인 Alice로 자동 전환되어 정확한 답을 제공합니다.

이처럼 Swarm 구조는 문맥을 유지하며, 필요한 순간에 적절한 에이전트를 자동 호출합니다.

---

5. 메모리 및 상태 관리

Swarm의 핵심은 메모리입니다.
에이전트 간의 대화를 이어가기 위해 Swarm은 **checkpointer(단기 메모리)**와 **store(장기 메모리)**를 사용합니다.

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.memory import InMemoryStore

checkpointer = InMemorySaver()  # 단기 메모리
store = InMemoryStore()         # 장기 메모리

이렇게 구성하면 Swarm이 이전 대화 상태를 잊지 않고, 다음 대화에서 이전의 문맥을 자연스럽게 이어갈 수 있습니다.
만약 checkpointer를 사용하지 않으면 Swarm은 “마지막으로 활성화된 에이전트” 정보를 잃어버리게 됩니다.

---

6. Custom Handoff Tool 구현하기

LangGraph Swarm의 강력한 기능 중 하나는 Handoff Tool을 직접 정의할 수 있다는 점입니다.
기본 제공되는 create_handoff_tool 외에도 아래처럼 자신만의 handoff 방식을 구현할 수 있습니다.

from typing import Annotated
from langchain_core.tools import tool, BaseTool, InjectedToolCallId
from langchain_core.messages import ToolMessage
from langgraph.types import Command
from langgraph.prebuilt import InjectedState

def create_custom_handoff_tool(agent_name: str, name: str | None, description: str | None) -> BaseTool:

    @tool(name, description=description)
    def handoff_to_agent(
        task_description: Annotated[str, "Detailed description of what the next agent should do."],
        state: Annotated[dict, InjectedState],
        tool_call_id: Annotated[str, InjectedToolCallId],
    ):
        tool_message = ToolMessage(
            content=f"Successfully transferred to {agent_name}",
            name=name,
            tool_call_id=tool_call_id,
        )
        messages = state["messages"]
        return Command(
            goto=agent_name,
            graph=Command.PARENT,
            update={
                "messages": messages + [tool_message],
                "active_agent": agent_name,
                "task_description": task_description,
            },
        )

    return handoff_to_agent

이 방식으로 handoff 시 어떤 데이터를 전달할지, 어떤 설명을 남길지, 어떤 상태를 갱신할지 세밀하게 조정할 수 있습니다.

---

7. Agent 구조 커스터마이징

기본적으로 Swarm은 모든 에이전트가 공통된 messages 키를 공유하지만,
프로젝트 성격에 따라 각 에이전트의 대화 기록을 분리하고 싶을 수도 있습니다.

그럴 때는 state schema를 별도로 정의하여 관리할 수 있습니다.

from typing_extensions import TypedDict, Annotated
from langchain_core.messages import AnyMessage
from langgraph.graph import StateGraph, add_messages

class AliceState(TypedDict):
    alice_messages: Annotated[list[AnyMessage], add_messages]

이 구조를 이용하면 각 에이전트의 내부 기록을 독립적으로 유지하면서도,
필요 시 Swarm 전체 상태에 통합할 수 있습니다.
즉, 프로젝트의 복잡도에 따라 메시지 관리 전략을 세밀하게 제어할 수 있습니다.

---

728x90

LangGraph Multi-Agent Swarm은 LLM 기반의 협력형 에이전트 시스템 구축을 간결하게 만들어주는 혁신적인 라이브러리입니다.

• 여러 에이전트 간 협력과 역할 분담이 가능하며
• 기억(메모리)과 상태 관리 기능을 통해 대화의 연속성을 보장하고
• 사용자가 직접 커스터마이징 가능한 구조를 제공합니다.

AI 시스템이 점점 복잡해지는 지금, LangGraph Swarm은 “모듈형 협력”이라는 새로운 접근 방식을 제시합니다.
이 라이브러리를 활용하면, 복잡한 업무를 여러 AI 에이전트가 자연스럽게 협력하여 수행하는 환경을 훨씬 쉽게 구현할 수 있을 것입니다.

300x250

https://github.com/langchain-ai/langgraph-swarm-py/?fbclid=IwY2xjawN5qsRleHRuA2FlbQIxMABicmlkETEyQWE4Q2ZXZ3AxY2U5Ujhnc3J0YwZhcHBfaWQQMjIyMDM5MTc4ODIwMDg5MgABHtmkSTNfnUDSxjFudlm2yEJ0_YpNs_FmLI11X9hMLm1C6dXPwtfgBZnIIwIW_aem_AkWaBNuckFbxlRBgNTqkyg

GitHub - langchain-ai/langgraph-swarm-py: For your multi-agent needs