[LangGraph 기초 1] Node와 State의 개념

 

LangGraph를 프로그래밍 언어로 바라보기

---

LLM 기반 애플리케이션을 실제 환경에서 운영하려면 단순한 모델 호출을 넘어, 상태 관리·제어 흐름·복구 가능성이 필요하다.
LangGraph는 이러한 요구를 충족하기 위한 에이전트 실행 프레임워크이며, 하나의 프로그래밍 언어처럼 생각할 수 있다.

LangGraph의 핵심 개념은 전통적인 프로그래밍 언어의 구성 요소와 매우 유사하다.

 

 

 

• State: 프로그램을 통해 흐르는 데이터
• Node: 데이터를 처리하는 함수
• Edge: 실행 흐름을 제어하는 제어문(control flow)
• Checkpointing: 상태 저장을 통한 복구 메커니즘
• Human-in-the-Loop: 실행을 중단하고 인간의 개입을 허용하는 구조

 

 

이러한 구성 덕분에 LangGraph는 단순한 워크플로우 도구가 아니라, 에이전트 실행을 위한 구조적 모델로 동작한다.

 

 

 

State란 무엇인가?

---

State는 그래프를 따라 이동하며 계속 업데이트되는 공유 데이터이다.

 

• 그래프 실행 시 입력으로 주어짐
• 각 노드에 의해 수정됨
• graph.invoke 명령어를 통해 그래프 실행이 끝나면 최종 결과로 반환됨

중요한 점은 그래프 자체는 stateless라는 것이다.
상태는 외부에서 주어지고, 실행 결과로 다시 외부로 반환된다.

 

 

StateGraph의 기본 구조

---

StateGraph는 이름 그대로 State + Graph로 구성되다.

1. 먼저 그래프가 다룰 State의 구조를 정의
2. 이 State는 모든 노드가 공유
3. 그래프는 이 State를 어떻게 변화시킬지만 정의

즉, LangGraph에서는 데이터(State)와 로직(Graph)이 명확히 분리된다.

 

State는 일반적인 Python 데이터 구조로 정의된다.

• TypedDict
• Python dataclass
• Pydantic BaseModel

보통 대부분의 예제에서는 단순함을 위해 문자열 리스트 하나를 가지는 TypedDict를 사용한다.
이 구조 덕분에 State는 명확하고 타입 안정적으로 관리되다.

 

 

 

Node는 단순한 함수다

---

LangGraph에서 Node는 특별한 객체가 아니다.
단순히 다음 형태를 가지는 함수입니다.

• 입력: 현재 State
• 출력: State에 대한 업데이트

노드는 현재 상태를 읽고, 필요한 연산을 수행한 뒤, 변경된 부분만 반환한다.

 

 

 

LangGraph의 실행 방식

---

그래프가 실행되면 LangGraph 런타임은 다음 과정을 반복한다.

1. 현재 실행할 노드를 선택
2. 현재 State를 노드에 전달
3. 노드 함수 실행
4. 반환값을 State에 반영

이 과정이 모든 노드에 대해 완료되면, 최종 State가 반환된다.

 

 

 

State 영속성과 복원력 (Resilience)

---

LangGraph의 강력한 특징 중 하나는 State의 영속성(persistence)이다.

 

 

• 노드 실행 중 실패 발생 가능
• 실패 시 State를 복원
• 동일 노드를 처음부터 다시 실행 가능

이 기능은 하위 플랫폼의 실패 감지 지원이 필요하지만,
LangGraph 애플리케이션을 장시간 실행 가능한 에이전트로 만들어 주는 핵심 요소이다.

 

 

 

 

실제로 Graph를 만드는 예제

---

from IPython.display import Image, display
import operator
from typing import Annotated, List, Literal, TypedDict
from langgraph.graph import END, START, StateGraph

# State 상태 정의 (TypeDict 타입 사용)
# 하나의 매개변수를 가짐 (nlist라는 문자열 타입의 리스트)

class State(TypedDict):
    nlist: List[str]

 

# Node 정의
# Node는 상태를 입력으로 받아 상태에 대한 업데이트를 수행함
# 여기서는 nlist를 note로 덮어쓰는 일을 수행

def node_a(state: State) -> State:
    print(f"node a is receiving {state['nlist']}") # 함수 맨 위에 디버깅 추가
    note = "Hello World from Node a"
    return (State(nlist = [note]))

 

# 그래프 구축
builder = StateGraph(State) # State를 사용해 StateGraph 객체를 instance화
builder.add_node("a", node_a) # 방금 만든 node_a를 "a" 노드로 추가
builder.add_edge(START, "a") # START 노드에서 "a" 노드 가는 Edge 추가
builder.add_edge("a", END) # "a" 노드에서 END 노드 가는 Edge 추가
graph = builder.compile() # StateGraph 객체를 컴파일하여 graph 객체로 변환

 

# 그래프 확인
display(Image(graph.get_graph().draw_mermaid_png()))

# 아래 이미지는 우리 노트북에서 렌더링하고 있는 이미지이다.
# 이 mermaid 다이어그램을 직접 생성하는 코드를 얻고 싶다면 draw_mermaid() 호출
# print(graph.get_graph().draw_mermaid())

 

 

 

 

# 초기 변수로 nlist에 초기값 입력
initial_state = State(
    nlist = ["Hello Node a, how are you?"]
)

# graph 실행: nlist가 node_a에 의해 새로운 nlist로 변경됨 (State 업데이트)
graph.invoke(initial_state)

 

 

Out:

node a is receiving ['Hello Node a, how are you?']
{'nlist': ['Hello World from Node a']}

 

 

 

핵심 요점

---

1. Graph와 State를 정의할 때 모든 Node가 동일한 State를 공유한다.
2. State는 Dictionary, Python 데이터 등 다양한 타입이 가능하다.
3. Node는 단순한 함수이다.
4. Graph를 실행할 때 LangGraph 런타임이 동작해 호출 문에서 입력 상태를 초기화하고 State를 입력으로 Node에 제공한다.
5. Node가 실행되어 반환값으로 State가 업데이트된다.
6. Graph가 실행을 마치면 반환값으로 State가 반환된다.