🕸️
LangGraph 치트시트

LangGraph 최신 기준 초보자 완벽 가이드: 필수 사전 설치, StateGraph 아키텍처, TypedDict 상태 관리, 조건부 분기(Conditional Edges), ReAct 루프 에이전트, MemorySaver 대화 체크포인팅 및 Human-in-the-loop(인간 개입) 실전 예제
#langgraph#agent#llm#multi-agent#stategraph#human-in-the-loop#react#python#langchain#memory최종 업데이트: 2026-10-06
LangGraph 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

LangGraph를 오류 없이 구동하고 상태 기반 에이전트를 실습하기 위해 사전에 준비해야 하는 환경 요구사항입니다.

### 🐍 1. Python 버전 & 가상환경 (Virtual Environment)
LangGraph는 **Python 3.9 ~ 3.12+ (권장: Python 3.11 또는 3.12)** 환경을 지원합니다. 글로벌 환경 오염을 방지하기 위해 가상환경 생성이 **필수**입니다.

```bash
# 1. 표준 venv 가상환경 생성
python -m venv .venv

# 2. 가상환경 활성화 (Windows PowerShell)
# ※ 스크립트 실행 오류 시: Set-ExecutionPolicy Unrestricted -Scope Process
.venv\Scripts\Activate.ps1

# 가상환경 활성화 (macOS / Linux / WSL)
source .venv/bin/activate

# 3. 또는 차세대 초고속 패키지 관리자 uv 사용 시 (강력 권장)
pip install uv
uv venv
# Windows: .venv\Scripts\activate / macOS: source .venv/bin/activate
uv pip install langgraph langchain-core langchain-openai
```

### 🛠️ 2. OS별 C/C++ 네이티브 빌드 도구 (컴파일러)
`tiktoken`, `pydantic-core` 등 C++/Rust 확장 패키지 설치 시 빌드 오류를 방지하기 위해 권장됩니다.
- **Windows**: [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) ("C++를 사용한 데스크톱 개발" 워크로드 체크)
- **macOS**: `xcode-select --install`
- **Linux (Ubuntu/Debian)**: `sudo apt update && sudo apt install -y build-essential python3-dev`

### 📦 3. 필수 핵심 라이브러리 일괄 설치
```bash
# 1. LangGraph 코어 및 사전 구축 모듈
pip install langgraph

# 2. 연동할 LLM 및 도구 라이브러리
pip install langchain-core langchain-openai langchain-community

# 3. 환경변수 관리 및 데이터 검증
pip install python-dotenv pydantic
```

### 🔑 4. 환경 변수 설정 (`.env`)
프로젝트 폴더 루트에 `.env` 파일을 생성합니다:
```bash
# OpenAI API 키
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

# LangSmith 실시간 시각적 트레이싱 (강력 추천 - 무료 가입 가능)
# 그래프의 각 노드 실행 상태와 분기 흐름을 브라우저 대시보드에서 실시간 확인 가능
LANGCHAIN_TRACING_V2="true"
LANGCHAIN_API_KEY="lsv2_pt_xxxxxxxxxxxxxxxxxxxx"
LANGCHAIN_PROJECT="lucky-langgraph-prod"
```

코드 시작 부분에 환경변수를 로드합니다:
```python
from dotenv import load_dotenv
load_dotenv()
```

---

## 2. LangGraph 핵심 개념 (Mental Model)

기존 LangChain(LCEL)이 단방향 파이프라인(A ➔ B ➔ C)이었다면, **LangGraph**는 **순환 루프(Cycle), 조건부 분기(Branching), 상태 기억(State Persistence), 인간 개입(HITL)**을 가능하게 해주는 순환 그래프 엔진입니다.

```text
[LangGraph 아키텍처 멘탈 모델]
               ┌────────────────┐
               │     START      │
               └───────┬────────┘
                       │
                       ▼
               ┌────────────────┐
         ┌────►│  LLM Agent     │ (Node: 상태를 읽고 다음 행동 결정)
         │     └───────┬────────┘
         │             │
(Loop:   │             ├───────────────[조건 만족: 종료]───────────────┐
 재호출) │             │ (Conditional Edge)                            │
         │             ▼                                               ▼
         │     ┌────────────────┐                              ┌───────────────┐
         └─────┤   Tool Node    │ (Node: 도구 실행 후 결과 반영)│      END      │
               └────────────────┘                              └───────────────┘
```

### 🔑 4대 핵심 구성요소
1. **State (상태)**: 모든 노드가 공유하고 업데이트하는 데이터 스키마 (`TypedDict` 또는 Pydantic).
2. **Node (노드)**: 현재 상태를 입력받아 새로운 상태 변경분을 반환하는 Python 함수.
3. **Edge (엣지)**: 노드와 노드 사이의 이동 경로 (일반 엣지 및 조건부 엣지).
4. **Checkpointer (체크포인터)**: 매 스텝마다 상태를 스냅샷으로 저장하여 롤백 및 대화 복원을 가능하게 하는 메모리.

---

## 3. [초보자 1단계] 가장 단순한 2-노드 순차 그래프

노드 2개를 생성하고 데이터를 전달하는 가장 기본적인 헬로월드 예제입니다.

```python
from typing import TypedDict
from langgraph.graph import StateGraph, START, END

# 1. 상태 스키마 정의 (노드들이 공유할 데이터 구조)
class SimpleState(TypedDict):
    user_name: str
    message: str

# 2. 노드 함수 정의 (state를 인자로 받아, 변경할 값만 딕셔너리로 반환)
def greeting_node(state: SimpleState):
    print(f"[노드 1 실행] 입력받은 이름: {state['user_name']}")
    return {"message": f"안녕하세요, {state['user_name']}님!"}

def append_cheer_node(state: SimpleState):
    print(f"[노드 2 실행] 이전 메시지: {state['message']}")
    return {"message": f"{state['message']} 오늘도 멋진 하루 보내세요!"}

# 3. 그래프 생성 및 노드 등록
builder = StateGraph(SimpleState)
builder.add_node("greeting", greeting_node)
builder.add_node("cheer", append_cheer_node)

# 4. 엣지 연결 (START ➔ greeting ➔ cheer ➔ END)
builder.add_edge(START, "greeting")
builder.add_edge("greeting", "cheer")
builder.add_edge("cheer", END)

# 5. 그래프 컴파일 (실행 가능한 Runnable 앱 생성)
app = builder.compile()

# 6. 실행 (초기 상태 주입)
final_state = app.invoke({"user_name": "홍길동"})
print("\n최종 결과:", final_state["message"])
# 출력: 안녕하세요, 홍길동님! 오늘도 멋진 하루 보내세요!
```

---

## 4. [초보자 2단계] 조건부 분기 (Conditional Edges)

사용자의 입력 조건에 따라 서로 다른 노드로 동적 분기(라우팅)하는 패턴입니다.

```python
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END

class RouteState(TypedDict):
    query: str
    intent: str
    result: str

# 1. 의도 분류 노드
def classify_intent_node(state: RouteState):
    q = state["query"].lower()
    if "배송" in q or "주문" in q:
        intent = "delivery"
    elif "환불" in q or "취소" in q:
        intent = "refund"
    else:
        intent = "general"
    return {"intent": intent}

# 2. 분기 처리 노드들
def delivery_node(state: RouteState):
    return {"result": "📦 배송 조회: 현재 고객님의 상품이 출고 준비 중입니다."}

def refund_node(state: RouteState):
    return {"result": "💰 환불 접수: 구매 후 7일 이내 상품은 전액 환불 가능합니다."}

def general_node(state: RouteState):
    return {"result": "🤖 일반 상담: 상담원 연결을 도와드리겠습니다."}

# 3. 라우팅 조건 함수 (다음 노드 이름을 반환)
def route_decision(state: RouteState) -> Literal["delivery", "refund", "general"]:
    return state["intent"]

# 4. 그래프 조립
builder = StateGraph(RouteState)
builder.add_node("classifier", classify_intent_node)
builder.add_node("delivery", delivery_node)
builder.add_node("refund", refund_node)
builder.add_node("general", general_node)

builder.add_edge(START, "classifier")

# 조건부 엣지 등록 (classifier 노드 종료 후 route_decision 함수의 결과에 따라 이동)
builder.add_conditional_edges(
    "classifier",
    route_decision,
    {
        "delivery": "delivery",
        "refund": "refund",
        "general": "general"
    }
)

# 모든 분기 노드는 최종 종료(END)로 이동
builder.add_edge("delivery", END)
builder.add_edge("refund", END)
builder.add_edge("general", END)

app = builder.compile()

# 테스트 실행
print(app.invoke({"query": "내 택배 배송 언제 도착해?"})["result"])
print(app.invoke({"query": "결제한 신발 환불하고 싶어요"})["result"])
```

---

## 5. [초보자 3단계] 루프(Cycle)가 있는 ReAct 에이전트

LLM이 필요할 때 도구를 호출하고, 도구 실행 결과를 다시 읽은 뒤 최종 답을 낼 때까지 스스로 루프를 도는 완성형 에이전트 패턴입니다.

### 💡 메시지 리듀서 (`add_messages`)
- 상태 딕셔너리의 기본 동작은 값 덮어쓰기(Overwrite)입니다.
- 하지만 대화 기록은 누적(Append)되어야 하므로 `Annotated[list, add_messages]` 리듀서를 사용합니다.

```python
from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# 1. 대화 누적 상태 정의
class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]

# 2. 에이전트가 활용할 도구 준비
@tool
def get_weather(city: str) -> str:
    """도시 이름을 받아 현재 날씨를 조회합니다."""
    weather_db = {"서울": "맑음, 21도", "부산": "비, 18도", "제주": "구름 조금, 23도"}
    return weather_db.get(city, f"{city}의 날씨 정보가 없습니다.")

tools = [get_weather]

# 3. 모델에 도구 바인딩
llm = ChatOpenAI(model="gpt-4o", temperature=0)
llm_with_tools = llm.bind_tools(tools)

# 4. LLM 호출 노드
def chatbot_node(state: AgentState):
    response = llm_with_tools.invoke(state["messages"])
    return {"messages": [response]}

# 5. 그래프 구축
builder = StateGraph(AgentState)
builder.add_node("chatbot", chatbot_node)
builder.add_node("tools", ToolNode(tools)) # 사전 제작된 도구 실행 노드

builder.add_edge(START, "chatbot")

# 조건부 분기: LLM이 도구를 불렀으면 'tools'로 가고, 안 불렀으면 END로 종료
builder.add_conditional_edges("chatbot", tools_condition)

# 도구 실행 후에는 다시 LLM으로 루프(Cycle)!
builder.add_edge("tools", "chatbot")

app = builder.compile()

# 실행
inputs = {"messages": [HumanMessage(content="서울 날씨가 어때?")]}
result = app.invoke(inputs)

print("최종 답변:", result["messages"][-1].content)
```

---

## 6. [초보자 추천] 10줄로 만드는 `create_react_agent`

위의 복잡한 그래프 구조를 단 한 줄의 고수준 함수로 만들어 주는 공식 Prebuilt 방식입니다.

```python
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver

@tool
def calculate_vat(price: int) -> int:
    """상품 가격을 받아 10% 부가세를 계산합니다."""
    return int(price * 0.1)

tools = [calculate_vat]
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 인메모리 대화 기억 체크포인터
memory = MemorySaver()

# 단 한 줄로 ReAct 에이전트 생성 완료
agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

# 세션 ID를 부여하여 실행
config = {"configurable": {"thread_id": "user-session-001"}}

res1 = agent.invoke({"messages": [("user", "100,000원짜리 자켓의 부가세는 얼마야?")]}, config=config)
print(res1["messages"][-1].content)

# 이전 대화를 기억하는 후속 질문
res2 = agent.invoke({"messages": [("user", "그럼 부가세를 포함한 총 결제 금액은 얼마가 돼?")]}, config=config)
print(res2["messages"][-1].content)
```

---

## 7. 대화 기억 & 영속성 (Persistence & Checkpointing)

LangGraph는 매 스텝마다 상태를 체크포인터에 스냅샷으로 영구 저장합니다. `thread_id`만 유지하면 서버가 재시작되어도 대화 흐름을 복원할 수 있습니다.

```python
from langgraph.checkpoint.memory import MemorySaver

# 1. 체크포인터 설정
checkpointer = MemorySaver() # 실무에서는 SQLiteSaver나 PostgresSaver 사용

# 2. 컴파일 시 체크포인터 바인딩
app = builder.compile(checkpointer=checkpointer)

# 3. 고유한 thread_id로 대화 진행
thread_kim = {"configurable": {"thread_id": "user-kim-777"}}
thread_lee = {"configurable": {"thread_id": "user-lee-888"}}

# 김 고객 대화
app.invoke({"messages": [("user", "내 이름은 김철수야.")]}, config=thread_kim)

# 이 고객 대화
app.invoke({"messages": [("user", "내 이름은 이영희야.")]}, config=thread_lee)

# 김 고객 재방문 확인
res = app.invoke({"messages": [("user", "내 이름이 뭐였지?")]}, config=thread_kim)
print("김철수 세션 응답:", res["messages"][-1].content) # 김철수님이라고 정확히 기억함
```

---

## 8. 인간 개입 (Human-in-the-loop: HITL)

결제 승인, DB 삭제, 메일 발송 등 위험한 행동 직전에 **에이전트 실행을 일시 정지(Pause)**하고 관리자의 승인을 받는 패턴입니다.

```python
# tools 노드 실행 직전에 멈추도록 설정
app = builder.compile(
    checkpointer=memory,
    interrupt_before=["tools"] # 'tools' 노드 진입 전 자동 일시 정지
)

config = {"configurable": {"thread_id": "order-101"}}

# 1. 사용자 요청 실행 ➔ 도구 호출 직전에 정지됨!
app.invoke({"messages": [("user", "관리자 권한으로 서버 재부팅해줘.")]}, config=config)

# 2. 현재 정지된 상태 조회
current_state = app.get_state(config)
print("현재 정지된 노드 직전 단계:", current_state.next) # ('tools',)

# 3. 관리자 승인 후 실행 재개 (None을 넘기면 멈췄던 지점부터 이어서 실행)
final_result = app.invoke(None, config=config)
print("승인 후 최종 실행 결과:", final_result["messages"][-1].content)
```

---

## 9. 실시간 스트리밍 (Streaming)

에이전트의 노드 진행 단계와 생성 토큰을 사용자 화면에 실시간으로 출력하는 방법입니다.

```python
# 노드 단위 실행 결과 실시간 스트리밍
for event in app.stream({"messages": [("user", "부산 날씨 알려줘")]}, config=config):
    for node_name, state_update in event.items():
        print(f"\n--- [노드 완료: {node_name}] ---")
        if "messages" in state_update:
            print("최신 메시지:", state_update["messages"][-1].content)
```

---

## 10. 프로덕션 개발 체크리스트

| 점검 항목 | 권장 사항 | 이유 |
| :--- | :--- | :--- |
| **State 최소화** | 꼭 필요한 필드만 State에 선언 | 매 노드마다 상태 스냅샷이 직렬화되므로 크기 절감 |
| **리듀서 사용** | 대화 기록은 `add_messages` 필수 적용 | 덮어쓰기 방지 및 멀티턴 대화 보존 |
| **DB 영속화** | 운영 환경에서는 `PostgresSaver` 도입 | 서버 재시작 시에도 수십만 유저 세션 유지 |
| **HITL 승인 절차** | 금융 결제/DB 수정 도구는 `interrupt_before` 지정 | LLM 환각(Hallucination)에 의한 오작동 원천 차단 |
| **트레이싱 활성화** | `LANGCHAIN_TRACING_V2=true` 설정 | LangSmith에서 전체 그래프 경로와 지연시간 시각화 |
💬
LangGraph 치트시트

의견 및 질문

댓글 수정

댓글 삭제
