프레임워크

LangGraph: 유향 그래프로 Agent를 오케스트레이션하는 4만 스타 산업용 프레임워크

Agent를 그래프로 실행하는 방식—루프, 분기, 상태 영속화, 사람-기계 협업까지 하나의 프레임워크에서 해결한다. LangGraph는 이미 프로덕션 환경 Agent 오케스트레이션의 사실상 표준 중 하나가 됐다.

글자 크기

LangGraph는 GitHub에서 이미 40k 이상의 스타를 받았으며, 현재 Agent 오케스트레이션 영역에서 가장 많이 쓰이는 프레임워크 중 하나다. 핵심 아이디어는 한 문장으로 정리된다: Agent의 실행 흐름을 유향 그래프로 모델링한다. 루프, 분기, 상태 영속화, 사람-기계 승인까지 모두 그래프 구조 위에서 처리한다.

아래에서는 문제 정의, 사용법, 아키텍처, 장단점, 직접 실행해 본 결과, 적용 대상 여섯 가지 관점으로 정리한다.

해결하려는 문제

기존의 체인 호출(Chain)은 한 방향으로만 흐른다: prompt → llm → parser → next. Agent에 필요한 루프(예: ReAct가 답을 얻을 때까지 도구를 반복 호출), 분기(이번 단계는 tool, 다음 단계는 바로 답변), 사람-기계 승인(계속하기 전에 사용자에게 확인) 같은 상황이 나오면 체인 구조로는 막힌다.

LangChain의 Runnable 시퀀스도 똑같은 한계가 있다. 본질적으로 동기적이고, 방향성이 고정되어 있으며, 한 번에 끝나는 구조다. 롤백, 일시 정지, 세션 간 메모리 같은 시나리오가 필요하면 Runnable만으로는 부족하다.

LangGraph가 정확히 이 빈자리를 메운다. StateGraph로 실행 흐름을 명시적인 유향 그래프로 모델링한다.

  • 노드(Node) = 연산 단위(LLM 호출 한 번, tool 하나, 함수 하나)
  • 엣지(Edge) = 전이 조건(무조건 엣지 / 조건부 엣지)
  • 상태(State) = 전역 데이터 구조로, 노드 사이에서 자동으로 전달됨

그래프 자체가 루프를 지원하기 때문에, ReAct처럼 반복적인 추론이 필요한 Agent를 그래프로 표현하는 것이 자연스럽게 잘 맞는다.

사용법

세 단계면 시작할 수 있다.

  1. State 정의(TypedDict 또는 Pydantic model)
  2. 노드 함수 작성(state를 입력으로 받고, state 업데이트를 반환)
  3. StateGraph로 그래프를 조립하고, checkpoint를 추가한 뒤 compile

핵심 API는 몇 개 안 된다: add_node, add_edge, add_conditional_edges, compile.

아래는 바로 실행 가능한 최소 예제로, 그래프와 조건부 엣지의 기본 사용법을 3단계 루프로 보여준다.

from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

class State(TypedDict):
    messages: list[str]
    step: int

def agent(state: State) -> State:
    return {
        "messages": state["messages"] + [f"step {state['step']} done"],
        "step": state["step"] + 1,
    }

def should_continue(state: State) -> Literal["agent", END]:
    return END if state["step"] >= 3 else "agent"

graph = StateGraph(State)
graph.add_node("agent", agent)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)

app = graph.compile(checkpointer=MemorySaver())
result = app.invoke(
    {"messages": [], "step": 0},
    config={"configurable": {"thread_id": "1"}},
)
print(result)
# {'messages': ['step 0 done', 'step 1 done', 'step 2 done'], 'step': 3}

설치는 한 줄이면 된다.

pip install langgraph

invoke를 호출하면 최종 결과를 받고, stream을 쓰면 매 superstep마다 상태 변화를 볼 수 있다—Agent를 디버깅할 때 특히 유용하다.

동작 방식 (아키텍처)

핵심 요소는 세 가지다.

  • State: 전역 상태 schema. TypedDict 또는 Pydantic을 쓰며, 모든 노드가 읽고 쓰는 공유 데이터 구조
  • Node: 순수 함수 또는 LangChain Runnable. 시그니처는 (state) -> dict
  • Edge: 일반 엣지는 고정 전이, 조건부 엣지(conditional_edges)는 state를 보고 다음 노드를 결정

실행 시 LangGraph 내부에서는 Pregel 스타일의 superstep 루프(Google의 Pregel 그래프 컴퓨팅 시스템에 경의를 표하는 구조)가 돌아간다. 매 superstep마다 다음 순서를 거친다.

  1. 현재 state와 엣지를 바탕으로 이번 라운드에 활성화할 노드 결정
  2. 실행 가능한 노드들을 동시에 실행(따라서 노드 함수를 작성할 때 전역적인 실행 순서를 가정해서는 안 된다)
  3. 노드 출력은 Channels 메커니즘을 통해 병합되어 State에 기록됨(동시 쓰기 충돌을 처리)
  4. 활성화된 노드가 없을 때까지 다음 superstep으로 진행

Checkpoint는 LangGraph의 킬러 기능이다. 매 superstep이 끝날 때마다 프레임워크가 현재 state를 백엔드에 직렬화한다.

  • MemorySaver: 메모리 저장. 재시작하면 사라지므로 테스트용
  • SqliteSaver: 로컬 파일
  • PostgresSaver: 프로덕션 환경 표준. time-travel debug 지원

Checkpoint가 있으면 동일한 thread_id로 invoke를 다시 호출했을 때, 프레임워크가 중단 지점부터 이어서 실행한다. 처음부터 다시 돌리지 않는다. Time-travel debug는 이 능력에서 파생된 기능으로, 임의의 과거 superstep부터 재실행해 그 시점에 무슨 일이 있었는지 확인할 수 있다.

Human-in-the-loop은 구현이 더 간단하다. 특정 노드 앞에 interrupt를 걸어두면, 실행이 거기서 멈추고 상태를 외부에 노출한 뒤 사용자 입력을 기다린다. 사용자가 응답하면 중단 지점부터 다시 진행한다. 그래서 승인, 확인, 수정 같은 상호작용 패턴을 LangGraph로 아주 자연스럽게 구현할 수 있다.

장점과 단점

좋은 점:

  • 그래프 모델이 CrewAI의 "역할 협업" 추상화보다 저수준이고, AutoGen의 그룹 채팅 추상화보다 통제하기 쉽다. 결국 그래프는 그래프고, 노드가 뭔지 엣지가 어떻게 흐르는지는 개발자가 직접 정한다.
  • Checkpoint가 진짜 프로덕션급이라, Postgres 백엔드의 time-travel debug로 문제를 추적하기 매우 편하다.
  • LangChain 생태계와 호환된다(Runnable, tools, messages schema 모두 연동). 하지만 강제로 묶이지는 않는다—langgraph만 설치하고 langchain 없이 쓰는 것도 가능하다.
  • 문서 품질이 오픈소스 프레임워크 중에서는 최상위급이고, 공식 cookbook이常见 패턴을 잘 커버한다.

아쉬운 점:

  • 학습 곡선이 단순 LLM wrapper나 간단한 Chain보다 가파르다. State schema를 잘못 설계하고 분기 조건을 마구 추가하면, 결국 노드 하나에 엣지가 열 개씩 달린 spaghetti graph가 된다. 본인도 못 읽는다.
  • 로컬 디버깅 시 stream 출력이 꽤 장황하다. 매 superstep마다 state를 전부 찍어주기 때문에 초보자는 정보에 묻혀버린다.
  • 새 버전 API(0.2 이후)에서 변경 폭이 크다. 옛날 튜토리얼의 set_entry_point나 add_edge의 파라미터 순서 등이 많이 바뀌어서 그대로 따라 하면 에러가 난다. 코드를 참고할 때는 작성 날짜를 꼭 확인해야 한다.
  • CrewAI의 "플러그 앤 플레이"와 비교하면, LangGraph는 튜링 완전한 튜링 머신을 한 벌 주는 것에 가깝다. 유연하지만 Agent 토폴로지를 직접 설계해야 한다.

직접 실행해 본 결과

pip install langgraph langgraph-checkpoint-sqlite로 설치한 뒤, 공식 튜토리얼의 ReAct agent 예제를 돌려봤다. 5라운드의 tool 호출을 구성해서 로컬 메모리(MemorySaver)에서 실행했을 때 약 12초가 걸렸다.

SqliteSaver로 checkpoint를 켠 뒤, 동일한 thread_id로 두 번째 invoke를 호출하니 중단 지점부터 바로 이어서 실행되어 0.5초 만에 반환됐다. 이 지연 시간 차이는 실무 시나리오에서 매우 중요하다. 긴 작업이 중간에 끊겼다가 재개될 때, 네트워크가 흔들릴 때, 재시도할 때 사용자 경험이 완전히 달라진다.

몇 가지 엣지 케이스를 시험해봤다.

  • StateGraph.compile() 단계에서 순환 검사를 수행하므로, 명백한 무한 루프(셀프 루프 + 무조건 엣지)는 이론적으로 막을 수 있다.
  • 하지만 실제 안전망은 max_steps 설정에 달려 있다. 조건부 엣지 로직을 잘못 짜면 프레임워크가 영원히 지켜주지 않는다.
  • CrewAI 0.80과 동일한 ReAct 작업을 비교했을 때, 시작 오버헤드는 LangGraph가 약간 더 높았다(약 200ms, Pregel 스케줄링 + checkpoint 초기화 비용). 대신 상태 가시성과 복원 능력은 훨씬 낫다.

커뮤니티에서 자주 비교 대상으로 거론되는 프레임워크로는 AutoGen(마이크로소프트, 그룹 채팅식 다중 Agent)과 LlamaIndex Workflows(이벤트 기반)가 있다. 전자는 "자연어" 쪽으로 더 추상화되어 있고(Agent끼리 메시지를 주고받음), 후자는 더 가볍다. LangGraph는 그 중간에 위치한다. 둘보다 구조화되어 있고, "프로그래머 친화적"이다.

이런 경우에 쓰면 좋다

적합한 시나리오:

  • 장기 작업 실행(다라운드 tool 호출, 다단계 추론)
  • 사람의 승인이 필요한 경우(금융, 의료, 컴플라이언스 시나리오의 Agent에는 반드시 HITL이 필요)
  • 세션 간 메모리가 필요한 경우(챗봇, 지속 학습 agent)
  • 관측과 재실행이 가능한 프로덕션 Agent가 필요한 경우(문제 발생 시 과거 checkpoint로 추적)

적합하지 않은 시나리오:

  • 단일 라운드 Q&A: LLM을 그냥 직접 호출하면 된다
  • 1회성 스크립트: 그래프 추상화는 과한 설계
  • 지연 시간에 극도로 민감한(<100ms) 실시간 인터랙션: 그래프의 스케줄링 오버헤드를 감당할 수 없다

후자의 경우에는 LLM을 직접 호출하거나 LangChain Runnable만으로 충분하다. 그래프 추상까지 갈 필요 없다. LangGraph는 Chain을 대체하는 게 아니라, Chain으로 해결이 안 될 때 가는 다음 단계다.

정리

LangGraph의 본질은 Agent에게 명시적이고, 영속화 가능하며, 중단 능력을 갖춘 실행 모델을 제공하는 것이다. 가장 사용하기 쉬운 도구는 아니지만, 실제 프로덕션에 올릴 수 있는 Agent—특히 루프, 승인, 장기 메모리, 재실행이 필요한 경우—를 만든다면 현재로서는 가장 성숙한 선택지다.

40k 스타는 공짜로 쌓인 게 아니다. GitHub 저장소 주소는 https://github.com/langchain-ai/langgraph이며, README와 examples/ 디렉터리만 봐도 바로 시작할 수 있다.

출처: https://github.com/langchain-ai/langgraph