프론트엔드 개요

프론트엔드 개요 (Overview)

LangGraph 에이전트를 프론트엔드로 렌더링해요.

LangGraph 파이프라인을 실시간으로 시각화하는 프론트엔드를 만들 수 있어요. 이 패턴들은 커스텀 StateGraph 워크플로우에서 노드별 상태와 스트리밍 콘텐츠로 다단계 그래프 실행을 렌더링하는 방법을 보여줍니다.

출처: 문서

본문

LangGraph의 프론트엔드 강점은 UI가 그래프와 같은 구조를 따라갈 수 있다는 점이에요. 노드(node), 상태 키(state key), 체크포인트(checkpoint), 인터럽트(interrupt), 서브그래프(subgraph), 스트리밍된 메시지가 모두 런타임에서 볼 수 있는 개념이라, 실행을 하나의 어시스턴트 메시지 뒤에 숨기는 대신 시스템이 무엇을 하고 있는지 설명해 주는 인터페이스를 만들 수 있습니다.

이 패턴들은 v1 프론트엔드 SDK 패키지를 사용해요. 이전 버전을 쓰고 있다면 [React](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/docs/v1-migration.md), [Vue](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/docs/v1-migration.md), [Svelte](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/docs/v1-migration.md), [Angular](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/docs/v1-migration.md) 마이그레이션 가이드를 참고하세요.

아키텍처 (Architecture)

LangGraph 그래프는 엣지(edge)로 연결된 이름 있는 노드들로 구성돼요. 각 노드는 한 단계(분류, 조사, 분석, 종합)를 실행하고 특정 상태 키에 출력을 씁니다. 프론트엔드에서 SDK 스트림 핸들은 노드 출력, 스트리밍 토큰, 발견된 서브그래프에 대한 반응형 접근을 제공해서 각 노드를 UI 카드에 매핑할 수 있게 해줍니다.

%%{
  init: {
    "fontFamily": "monospace",
    "flowchart": {
      "curve": "curve"
    }
  }
}%%
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

  classDef blueHighlight fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A;
  classDef greenHighlight fill:#DCFCE7,stroke:#16A34A,color:#14532D;
  classDef orangeHighlight fill:#FEF3C7,stroke:#D97706,color:#92400E;
  class FRONTEND blueHighlight;
  class GRAPH greenHighlight;
  class N1,N2,N3 orangeHighlight;

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는 injectStream으로 같은 스트림 API 형태를 사용합니다.

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()];
}

채팅 스트림과 무엇이 다른가 (What makes this different from a chat stream)

커스텀 그래프는 종종 제품 워크플로우를 구동합니다. 조사 파이프라인, 승인 흐름, 데이터 파이프라인, 데이터 강화, 코드 리뷰, 계획, 다단계 분석 등이요. 프론트엔드 SDK를 쓰면 그래프 네이티브 신호로 이런 워크플로우를 렌더링할 수 있어요:

런타임 개념 프론트엔드 UX
이름 있는 노드 그래프 노드마다 카드 하나, 타임라인 단계 하나, 상태 배지 하나.
상태 키 분류, 출처, 분석, 최종 종합 같은 타입 있는 출력을 위한 전용 UI 영역.
스트리밍 메타데이터 부분 메시지를 그것을 만들어 낸 노드로 라우팅.
체크포인트 이전 그래프 상태를 검사하거나 재개 — 디버깅과 감사(auditability)에 유용.
인터럽트 사람의 입력·승인·수정을 위해 노드를 일시 중지한 뒤 계속 진행.
서브그래프 사용자가 더 자세한 내용이 필요할 때만 중첩 실행을 드러내기.

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

패턴 (Patterns)

Graph execution — 다단계 그래프 파이프라인을 노드별 상태와 스트리밍 콘텐츠로 시각화.

Custom stream channels — 커스텀 서버 측 데이터를 프론트엔드로 스트리밍하고 useExtension과 useChannel로 읽기.

LangChain 프론트엔드 패턴 — 마크다운 메시지, 도구 호출, human-in-the-loop, 재개 가능한 스트림, time travel — 은 어떤 LangGraph 그래프에서도 동작해요. createAgent, createDeepAgent, 커스텀 StateGraph 중 무엇을 쓰든 스트림 API가 같은 핵심 데이터 모델을 제공합니다.

더 알아보기 (Learn more)