[LangGraph] LangGraph 설명 및 기초

 

이번 글에서는 랭그래프(LangGraph)가 무엇인지, 어떻게 활용할 수 있는지 살펴보고자 합니다. 학습은 '요즘 AI 에이전트 개발, LLM RAG ADK MCP LangChain A2A LangGraph' 책을 기반으로 진행하여 내용이 유사함을 미리 알려드립니다.

 

랭그래프는 대표적인 에이전트 프레임워크 중 하나로, 랭체인(LangChain)을 개발한 LangChain.inc에서 개발했습니다. 랭그래프는 이름에서 알 수 있듯이 그래프 구조로 이루어져 있습니다. 자료 구조가 노드(Node)와 엣지(Edge)로 구성되어 있고, 방향 그래프(Directed Graph)를 기반으로 합니다. 많은 워크플로우 시스템들이 순환이 불가능한 DAG(Directed Acyclic Graph)만을 활용하는 반면, 랭그래프는 순환이 있는 그래프도 사용할 수 있습니다. 이를 바탕으로 이전 태스크로 돌아갈 수도 있고, 특정 조건이 충족될 때까지 태스크를 반복하는 것도 가능합니다.

 

랭그래프의 핵심 개념으로는 상태(State), 노드, 엣지가 있습니다. 상태는 그래프 구조로 태스크가 진행되는 과정에서 유지되는 데이터를 말합니다. 각 노드는 상태에 접근하여 워크플로우의 컨텍스트를 관리하기 때문에, 상태는 중앙 저장소 역할을 수행할 정도로 중요합니다.

 

다음으로 노드는 그래프의 기본 실행 단위를 말하며, 특정 태스크를 수행하는 에이전트, 툴 등을 나타냅니다.

 

마지막으로 엣지는 노드 간의 연결을 정의하고 실행 흐름을 제어하는 역할을 수행합니다. 랭그래프에는 조건부 엣지가 존재합니다. 상태에 따라 노드를 분기하는 것이 가능하므로, 상황에 따라 에이전트가 다른 판단을 수행하도록 하는 등 다양한 전략을 적용할 수 있습니다.

 

그럼 예제를 통해 랭그래프가 어떻게 동작하는지 살펴보겠습니다. 해당 예제에서는 LLM을 활용하지 않았습니다. 아래 코드는 책의 실습 자료로 해당 Github 링크에 있습니다.

 

우선 WorkflowStep, GraphState Class로 워크플로우 단계와 그래프 상태를 정의해 줍니다. 워크플로우는 GREETING, PROCESSING, 두 단계이며, 그래프 상태에는 이름, 인사말, 처리된 최종 메시지가 있습니다.

from tkinter import Image
from typing import Dict, Any
from langgraph.graph import StateGraph, START, END
from pydantic import BaseModel, Field

# ① 워크플로우 단계 정의
class WorkflowStep:
    GREETING = "GREETING"
    PROCESSING = "PROCESSING"

# ② 그래프 상태 정의
class GraphState(BaseModel):
    name: str = Field(default="", description="사용자 이름")
    greeting: str = Field(default="", description="생성된 인사말")
    processed_message: str = Field(default="", description="처리된 최종 메시지")

 

다음은 노드, 즉 태스크를 생성하는 단계입니다. generate_greeting() 함수는 인사말 생성을 수행하고, process_message() 함수는 인사말을 처리하고 최종 메시지를 생성하는 역할을 합니다.

# ③ 첫번째 노드 함수
def generate_greeting(state: GraphState) -> Dict[str, Any]:
    name = state.name or "아무개"
    greeting = f"안녕하세요, {name}님!"
    print(f"[generate_greeting] 인사말 생성: {greeting}")
    return {"greeting": greeting}


# ④두 번째 노드: 인사말을 처리하고 최종 메시지 생성
def process_message(state: GraphState) -> Dict[str, Any]:
    greeting = state.greeting
    processed_message = f"{greeting} LangGraph에 오신 것을 환영합니다!"

    print(f"[process_message] 최종 메시지: {processed_message}")

    return {"processed_message": processed_message}

 

이제는 create_hello_graph() 함수를 통해 그래프를 생성하는 단계입니다. 워크플로우에 상태와 노드를 먼저 추가해 주고, 작업 순서에 따라 노드들을 엣지로 연결해 줍니다.

# ⑤ 그래프 생성
def create_hello_graph():
    workflow = StateGraph(GraphState)

    # 노드 추가
    workflow.add_node(WorkflowStep.GREETING, generate_greeting)
    workflow.add_node(WorkflowStep.PROCESSING, process_message)

    # 시작점 설정
    workflow.add_edge(START, WorkflowStep.GREETING)

    # 엣지 추가 (노드 간 연결)
    workflow.add_edge(WorkflowStep.GREETING, WorkflowStep.PROCESSING)
    workflow.add_edge(WorkflowStep.PROCESSING, END)

    # 그래프 컴파일
    app = workflow.compile()

    return app

 

마지막으로 main() 함수를 통해 그래프를 실행합니다. initial_state에 초기 상태를 지정해주고(이름은 ‘승귤로 지정’), final_state에 invoke() 함수를 통해 그래프를 실행하며 결과를 넣어줍니다. 그 외에는 워크플로우를 실제 그래프 형태로 만드는 과정입니다.

def main():
    print("=== Hello 랭그래프 ===\n")
    app = create_hello_graph()

    initial_state = GraphState(name="승귤", greeting="", processed_message="")
    print("초기 상태:", initial_state.model_dump())
    print("\n--- 그래프 실행 시작 ---")

    # 그래프 실행
    final_state = app.invoke(initial_state)

    print("--- 그래프 실행 종료 ---\n")
    print("최종 상태:", final_state)
    print(f"\n결과 메시지: {final_state['processed_message']}")
    # ⑥ ASCII로 그래프 출력
    result = app.get_graph().draw_ascii()
    print(result)

    # ⑦ Mermaid로 그래프 이미지 생성
    result = app.get_graph().draw_mermaid_png()

    with open("./hello_langgraph.png", "wb") as f:
        f.write(result)

 

아래가 위 python 파일의 실행 결과입니다. “안녕하세요, 승귤님!”이라는 인사말 생성에서 시작해, “LangGraph에 오신 것을 환영합니다”라는 인사말을 추가하는 처리를 진행하며 최종 메시지를 생성했습니다. 아래 워크플로우가 그래프 형태로 나타나고, 실제 이미지 파일로도 저장되는 것을 확인할 수 있습니다.

=== Hello 랭그래프 ===

초기 상태: {'name': '승귤', 'greeting': '', 'processed_message': ''}

--- 그래프 실행 시작 ---
[generate_greeting] 인사말 생성: 안녕하세요, 승귤님!
[process_message] 최종 메시지: 안녕하세요, 승귤님! LangGraph에 오신 것을 환영합니다!
--- 그래프 실행 종료 ---

최종 상태: {'name': '승귤', 'greeting': '안녕하세요, 승귤님!', 'processed_message': '안녕하세요, 승귤님! LangGraph에 오신 것을 환영합니다!'}

결과 메시지: 안녕하세요, 승귤님! LangGraph에 오신 것을 환영합니다!
+-----------+  
| __start__ |
+-----------+
       *
       *
       *
 +----------+
 | GREETING |
 +----------+
       *
       *
       *
+------------+
| PROCESSING |
+------------+
       *
       *
       *
  +---------+
  | __end__ |
  +---------+

 

📌 LangGraph 관련 글 모음

• 조건부 엣지 적용하는 방법
• 체크포인터 기반 메모리(상태) 관리 방법

 

<참고>

1. https://ebook-product.kyobobook.co.kr/dig/epd/ebook/E000011924591

요즘 AI 에이전트 개발, LLM RAG ADK MCP LangChain A2A LangGraph | 박승규