멀티 에이전트 시스템 구축 가이드

원문: https://langchain-ai.github.io/langgraph/how-tos/multi_agent/

개요

단일 에이전트는 여러 도메인을 전문화하거나 많은 도구를 관리해야 할 때 어려움을 겪을 수 있습니다. 이를 해결하기 위해 에이전트를 더 작고 독립적인 에이전트로 분리하여 멀티 에이전트 시스템으로 구성할 수 있습니다.

멀티 에이전트 시스템에서 에이전트는 서로 통신해야 합니다. 이들은 핸드오프(Handoff) 를 통해 통신합니다. 핸드오프는 제어권을 넘겨줄 에이전트와 해당 에이전트에게 전송할 페이로드를 설명하는 프리미티브입니다.

이 가이드는 다음 내용을 다룹니다:

에이전트 간 핸드오프 구현
핸드오프와 미리 빌드된 에이전트를 사용하여 사용자 정의 멀티 에이전트 시스템 구축

멀티 에이전트 시스템 구축을 시작하려면 가장 인기 있는 두 가지 멀티 에이전트 아키텍처인 슈퍼바이저와 스웜의 LangGraph 미리 빌드된 구현을 확인하세요.

핸드오프

멀티 에이전트 시스템에서 에이전트 간 통신을 설정하려면 핸드오프를 사용할 수 있습니다. 핸드오프는 한 에이전트가 제어권을 다른 에이전트에게 넘기는 패턴입니다. 핸드오프를 통해 다음을 지정할 수 있습니다:

목적지: 이동할 대상 에이전트(예: 이동할 LangGraph 노드의 이름)
페이로드: 해당 에이전트에게 전달할 정보(예: 상태 업데이트)

핸드오프 생성

핸드오프를 구현하려면 에이전트 노드나 도구에서 Command 객체를 반환할 수 있습니다:

from typing import Annotated
from langchain_core.tools import tool, InjectedToolCallId
from langgraph.prebuilt import create_react_agent, InjectedState
from langgraph.graph import StateGraph, START, MessagesState
from langgraph.types import Command
 
def create_handoff_tool(*, agent_name: str, description: str | None = None):
    name = f"transfer_to_{agent_name}"
    description = description or f"Transfer to {agent_name}"
 
    @tool(name, description=description)
    def handoff_tool(
        state: Annotated[MessagesState, InjectedState],  # (1)
        tool_call_id: Annotated[str, InjectedToolCallId],
    ) -> Command:
        tool_message = {
            "role": "tool",
            "content": f"Successfully transferred to {agent_name}",
            "name": name,
            "tool_call_id": tool_call_id,
        }
        return Command(  # (2)
            goto=agent_name,  # (3)
            update={"messages": state["messages"] + [tool_message]},  # (4)
            graph=Command.PARENT,  # (5)
        )
 
    return handoff_tool

InjectedState 어노테이션을 사용하여 핸드오프 도구를 호출하는 에이전트의 상태에 접근합니다.
Command 프리미티브를 사용하면 상태 업데이트와 노드 전환을 단일 작업으로 지정할 수 있어 핸드오프 구현에 유용합니다.
핸드오프할 에이전트 또는 노드의 이름입니다.
에이전트의 메시지를 가져와서 핸드오프의 일부로 부모의 상태에 추가합니다. 다음 에이전트는 부모 상태를 볼 수 있습니다.
LangGraph에게 부모 멀티 에이전트 그래프의 에이전트 노드로 이동해야 함을 나타냅니다.

팁
Command를 반환하는 도구를 사용하려면 미리 빌드된 create_react_agent / ToolNode 컴포넌트를 사용하거나, 도구가 반환한 Command 객체를 수집하여 목록으로 반환하는 자체 도구 실행 노드를 구현할 수 있습니다:
def call_tools(state):
    ...
    commands = [tools_by_name[tool_call["name"]].invoke(tool_call) for tool_call in tool_calls]
    return commands

중요
이 핸드오프 구현은 다음을 가정합니다:

각 에이전트는 멀티 에이전트 시스템의 전체 메시지 히스토리(모든 에이전트에 걸친)를 입력으로 받습니다. 에이전트 입력에 대한 더 많은 제어가 필요한 경우 이 섹션을 참조하세요.

각 에이전트는 자신의 내부 메시지 히스토리를 멀티 에이전트 시스템의 전체 메시지 히스토리로 출력합니다. 에이전트 출력이 추가되는 방식에 대한 더 많은 제어가 필요한 경우 별도의 노드 함수로 에이전트를 래핑하세요:
def call_hotel_assistant(state):
    # 내부 독백을 제외하고 에이전트의 최종 응답 반환
    response = hotel_assistant.invoke(state)
    return {"messages": response["messages"][-1]}

에이전트 입력 제어

Send() 프리미티브를 사용하여 핸드오프 중에 워커 에이전트에게 직접 데이터를 전송할 수 있습니다. 예를 들어, 호출하는 에이전트가 다음 에이전트를 위한 작업 설명을 작성하도록 요청할 수 있습니다:

from typing import Annotated
from langchain_core.tools import tool, InjectedToolCallId
from langgraph.prebuilt import InjectedState
from langgraph.graph import StateGraph, START, MessagesState
from langgraph.types import Command, Send
 
def create_task_description_handoff_tool(
    *, agent_name: str, description: str | None = None
):
    name = f"transfer_to_{agent_name}"
    description = description or f"Ask {agent_name} for help."
 
    @tool(name, description=description)
    def handoff_tool(
        # 이것은 호출하는 에이전트에 의해 채워집니다
        task_description: Annotated[
            str,
            "Description of what the next agent should do, including all of the relevant context.",
        ],
        # 이러한 매개변수는 LLM에 의해 무시됩니다
        state: Annotated[MessagesState, InjectedState],
    ) -> Command:
        task_description_message = {"role": "user", "content": task_description}
        agent_input = {**state, "messages": [task_description_message]}
        return Command(
            goto=[Send(agent_name, agent_input)],
            graph=Command.PARENT,
        )
 
    return handoff_tool

핸드오프에서 Send()를 사용하는 전체 예제는 멀티 에이전트 슈퍼바이저 예제를 참조하세요.