Python LangGraph 주요 문법 완전 정복

[Python LangGraph]

Python 생태계에서 LLM(대규모 언어 모델)을 활용한 워크플로우를 설계하는 데 있어 LangGraph는 매우 유용한 도구입니다. LangGraph는 LangChain을 기반으로 하면서, 상태 기반의 워크플로우를 정의하고 실행할 수 있는 라이브러리입니다. 특히 대화형 애플리케이션을 설계하거나, 다양한 에이전트의 논리 흐름을 제어할 때 강력한 유연성과 확장성을 제공합니다.

이 글에서는 LangGraph를 처음 접하는 분들을 위해 주요 문법을 중심으로 사용법과 개념을 예제와 함께 상세히 설명하겠습니다.

LangGraph란 무엇인가?

LangGraph는 LLM 기반의 복잡한 대화 흐름, 멀티에이전트 시스템, 워크플로우 등을 상태 기반(State-based)으로 구현할 수 있도록 도와주는 Python 라이브러리입니다. 기존의 LangChain의 Chain, Agent 개념을 확장하여 상태 머신 형태로 구성할 수 있게 해줍니다.

간단히 말해, LangGraph는 “어떻게 상태가 변화하면서 LLM 기반 로직이 흐를지”를 정의하는 툴입니다.

LangGraph의 기본 개념

LangGraph를 이해하려면 다음 네 가지 주요 개념을 먼저 숙지해야 합니다.

노드 (Node)

정의: 그래프에서 하나의 단일 작업 또는 함수.
역할: 각 노드는 LLM 호출, API 요청, 계산 등의 작업을 수행.

def my_node(state):
    return state + 1

엣지 (Edge)

정의: 한 노드에서 다른 노드로 연결되는 흐름.
역할: 조건문 또는 순서 기반으로 노드 간 이동을 담당.

graph.edge("A", "B")

상태 (State)

정의: 현재까지의 입력/출력 정보, 메타데이터 등을 담고 있는 값.
역할: 그래프 실행 중 변하는 데이터 저장소.

{"user_input": "안녕하세요", "llm_response": ""}

상태 기계 (State Machine)

정의: 상태 + 노드 + 엣지로 구성된 전체 그래프 시스템.
역할: 시작 상태에서 시작해 노드를 따라 상태를 변경하며 실행.

LangGraph 설치 방법

LangGraph는 pip를 이용해 간단히 설치할 수 있습니다.

pip install langgraph

LangChain이 설치되어 있어야 하므로, 필요시 함께 설치하세요:

pip install langchain openai

LangGraph 핵심 문법 및 코드 구성

LangGraph를 사용하기 위해 필요한 핵심 구성 요소를 단계별로 살펴보겠습니다.

Graph 정의

LangGraph에서는 StateGraph를 이용해 상태 그래프를 정의합니다.

from langgraph.graph import StateGraph

workflow = StateGraph()

노드 정의

노드는 Python 함수로 정의되며, 입력으로 state를 받고, 반환 값으로 새로운 상태를 반환합니다.

def greet_node(state):
    user_input = state["user_input"]
    response = f"안녕하세요, {user_input}님!"
    state["llm_response"] = response
    return state

노드 추가 및 Transition 설정

노드를 그래프에 추가하고 흐름을 정의합니다.

workflow.add_node("greet", greet_node)
workflow.set_entry_point("greet")
workflow.set_finish_point("greet")

여러 노드를 사용하는 경우에는 transition을 다음과 같이 정의합니다:

workflow.add_edge("node1", "node2")

Graph 실행

마지막으로 그래프를 빌드하고 실행합니다.

graph = workflow.compile()

initial_state = {"user_input": "철수"}
result = graph.invoke(initial_state)
print(result)

LangGraph를 이용한 간단한 예제

아래는 사용자의 질문에 따라 다른 노드로 분기하는 간단한 LangGraph 예제입니다.

from langgraph.graph import StateGraph

def start(state):
    question = state["question"]
    if "날씨" in question:
        return "weather"
    else:
        return "general"

def weather_node(state):
    state["answer"] = "오늘은 맑습니다."
    return state

def general_node(state):
    state["answer"] = "무엇을 도와드릴까요?"
    return state

workflow = StateGraph()
workflow.add_node("start", start)
workflow.add_node("weather", weather_node)
workflow.add_node("general", general_node)

workflow.set_entry_point("start")
workflow.add_conditional_edges("start", lambda s: s["question"], {
    "weather": "weather",
    "general": "general",
})

workflow.set_finish_point("weather")
workflow.set_finish_point("general")

graph = workflow.compile()

# 실행 예시
result = graph.invoke({"question": "오늘 날씨 어때?"})
print(result["answer"])  # 출력: 오늘은 맑습니다.

고급 기능 소개

LangGraph는 기본적인 상태 흐름뿐 아니라 다음과 같은 고급 기능도 지원합니다.

조건 분기 (Branching)

add_conditional_edges를 통해 조건에 따라 다른 노드로 이동할 수 있습니다.

workflow.add_conditional_edges("start", decision_func, {
    "case1": "node1",
    "case2": "node2"
})

반복 처리 (Loop)

노드 간 반복 연결을 만들어 루프 형태로 처리할 수 있습니다.

workflow.add_edge("check", "ask_again")
workflow.add_edge("ask_again", "check")

복합 상태 관리

LangGraph는 dict 이외에도 TypedDict나 Pydantic 모델을 사용하여 더 안전한 상태 정의가 가능합니다.

from typing import TypedDict

class MyState(TypedDict):
    question: str
    answer: str

마무리 및 추천 학습 자료

LangGraph는 복잡한 LLM 워크플로우를 구조적으로 관리할 수 있는 매우 강력한 도구입니다. 특히 상태 기반으로 논리적 흐름을 제어할 수 있다는 점에서 기존의 LangChain보다 유연하고 명확한 구조를 제공합니다.