프론트엔드 개요

프론트엔드 개요 (Frontend Overview)

createAgent로 만든 에이전트에, 실시간 스트리밍을 곁들인 풍부하고 상호작용적인 프론트엔드를 붙이고 싶다면 바로 이 문서가 시작점이에요. 기본 메시지 렌더링부터, 인간 검토(human-in-the-loop) 승인, 큐 제출(queued submissions), 지속적인 스트림 재참여, 타임 트래블 디버깅 같은 고급 워크플로까지, 이 섹션의 패턴들이 그 모든 것을 다룹니다.

출처: LangChain 공식 문서 — frontend-overview

LangChain 프론트엔드 SDK가 만들어진 이유

LangChain 프론트엔드 SDK는 에이전트 애플리케이션을 위해 만들어졌어요. 토큰만 스트리밍하는 단순 채팅봇이 아니라요. 메시지를 렌더링하는 바로 그 훅이, 에이전트의 지속적인 스레드 상태, 도구 호출 수명주기, 인터럽트, 체크포인트 히스토리, 커스텀 상태 값까지 노출합니다. 그래서 여러분의 UI는 장기 실행되는 에이전트 작업을 위한 제어판(control plane)이 될 수 있어요.

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

아키텍처

모든 패턴은 같은 아키텍처를 따릅니다. createAgent 백엔드가 SDK 스트림 API를 통해 프론트엔드로 상태를 스트리밍하죠.

%%{
  init: {
    "fontFamily": "monospace",
    "flowchart": {
      "curve": "curve"
    }
  }
}%%
graph LR
  FRONTEND["useStream()"]
  BACKEND["createAgent()"]

  BACKEND --"stream"--> FRONTEND
  FRONTEND --"submit"--> BACKEND

  classDef blueHighlight fill:#E5F4FF,stroke:#006DDD,color:#030710;
  classDef greenHighlight fill:#F6FFDB,stroke:#6E8900,color:#2E3900;
  class FRONTEND blueHighlight;
  class BACKEND greenHighlight;

백엔드에서 createAgent는 스트리밍 API를 노출하는 컴파일된 LangGraph 그래프를 만듭니다. 프론트엔드에서 스트림 핸들은 그 API에 연결되어, 메시지, 도구 호출, 인터럽트, 값(values), 스레드 메타데이터 같은 반응형 상태를 제공하고, 어떤 프레임워크로든 렌더링할 수 있어요.

왜 LangChain 프론트엔드 SDK를 쓸까요?

대부분의 AI UI 라이브러리는 스트리밍된 텍스트를 채팅 기록에 덧붙여 주는 데 그칩니다. LangChain SDK는 프로덕션 에이전트가 필요로 하는 더 풍부한 런타임 의미론을 노출해요.

이런 원시 동작들이 있으면, 사용자가 에이전트 작업이 진행되는 동안 그것을 들여다보고, 방향을 틀고, 일시 중지하고, 재개하고, 분기(fork)시킬 수 있는 UI를 설계할 수 있어요.

백엔드 에이전트는 이렇게 만들 수 있습니다.

from langchain import create_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather, search_web],
    checkpointer=MemorySaver(),
)

주요 패턴들

메시지와 출력 렌더링

• 마크다운 메시지 (Markdown Messages) — 스트리밍되는 마크다운을 적절한 서식과 코드 하이라이팅으로 파싱하고 렌더링합니다.
• 추론 토큰 (Reasoning Tokens) — 모델의 사고 과정을 접을 수 있는 블록(collapsible blocks)으로 표시합니다.
• 생성형 UI (Generative UI) — 제어형에서 선언형, 개방형에 이르는 스펙트럼에서 에이전트가 생성한 인터페이스를 렌더링합니다.

에이전트 동작 표시

• 도구 호출 (Tool Calling) — 도구 호출을 타입 안전하고 풍부한 UI 카드로, 로딩·오류 상태와 함께 보여줍니다.
• 헤드리스 도구 (Headless Tools) — 에이전트에는 타입 있는 도구 스키마를 유지하면서, 브라우저·디바이스 API를 클라이언트에서 실행합니다.
• 인간 검토 (Human-in-the-loop) — 승인, 거부, 편집 워크플로로 인간 검토를 위해 에이전트를 일시 중지합니다.

대화 관리

• 분기 채팅 (Branching Chat) — 메시지를 편집하고, 응답을 재생성하고, 대화 분기를 탐색합니다.
• 메시지 큐 (Message Queues) — 에이전트가 순차적으로 처리하는 동안 여러 메시지를 큐에 담습니다.

고급 스트리밍

• 스트림 참여 및 재참여 (Join & Rejoin Streams) — 진행 상황을 잃지 않고 실행 중인 에이전트 스트림에서 끊겼다가 다시 연결합니다.
• 타임 트래블 (Time Travel) — 대화 히스토리의 어떤 체크포인트에서든 검사, 탐색, 재개합니다.

프론트엔드 패턴 고르기

통합 (Integrations)

스트림 API는 UI에 종속되지 않아요. 어떤 컴포넌트 라이브러리나 생성형 UI 프레임워크와도 쓸 수 있습니다. 컴포넌트 라이브러리가 표현 계층을 담당하고, LangChain SDK는 그 아래에서 에이전트 런타임 상태, 재개 가능성(resumability), 인터럽트, 체크포인트 의미론을 담당하죠.

• AI Elements — AI 채팅을 위한 조합 가능한 shadcn/ui 컴포넌트: Conversation, Message, Tool, Reasoning.
• assistant-ui — 내장 스레드 관리, 분기, 첨부 지원을 갖춘 헤드리스 React 프레임워크.
• OpenUI — openui-lang 컴포넌트 DSL을 쓰는 데이터가 풍부한 리포트·대시보드용 생성형 UI 라이브러리.

더 알아보기 (Learn more)

• 마크다운 메시지
• 도구 호출
• 구조화된 출력
• 프론트엔드 통합