LangGraph 입문 — 상태 기반 워크플로우 만들기

📌 3줄 요약
· LangGraph는 LangChain 위에서 동작하며, 작업 흐름을 그래프(노드와 엣지) 형태로 그려 복잡한 LLM 애플리케이션을 설계하도록 돕는 도구예요.
· 핵심은 상태(State)라는 공유 메모리로, 각 노드가 이 상태를 읽고 갱신하며 다음 단계로 넘겨 줍니다.
· 덕분에 조건 분기·반복·되돌아가기처럼 일직선 체인으로는 표현하기 어려운 흐름을 자연스럽게 만들 수 있습니다.
📥 상태 입력 → ⚙️ 노드 실행 → 🔀 엣지로 이동 → 📤 상태 갱신

LangChain으로 체인을 엮다 보면, 어느 순간 일직선 흐름의 한계를 느끼게 됩니다. "이 조건이면 A 단계로, 아니면 B 단계로 보내고 싶다", "결과가 만족스럽지 않으면 앞 단계로 되돌아가 다시 시도하고 싶다" 같은 요구가 생기기 때문이죠. 이런 복잡한 흐름을 깔끔하게 표현하기 위해 등장한 것이 바로 LangGraph입니다. 오늘은 LangGraph가 무엇이고, 그 중심에 있는 상태(State)라는 개념이 어떻게 전체 흐름을 이끄는지 차근차근 살펴보겠습니다.

🤔 왜 체인만으로는 부족할까

기본적인 체인은 입력 → 처리 → 출력으로 이어지는 한 방향 흐름입니다. 간단한 질문-응답에는 충분하지만, 실제 애플리케이션은 그보다 훨씬 복잡한 경우가 많아요. 예를 들어 답을 만든 뒤 품질을 점검하고, 기준에 못 미치면 다시 생성하도록 되돌리는 흐름을 생각해 봅시다.

이런 분기와 반복은 일직선 체인으로 표현하기가 상당히 까다롭습니다. LangGraph는 작업 흐름을 그래프로 바라봅니다. 각 작업을 점(노드)으로 두고, 그 사이를 선(엣지)으로 이으면, 갈림길도 되돌아가는 길도 자연스럽게 그릴 수 있게 되죠.

LangGraph의 발상은 "흐름을 한 줄로 늘어놓지 말고, 지도처럼 그려 보자"는 것입니다.

🧩 LangGraph의 세 가지 재료 — 상태·노드·엣지

LangGraph를 이해하려면 세 가지 요소만 기억하면 됩니다. 이 셋이 어우러져 하나의 워크플로우를 이룹니다.

📦 상태(State)
그래프 전체가 공유하는 데이터입니다. 노드들이 함께 읽고 쓰는 공용 노트라고 보면 됩니다.
⚙️ 노드(Node)
하나의 작업 단위입니다. 상태를 입력으로 받아 일을 하고, 갱신된 상태를 돌려줍니다.
🔀 엣지(Edge)
노드와 노드를 잇는 이동 경로입니다. 어느 노드 다음에 어디로 갈지를 정합니다.

정리하면 노드가 일을 하고, 엣지가 길을 안내하며, 상태가 그 사이를 흐르는 데이터입니다. 이 셋을 조립하는 것이 곧 LangGraph로 워크플로우를 만드는 일이에요.

📦 상태(State)가 흐름을 이끈다

LangGraph에서 가장 중요한 개념은 단연 상태(State)입니다. 상태는 그래프가 도는 동안 계속 들고 다니는 데이터 묶음이에요. 보통 질문, 중간 결과, 최종 답변처럼 흐름에 필요한 값들을 담습니다.

각 노드는 이 상태를 입력으로 받아 자기 일을 한 뒤, 바뀐 부분을 돌려줍니다. 그러면 LangGraph가 그 변경분을 상태에 반영하고, 다음 노드로 넘겨 주죠. 즉 노드들은 서로 직접 대화하지 않고, 오직 상태를 통해서만 정보를 주고받습니다. 이 구조 덕분에 흐름이 아무리 복잡해져도 데이터가 지금 어떤 상태인지를 한곳에서 파악할 수 있습니다.

💻 코드로 보는 가장 작은 그래프

개념을 코드로 옮겨 보겠습니다. 상태의 모양을 정의하고, 노드 함수를 만든 뒤, 그래프에 노드와 엣지를 등록하는 순서입니다.

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

# 1) 상태의 모양을 정의한다
class State(TypedDict):
    question: str
    answer: str

# 2) 노드 함수 — 상태를 받아 바뀐 부분을 돌려준다
def answer_node(state: State):
    q = state["question"]
    return {"answer": f"'{q}'에 대한 답변입니다"}

# 3) 그래프에 노드와 엣지를 등록한다
builder = StateGraph(State)
builder.add_node("answer", answer_node)
builder.add_edge(START, "answer")
builder.add_edge("answer", END)

graph = builder.compile()
result = graph.invoke({"question": "LangGraph가 뭐예요?"})
print(result["answer"])

흐름을 따라가 보면, START에서 출발해 answer 노드를 거쳐 END로 끝납니다. 노드는 상태에서 question을 꺼내 쓰고, answer라는 바뀐 부분만 돌려줬어요. 이렇게 상태의 모양 → 노드 → 엣지 순으로 조립하는 것이 LangGraph의 기본 패턴입니다.

🔀 조건 분기로 흐름 나누기

LangGraph의 진짜 강점은 갈림길을 만들 수 있다는 점입니다. 상태의 값에 따라 다음에 어느 노드로 갈지를 그때그때 결정할 수 있어요. 이를 조건부 엣지(conditional edge)라고 부릅니다.

# 상태를 보고 다음 노드 이름을 돌려주는 판단 함수
def route(state: State):
    if state["answer"]:
        return "done"      # 답이 있으면 종료 쪽으로
    return "retry"         # 없으면 다시 시도 쪽으로

builder.add_conditional_edges(
    "answer",              # 이 노드 다음에
    route,                 # 이 함수로 길을 고른다
    {"done": END, "retry": "answer"},
)

여기서 route 함수는 상태를 들여다보고 다음에 갈 곳의 이름을 돌려줍니다. 답이 있으면 종료로, 없으면 다시 answer 노드로 돌아가게 되죠. 이렇게 상태에 기반해 길이 갈라지는 구조가, 일직선 체인과 LangGraph를 가르는 핵심 차이입니다.

🔧 실무 팁

  • 상태 설계부터 시작하라 — 그래프를 그리기 전에 어떤 값을 들고 다닐지부터 정하면, 노드를 만들 때 훨씬 수월합니다.
  • 노드는 작게 쪼개라 — 하나의 노드가 너무 많은 일을 하면 디버깅이 어렵습니다. 한 노드엔 한 가지 책임이 좋습니다.
  • 반복 흐름엔 종료 조건을 꼭 두라 — 되돌아가는 경로를 만들 때는 언제 멈출지를 상태로 관리해, 무한 반복에 빠지지 않도록 하세요.
  • 먼저 흐름을 그려 보라 — 코드를 쓰기 전에 노드와 엣지를 종이에 그려 보면, 복잡한 워크플로우도 머릿속이 정리됩니다.

❓ 자주 묻는 질문 (FAQ)

Q. LangGraph는 LangChain을 대체하나요?
A. 대체라기보다 보완에 가깝습니다. LangChain이 모델 호출·프롬프트 같은 부품을 제공한다면, LangGraph는 그 부품들을 복잡한 흐름으로 엮는 틀을 제공합니다.

Q. 간단한 질문-응답에도 LangGraph가 필요한가요?
A. 꼭 그렇지는 않습니다. 일직선 흐름으로 충분하다면 기본 체인이 더 간결해요. 분기·반복·되돌아가기가 필요해질 때 LangGraph가 빛을 발합니다.

Q. 상태에는 아무 값이나 담아도 되나요?
A. 흐름에 필요한 값을 담으면 됩니다. 다만 상태의 모양을 미리 정의해 두면, 어떤 데이터가 오가는지 명확해져 관리가 쉬워집니다.

마무리

정리하면, LangGraph는 LLM 애플리케이션의 흐름을 그래프로 그려 복잡한 워크플로우를 설계하게 해 주는 도구이고, 그 중심에는 모든 노드가 공유하는 상태(State)가 있습니다. 노드가 상태를 받아 일하고, 엣지가 다음 길을 안내하며, 조건부 엣지로 갈림길과 반복까지 표현할 수 있어요. 일직선 체인으로 답답했던 흐름이 있었다면, LangGraph의 상태 기반 설계가 좋은 돌파구가 될 것입니다. 다음 편에서는 그래프 안에서 스스로 도구를 골라 쓰는 에이전트를 LangGraph로 구성하는 이야기로 이어가 보겠습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

LCEL — LangChain 표현식으로 체인 깔끔하게 잇기

📌 3줄 요약 · LCEL(LangChain Expression Language) 은 여러 단계를 파이프 기호(|) 로 이어 하나의 체인으로 만드는 방식이에요. · 프롬프트 → 모델 → 출력 파서처럼 흐름이 그대로 코드에 보여서 읽기 쉽고 수정도 간편합니다. · 스트리밍·배치·비동기 같은 기능을 따로 구현하지 않아도 체인 전체에서 바로 쓸 수 있습니다. 📖 목차 LCEL이 왜 필요할까 파이프(|)로 잇는다는 발상 체인의 기본 3단 구성 코드로 보는 LCEL LCEL이 공짜로 주는 기능들 실무 팁 자주 묻는 질문(FAQ) 📝 프롬프트 → 🤖 모델 → 🔧 출력 파서 → ✅ 결과 LangChain으로 뭔가를 만들다 보면, 프롬프트를 만들고 모델에 넣고 그 결과를 다시 다듬는 여러 단계 가 반복됩니다. 예전에는 이걸 함수로 하나씩 호출하며 이어 붙였는데, 코드가 길어질수록 흐름을 알아보기 어려웠어요. 이 불편을 깔끔하게 정리한 것이 바로 LCEL(LangChain Expression Language) 입니다. 오늘은 LCEL이 무엇이고 왜 편한지 차근차근 살펴보겠습니다. 🤔 LCEL이 왜 필요할까 LLM 앱은 대부분 여러 단계가 순서대로 이어지는 구조 입니다. 사용자 질문을 받아 프롬프트 틀에 채우고, 그걸 모델에 보내고, 모델이 돌려준 답을 원하는 형태로 정리하는 식이죠. 각 단계를 따로 함수로 부르면 이렇게 됩니다. 단계가 두세 개일 땐 괜찮지만, 중간에 검색이나 조건 분기가 끼면 어디서 무엇이 넘어가는지 한눈에 파악하기 어려워집니다. 게다가 스트리밍이나 병렬 처리를 넣으려면 단계마다 코드를 또 손봐야 하죠. LCEL의 목표는 간단합니다. "단계를 이어 붙이는 일"을 눈에 보이게, 그리고 한 번만 만들자는 것입니다. 🔗 파이프(|)로 잇는다는 발상 LCEL의 핵심은 파이프 기호 | 하나입니다. 리눅스 터미널에서 명령어1 | 명령어2 로 앞 결과를 뒤로 ...
자세한 내용 보기

Streaming — 답변을 실시간으로 흘려보내기

📌 3줄 요약 · 스트리밍(Streaming) 은 모델의 답변을 다 만들어진 뒤 한꺼번에 주는 대신, 생성되는 대로 조금씩 흘려보내는 방식이에요. · LangChain에서는 invoke 대신 stream 을 쓰면, 답변이 토큰 단위로 순서대로 도착합니다(타이핑 효과). · 체감 대기 시간이 크게 줄어 챗봇처럼 즉각 반응하는 UX 를 만들 때 특히 유용합니다. 📖 목차 스트리밍이 왜 필요할까 한 번에 vs 조금씩, 무엇이 다른가 토큰 단위로 흘려보낸다는 것 코드로 보는 stream stream vs invoke vs batch 실무 팁 자주 묻는 질문(FAQ) 🙋 질문 → 🤖 모델 생성 → 💧 토큰이 하나씩 → 🖥️ 화면에 실시간 챗봇에 질문을 던졌을 때, 답이 한 글자씩 타이핑되듯 나타나는 화면을 본 적 있을 거예요. 이건 답변이 다 완성될 때까지 기다렸다가 한꺼번에 보여 주는 게 아니라, 모델이 글자를 만들어 내는 즉시 화면으로 흘려보내기 때문에 가능한 일입니다. 이 방식을 스트리밍(Streaming) 이라고 부릅니다. 오늘은 LangChain에서 스트리밍이 무엇이고 왜 유용한지, 그리고 어떻게 쓰는지 차근차근 살펴보겠습니다. 🤔 스트리밍이 왜 필요할까 LLM은 답변을 앞에서부터 순서대로 한 조각씩 생성합니다. 긴 답변일수록 전체가 완성되기까지 시간이 걸리는데, 완성될 때까지 화면에 아무것도 안 보이면 사용자는 "멈춘 건가?" 하고 답답해집니다. 스트리밍은 이 기다리는 시간을 체감상 크게 줄여 줍니다. 첫 글자가 나오기 시작하는 순간부터 화면에 하나씩 채워지니, 실제 전체 생성 시간이 같아도 훨씬 빠르게 느껴지죠. 특히 대화형 챗봇처럼 반응 속도가 중요한 서비스 에서는 거의 필수적인 요소입니다. 스트리밍의 핵심은 "답을 다 만들 때까지 기다리지 말고, 만들어지는 대로 바로 보여 주자" 는 것입니다. ⚖️ 한 번에 vs 조금씩...
자세한 내용 보기

Callback와 로깅 — LangChain 내부 들여다보기

📌 3줄 요약 · 콜백(Callback) 은 LangChain이 실행되는 중간중간 특정 시점마다 내가 지정한 함수를 자동으로 불러 주는 장치예요. · 이 콜백을 이용하면 체인이 언제 시작하고, 어떤 프롬프트가 들어가고, 어떤 답이 나왔는지 를 실시간으로 들여다보고 로깅 할 수 있습니다. · 덕분에 "왜 이런 답이 나왔지?"를 추적하는 디버깅과 모니터링 이 훨씬 쉬워집니다. 📖 목차 콜백이 왜 필요할까 콜백은 언제 불릴까 — 이벤트라는 개념 로깅과 콜백은 어떻게 연결되나 코드로 보는 콜백 핸들러 대표적인 콜백 이벤트 한눈에 실무 팁 자주 묻는 질문(FAQ) 🚀 체인 시작 → 🔔 이벤트 발생 → 🪝 콜백 호출 → 📝 기록·로깅 체인을 만들어 실행하면, 겉으로는 질문을 넣으면 답이 나오는 단순한 상자처럼 보입니다. 하지만 그 상자 안에서는 프롬프트가 조립되고, 모델이 호출되고, 출력이 정리되는 여러 단계가 순서대로 벌어지고 있어요. 이 내부 과정을 밖에서 들여다볼 수 있게 해 주는 장치가 바로 콜백(Callback) 입니다. 오늘은 콜백이 무엇이고 왜 유용한지, 그리고 이를 활용한 로깅 이 어떻게 이뤄지는지 차근차근 살펴보겠습니다. 🤔 콜백이 왜 필요할까 체인이 예상과 다른 답을 내놓았을 때, 우리가 볼 수 있는 건 보통 최종 결과 하나뿐 입니다. 그런데 문제의 원인은 대개 중간에 있어요. 실제로 어떤 프롬프트가 모델에 들어갔는지 , 모델이 어떤 원문을 돌려줬는지 를 모르면 원인을 짚기 어렵습니다. 콜백은 이 보이지 않던 중간 과정을 밖으로 꺼내 주는 역할을 합니다. 체인이 시작될 때, 모델이 호출될 때, 답이 완성될 때처럼 중요한 순간마다 내가 등록해 둔 함수가 자동으로 실행되죠. 그래서 실행 흐름을 기록하고 추적하는 일 이 한결 수월해집니다. 콜백의 핵심은 "실행 중간의 특정 순간마다, 내가 원하는 코드를 끼워 넣을 수 있게 하자" 는 것입...
자세한 내용 보기