LangGraph 아키텍처

LangGraph 개요

LangChain이 체인과 에이전트 개념을 통해 언어 모델 활용을 지원했다면, LangGraph는 노드와 엣지로 이루어진 그래프 구조를 통해 복잡한 워크 플로우를 구현한다. LangCahin의 기존 체인은 주로 비순환 유향 그래프(DAG) 형태였지만, LangGraph를 사용하면 루프를 포함한 순환 그래프 형태의 논리 흐름을 손쉽게 구축할 수 있다.

이러한 사이클 지원을 통해 에이전트가 LLM을 반복 호출하며 추론하는 상태 기계(state machine)를 구현할 수 있으며, 개발자는 워크플로우의 흐름과 상태를 세밀하게 제어할 수 있다. 또한 LangGraph는 중앙 집중식 상태 관리와 Persistence(상태 지속) 레이어를 제공하여 대화 메모리 및 Human-in-the-loop과 같은 기능도 지원한다.

요약하면, LangGraph는 LangChain 상태계와 상호 운용되면서도 에이전트의 동작 원리를 그래프로 시각화하고 세밀하게 조정할 수 있게 해주는 아키텍처이다.

 

그래프 구조

노드

LangGraph의 노드는 파이썬 함수 또는 LangChain의 체인/프롬프트 등을 감싼 실행체로 정의된다. 노드는 첫 번째 인자로 그래프의 상태를 받아들이고 로직 실행 후 상태에 반영할 변경사항을 반환한다.

from langchain_core.runnables import RunnableConfig
from langgraph.graph import StateGraph

builder = StateGraph(dict)
def my_node(state: dict, config: RunnableConfig):
    print("In node: ", config["configurable"]["user_id"])
    return {"results": f"Hello, {state['input']}!"}

# The second argument is optional
def my_other_node(state: dict):
    return state

builder.add_node("my_node", my_node)
builder.add_node("other_node", my_other_node)

 

LangGraph에는 START 노드와 END 노드라는 특별한 노드가 있다. START는 그래프 시작 지점을 나타내며 주로 사용자 입력을 그래프에 투입할 때 사용하고 END 그래프 종료를 의미하여 더 이상 진행할 노드가 없음을 표시한다.

 

엣지

엣지는 노드 간의 실행 흐름을 정의한다. LangGraph에서는 다음과 같은 주요 엣지 유형을 지원한다.

# 일반 엣지
# 항상 노드 A 실행 후 노드 B를 실행하도록 직접 연결을 정의
graph.add_edge("A", "B")

# 조건부 엣지
# 분기 로직이 포함된 엣지로, 특정 노드의 실행 결과나 상태를 평가하는 함수를 통해 다음으로 실행할 노드를 겨정
graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"})

# 엔트리 엣지
# 그래프의 시작 노드를 지정하는 엣지
graph.set_entry_point("노드 이름")

 

하나의 노드에서 여러 개의 엣지를 출력으로 가질 수도 있으며 병렬적으로 여러 노드들을 다음 단계에서 동시에 실행시키는 것도 가능하다. 하지만, 일반적으로 에이전트 시나리오에서는 한 시점에 하나의 경로만 진행되도록 설계하며 필요한 경우 조건부 엣지를 사용해 분기하거나 루프를 돌게 된다.

 

상태 관리

상태는 LangGraph 아키텍처의 중앙 허브 역할을 한다. 그래프의 각 노드는 상태를 공유하며, 상태에 담긴 정보를 참고하여 동작하고 실행 결과를 다시 상태에 기록한다.

상태는 파이썬 타입 힌드를 사용해 스키마를 정의하게 되며 사용자 입력, 대화 이력, 중간 결과 등을 속성으로 가질 수 있다. 상태 객체는 그래프 실행 내내 지속되며, 노드 간 메시지 전달이나 데이터 공유를 이 상태를 통해 수행한다.

from langgraph.graph import StateGraph
from typing import TypedDict, List, Annotated
import operator

# 상태 객체의 타입 정의
class State(TypedDict):
    input: str
    all_actions: Annotated[List[str], operator.add]

# 정의한 State 타입으로 그래프 초기화
graph = StateGraph(State)

 

State의 input 필드에 사용자 입력을 담고, all_actions 필드에 에이전트가 수행한 모든 액션의 기록을 리스트로 누적한다. 해당 리스트에 새 요소를 추가하는 방식으로 상태를 업데이트하겠다는 의미이다. 이렇게 상태 구조를 정의하고 나면 StateGraph 생성 시에 각 상태 속성의 업데이트 동작을 LangGraph가 인식하게 된다.