2 – LangGraph 소개

‘LangChain 시리즈’ 두 번째 편입니다. 이번 글에서는 LangGraph의 탄생 배경, 설치 방법, 기본 사용법, 내부 구조, 실전 팁, 그리고 멀티‑에이전트 Hello World 예제까지 단계별로 살펴보겠습니다.

---

1. LangGraph란 무엇인가?

LangGraph는 LangChain 팀이 2024년 4분기에 공개한 상태 지향 워크플로우 프레임워크입니다. 복잡한 LLM 호출, 외부 Tool 사용, 인간 개입(HITL)을 그래프(노드·엣지) 모델로 정의하고, 체크포인트 DB에 상태를 기록해 긴 작업을 신뢰성 있게 실행·재시작할 수 있도록 설계되었습니다.

1‑1. LangGraph의 필요성

시나리오	기존 방식	LangGraph 방식
장시간 분석 보고	한 번에 요약 → 토큰 초과·타임아웃	단계별 처리, 중간 결과 저장, 오류 시 Resume
다중 에이전트 협업	파이썬 코드로 메시지 수동 라우팅	Supervisor·Network 템플릿으로 노드 연결
사용자 승인 Loop	직접 if/while 로직 작성	pause()‑resume() 내장, HITL 간단 연결
AutoGPT류 자동화	무한 루프 + time.sleep	Loop Node + Max Iterations + 체크포인트

1‑2. LangGraph가 해결하는 네 가지 고질병

1. 내구성 – 노드 실행 결과를 DB에 저장하여 최소‑1회 실행을 보장합니다.
2. 가시성 – LangSmith 통합으로 노드별 입력·출력·토큰 사용량을 시각화합니다.
3. 복잡한 제어 흐름 – 조건 분기, 병렬, 루프, 타임트래블(롤백)을 지원합니다.
4. 역할 분리 – 전문 에이전트를 네트워크·계층 구조로 조직화해 높은 응집도/낮은 결합도를 확보합니다.

한줄 요약 : LangGraph는 LangChain 컴포넌트를 오케스트레이션하는 “LLM용 쿠버네티스”입니다.

---

2. LangChain vs LangGraph 비교

항목	LangChain	LangGraph	비고
주요 책임	체인·에이전트 조립	워크플로우·상태 관리	계층적 관계
실행 단위	Runnable (함수형 파이프)	Graph Node (Stateful Runnable)	Node ≈ Runnable + State
상태 저장소	메모리 또는 Redis	SQLite·DuckDB·Postgres	백엔드 교체 가능
제어 흐름	순차·조건·병렬(LCEL)	순차·조건·병렬 + 루프·스케줄·타임트래블	on_event() Hook
멀티에이전트 템플릿	수동 구현	Supervisor·Network·Hierarchical	4개 패턴 제공
Human‑in‑the‑loop	사용자 정의 Callback	pause()‑resume() 내장	Slack·Webhook 예시
에러 복구	예외처리 수동	체크포인트 기반 Resume	재시도·Skip 전략
대표 사용처	단일 RAG·챗봇	AutoGPT, 장시간 크롤링	대규모 작업

정리  : LangChain이 부품을 만든다면, LangGraph는 그 부품을 연결해 시스템을 돌립니다.

---

3. 설치 · 환경 준비 · 버전 체크

3‑1. 필수 패키지

# LangChain 0.3.x 이상 설치
pip install "langchain>=0.3.0"
# LangGraph 설치
pip install langgraph
# 모델 프로바이더 예: OpenAI
pip install langchain-openai

3‑2. 권장 환경

항목	최소	권장
Python	3.9	3.11 (성능 향상)
OS	Linux / macOS / WSL	+ Docker (python:3.11‑slim)

3‑3. 환경 변수 관리

.env 파일 예시:

OPENAI_API_KEY=sk‑...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls‑...

python‑dotenv로 로드하거나 Docker 비밀 변수로 주입하세요.

---

4. 내부 아키텍처 · 핵심 개념

4‑1. StateGraph

StateGraph(supervisor, memory=...) 객체는 LangGraph의 컨테이너입니다.

1. 노드 등록 – add_node() 또는 템플릿 함수 호출.
2. 엣지 정의 – 순서, 조건, 반복 로직 지정.
3. 스토리지 선택 – SQLite, DuckDB, Postgres, 커스텀 Driver.
4. 이벤트 Hook – on_start, on_finish, on_error 등.

4‑2. Node 종류

타입	예시	특징
Task	LLM 호출, Tool 실행	입력 → 출력
Control	조건, 루프	흐름 제어
Composite	하위 그래프 래핑	재귀·모듈화

4‑3. Memory 모델

• Thread Memory : 세션별 대화 기록을 thread_messages 테이블에 보존.
• Global Memory : 세션을 초월한 지식. 벡터스토어 또는 KV DB로 관리.

4‑4. 체크포인트 전략

전략	설명	권장 사용처
At Every Node	각 노드 후 저장	최대 안정성
On Error	실패 시만 저장	성능·비용 절감
Manual	코드에서 checkpoint() 호출	맞춤 로직

TIP : 고빈도 워크플로우는 On Error + sqlite WAL 모드로 속도를 확보하세요.

4‑5. LangGraph Studio & CLI

• Studio 웹 UI: 그래프 시각 편집, 실행 로그, 수동 재시작, HITL 승인 버튼 제공.
• CLI : lg run graph.yaml, lg visualize 로 YAML 워크플로우 실행·PNG 추출.

---

5. 멀티‑에이전트 Hello World 튜토리얼

5‑1. 시나리오

사용자 요청 “한국어로 인사해” 를 세 단계로 해결합니다.

1. Greeter → “Hello, World!” 생성.
2. Translator → 한국어 번역.
3. Supervisor → 흐름 제어·최종 응답.

5‑2. 전체 코드

"""hello_graph.py – LangGraph Hello World"""
from langgraph.graph import StateGraph
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
import pathlib

# 1. 공통 LLM 설정
llm = ChatOpenAI(model="gpt-4.1", temperature=0.0)

# 2. 하위 에이전트
greeter = create_react_agent(llm, tools=[], system_message="You are a friendly greeter.")
translator = create_react_agent(llm, tools=[], system_message="You translate English greetings to Korean.")

# 3. 에이전트를 Tool로 래핑
@tool
def run_greeter(_: str) -> str:
    """Generate an English greeting"""
    return greeter.invoke({"input": "hello"})

@tool
def run_translator(text: str) -> str:
    """Translate the input text into Korean"""
    return translator.invoke({"input": text})

# 4. Supervisor
supervisor = create_react_agent(
    llm,
    tools=[run_greeter, run_translator],
    system_message=(
        "You are a supervisor. First call run_greeter, then run_translator.\n"
        "Return ONLY the final Korean greeting."
    ),
)

# 5. 그래프 생성
DB_PATH = pathlib.Path("./hello.db").as_uri()  # sqlite:///hello.db
workflow = StateGraph(supervisor, memory=DB_PATH)

# 6. 실행
if __name__ == "__main__":
    response = workflow.invoke({"input": "한국어 인사"})
    print("Supervisor 응답:", response)

5‑3. 실행 로그 예시 (LangSmith)

[12:03:22] Node(run_greeter)    → "Hello, World!"
[12:03:23] Node(run_translator) → "안녕하세요, 세계!"
[12:03:23] Supervisor           → "안녕하세요, 세계!"

5‑4. 핵심 포인트

코드	키워드	설명
8–10	create_react_agent	도구 0개 → 간단한 에이전트 생성
13–22	@tool	하위 에이전트를 Tool로 노출
25–33	Supervisor Prompt	호출 순서 명시, 출력 형식 제한
37	SQLite URI	Docker에선 절대 경로 권장
40	workflow.invoke	입력 딕셔너리 → Supervisor 프롬프트 삽입

실전 팁 : 노드 실행 시간이 길면 workflow.invoke_async() + await로 비동기 호출하세요.

---

6. 실습 확장 아이디어

1. 상태 루프 – “다시” 입력 시 Translator만 반복.
2. Human Approval – Slack 리액션 /approve 연동.
3. File IO Tool – write_file(path, text) 추가로 결과 저장.
4. 다국어 번역 Pool – 언어 코드별 에이전트 맵 구현.
5. LangGraph Studio 활용 – 그래프 시각화·토큰 사용량 분석.

---

7. FAQ 및 트러블슈팅

**Q1 · **RuntimeError: database is locked

• SQLite WAL 모드를 활성화하거나 DuckDB 백엔드로 전환하십시오.

Q2 · 서버 재시작 후 이어서 실행할 수 있나요?

• 가능합니다. 다음 invoke() 호출 시 체크포인트를 읽어 중단 지점부터 재개합니다. 입력에 해시 키를 부여하면 멱등성이 보장됩니다.

Q3 · Slack 기반 HITL을 연결하려면?

• pause() 상태에서 Webhook → resume(session_id, input) 호출 구조를 사용하십시오.

Q4 · Prefect·Airflow와의 차이는?

• 두 툴은 데이터 파이프라인 중심, LangGraph는 LLM 에이전트 중심입니다. LLM‑특화 기능(토큰 스트리밍·메모리)이 기본 제공됩니다.