LangGraph 그래프를 프론트엔드로 렌더링하기

LangGraph 그래프를 프론트엔드로 렌더링하기 (Overview)

LangGraph로 만든 파이프라인을 백엔드에서만 돌리고 있나요? 이제 그 실행 과정을 실시간으로 시각화하는 프론트엔드를 만들 수 있어요. 여기서 소개하는 패턴은 커스텀 StateGraph 워크플로의 각 노드 상태와 스트리밍 콘텐츠를 화면에 그리는 방법을 보여줘요. 핵심은 UI가 그래프와 같은 구조를 따라간다는 점이에요.

출처: 공식문서

LangGraph 프론트엔드의 가장 큰 장점은 화면(UI)이 그래프 구조 그대로를 따라갈 수 있다는 거예요. 노드, state key, 체크포인트, 인터럽트, 서브그래프, 스트리밍 메시지는 모두 런타임에서 눈에 보이는 개념이라, 단순히 에이전트 메시지 하나로 실행을 숨기는 대신 "지금 시스템이 뭘 하고 있는지" 설명하는 인터페이스를 만들 수 있어요.

이 패턴들은 v1 프론트엔드 SDK 패키지를 사용해요. 이전 버전을 쓰고 있다면 React, Vue, Svelte, Angular 마이그레이션 가이드를 참고하세요.

아키텍처

LangGraph 그래프는 엣지로 연결된 이름 있는 노드들로 구성돼요. 각 노드는 한 단계를 실행하고(분류, 리서치, 분석, 종합) 결과를 특정 state key에 써요. 프론트엔드에서는 SDK의 stream handle이 노드 출력, 스트리밍 토큰, 발견된 서브그래프에 대한 반응형 접근을 제공해서, 각 노드를 UI 카드 하나에 매핑할 수 있어요.

graph LR
  FRONTEND["useStream()"]
  GRAPH["StateGraph"]
  N1["Node A"]
  N2["Node B"]
  N3["Node C"]

  GRAPH --"stream"--> FRONTEND
  FRONTEND --"submit"--> GRAPH
  GRAPH --> N1
  N1 --> N2
  N2 --> N3

from langgraph.graph import StateGraph, MessagesState, START, END

class State(MessagesState):
    classification: str
    research: str
    analysis: str
    synthesis: str

graph = StateGraph(State)
graph.add_node("classify", classify_node)
graph.add_node("do_research", research_node)
graph.add_node("analyze", analyze_node)
graph.add_node("synthesize", synthesize_node)
graph.add_edge(START, "classify")
graph.add_edge("classify", "do_research")
graph.add_edge("do_research", "analyze")
graph.add_edge("analyze", "synthesize")
graph.add_edge("synthesize", END)

app = graph.compile()

프론트엔드에서는 useStream이 그래프 노드를 탐색하기 위한 stream.subgraphs와, 노드 범위 스트리밍 콘텐츠를 위한 useMessages(stream, node) 같은 셀렉터 헬퍼를 노출해요. 전체 그래프 상태가 필요할 때는 stream.values에서 최종 synthesis 같은 필드를 꺼낼 수 있어요. Angular는 같은 stream API 구조를 injectStream으로 사용해요.

import { useStream } from "@langchain/react";

function Pipeline() {
  const stream = useStream<typeof graph>({
    apiUrl: "http://localhost:2024",
    assistantId: "pipeline",
  });

  const classification = stream.values?.classification;
  const research = stream.values?.research;
  const analysis = stream.values?.analysis;
  const graphNodes = [...stream.subgraphs.values()];
}

채팅 스트림과 무엇이 다른가

커스텀 그래프는 종종 실제 제품 워크플로를 구동해요—리서치 파이프라인, 승인 흐름, 데이터 파이프라인, 데이터 보강, 코드 리뷰, 계획, 다단계 분석 같은 것들이죠. 프론트엔드 SDK는 이 워크플로를 그래프 네이티브 신호로 렌더링하게 해줘요.

런타임 개념	프론트엔드 UX
이름 있는 노드 (Named nodes)	그래프 노드 하나당 카드 한 장, 타임라인 스텝, 상태 배지 하나씩.
State key	classification·sources·analysis·최종 synthesis 같은 타입 있는 출력을 위한 전용 UI 영역.
스트리밍 메타데이터	부분 메시지를 그것을 생성한 노드로 라우팅.
체크포인트 (Checkpoints)	이전 그래프 상태를 검사하고 재개 — 디버깅·감사 용도.
인터럽트 (Interrupts)	인간 입력, 승인, 수정을 위해 노드를 일시 중지한 뒤 계속 진행.
서브그래프 (Subgraphs)	사용자가 더 자세한 내용이 필요할 때만 중첩 실행을 드러냄.

SDK가 이런 개념을 직접 노출하기 때문에, 백엔드 프로토콜을 바꾸지 않고도 단순한 채팅 패널에서 완전한 워크플로 디버거까지 확장할 수 있어요.

패턴

Graph execution — 다단계 그래프 파이프라인을 노드별 상태와 스트리밍 콘텐츠로 시각화. 자세히
Custom stream channels — 커스텀 서버 측 데이터를 프론트엔드로 스트리밍하고 useExtension와 useChannel로 읽기. 자세히

더 알아보기 (Learn more)

그래프 실행 시각화: Graph execution
커스텀 스트림 채널: Custom stream channels
LangChain 프론트엔드 패턴 전체: 관련 패턴

LangGraph 그래프를 프론트엔드로 렌더링하기