🧭 LangGraph 완전 정복 ⑦ — LangGraph + UI 통합 (Gradio, Streamlit)

“코드에서 흐름으로, 흐름에서 인터랙션으로.”
LangGraph 그래프를 시각화하고 실시간 조작 가능한 UI로 연결하기.

---

🎯 1. 목표

지금까지의 LangGraph는 콘솔 중심으로 실행되었죠.
하지만 실제 응용에서는 사용자 입력, 상태 표시, 그래프 시각화, 디버깅 로그가 필요합니다.

이번 편에서는 다음을 모두 다룹니다.

✅ LangGraph + Gradio: 그래프 기반 채팅 인터페이스
✅ LangGraph + Streamlit: 노드 상태 시각화 대시보드
✅ 실시간 상태 업데이트 (WebSocket / Callback)

---

🧩 2. 기본 구조 개요

📊 LangGraph + UI 통합 구조:

각 노드의 실행 상태를 UI에 표시하고, 사용자의 입력(텍스트·버튼 등)이 그래프 실행을 트리거하는 구조입니다.

---

⚙️ 3. Gradio 연동 예시: 대화형 그래프 앱

LangGraph는 Gradio와 아주 쉽게 통합됩니다.
LLM 호출 결과를 스트리밍하거나, 노드 실행 결과를 실시간 표시할 수 있습니다.

import gradio as gr
from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI

# 상태 정의
class ChatState:
    messages: list[str]

# 그래프 정의
def chat_node(state: ChatState):
    llm = ChatOpenAI(model="gpt-4o-mini")
    user_msg = state.messages[-1]
    reply = llm.invoke(user_msg)
    state.messages.append(reply.content)
    return state

graph = StateGraph(ChatState)
graph.add_node("chat", chat_node)
graph.set_entry_point("chat")
graph.set_finish_point("chat")
app = graph.compile()

# Gradio 인터페이스
def chat_fn(user_input, history):
    state = ChatState(messages=history + [user_input])
    result = app.invoke(state)
    return result.messages, result.messages

ui = gr.ChatInterface(
    fn=chat_fn,
    title="LangGraph Chatbot",
    description="LangGraph 노드 기반 LLM 대화 흐름 예시",
)

ui.launch()

✅ 실행 후:

• 사용자의 입력이 StateGraph에 전달되고,
• LangGraph가 상태를 업데이트하며,
• Gradio 채팅창에 실시간 결과가 반영됩니다.

---

🔁 4. 상태 추적 + 시각화

LangGraph는 내부 상태를 시각화하는 기능을 제공합니다.

graph.visualize("chat_flow.png")

또는 Gradio UI 내부에서 직접 상태를 표시할 수도 있습니다:

def debug_panel(state):
    return f"현재 메시지 수: {len(state.messages)}\n최근 응답: {state.messages[-1]}"

Gradio에서 state를 출력 영역으로 연결하면, 대화뿐 아니라 내부 흐름을 함께 모니터링할 수 있습니다.

---

🧠 5. Streamlit 통합 예시: 그래프 상태 대시보드

Streamlit은 LangGraph 실행 로그를 실시간 시각화하기에 적합합니다.

import streamlit as st
from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI

# 상태
class QAState:
    query: str
    answer: str

# 노드
def answer_node(state: QAState):
    llm = ChatOpenAI(model="gpt-4o-mini")
    res = llm.invoke(f"Q: {state.query}\nA:")
    state.answer = res.content
    return state

graph = StateGraph(QAState)
graph.add_node("answer", answer_node)
graph.set_entry_point("answer")
graph.set_finish_point("answer")
app = graph.compile()

# Streamlit UI
st.title("LangGraph QA Dashboard")

query = st.text_input("질문을 입력하세요:")
if st.button("실행"):
    state = app.invoke({"query": query})
    st.subheader("LLM 응답")
    st.write(state["answer"])
    st.image(graph.visualize("graph.png"))

✅ 실행 후:

• 입력창에 질문 입력
• LangGraph 실행 결과 즉시 표시
• graph.visualize()로 그래프 이미지 표시

---

🧰 6. WebSocket 기반 실시간 이벤트 처리 (고급)

LangGraph 실행 중간에 각 노드의 상태를 실시간으로 브로드캐스트하려면 CallbackManager나 WebSocket을 사용할 수 있습니다.

from langgraph.callbacks.base import CallbackManager

def on_node_start(node_name, state):
    print(f"[Node Start] {node_name}")

def on_node_end(node_name, state):
    print(f"[Node End] {node_name}")

manager = CallbackManager(
    on_node_start=on_node_start,
    on_node_end=on_node_end
)

app = graph.compile(callbacks=manager)

이 데이터를 WebSocket으로 스트리밍하면 실시간 그래프 “노드 실행 로그” UI를 만들 수 있습니다.

---

🎨 7. 실전 UX 설계 팁

목적	구현 방식	비고
대화형 챗봇	gr.ChatInterface	직관적 인터랙션
대시보드형	Streamlit	상태·노드 시각화
실시간 추적	CallbackManager / WS	디버깅 및 운영용
노드별 로그	각 노드 내 print 또는 state.log.append()	상태 기반 로깅
Mermaid 시각화	graph.visualize() or 직접 Mermaid 코드 생성	문서 자동화 가능

---

🧭 8. 다음 회차 예고

👉 8편: 실전 아키텍처 설계 & Best Practice
마지막 편에서는 지금까지 배운 내용을 종합하여 대규모 그래프 설계, 성능 최적화, 오류 처리, 배포 전략을 모두 다룹니다.

---

🎓 9. 더 깊이 배우기 위한 고급 확장 학습 가이드

주제	학습 이유	추천 학습 방향
Event-driven UI	실시간 그래프 실행 상태 반영	WebSocket, async callback
Graph Visualization Libraries	그래프를 인터랙티브하게 시각화	D3.js, Cytoscape.js, NetworkX
LangGraph Callback System	노드 실행 상태 모니터링	CallbackManager, custom logger
LangServe Integration	UI와 그래프 백엔드 분리	LangServe REST endpoint
Frontend-Graph Sync	상태 객체를 UI와 양방향 동기화	React + FastAPI 조합
User Feedback Loop (HITL UI)	사용자 피드백을 그래프에 직접 반영	평가용 버튼, 수정 피드백 이벤트

---

📚 핵심 요약

• LangGraph는 Gradio/Streamlit과 결합하여 시각적 워크플로우 인터페이스를 만들 수 있다.
• Gradio는 실시간 대화용, Streamlit은 분석·디버깅용으로 적합하다.
• Callback과 WebSocket을 통해 그래프의 실시간 상태 추적도 가능하다.

💡 코드로 설계한 그래프가 이제 눈앞의 “흐름”으로 보이기 시작한다.