React 애플리케이션에 LangGraph를 통합하는 방법

사전 요구사항

useStream() React hook은 LangGraph를 React 애플리케이션에 통합하는 원활한 방법을 제공합니다. 스트리밍, 상태 관리 및 분기 로직의 모든 복잡성을 처리하여 훌륭한 채팅 경험을 구축하는 데 집중할 수 있도록 합니다. 주요 기능:

Messages 스트리밍: 메시지 청크 스트림을 처리하여 완전한 메시지 형성
메시지, 인터럽트, 로딩 상태 및 오류에 대한 자동 상태 관리
대화 분기: 채팅 기록의 모든 지점에서 대체 대화 경로 생성
UI 독립적 설계: 자체 컴포넌트 및 스타일링 사용 가능

React 애플리케이션에서 useStream()을 사용하는 방법을 살펴보겠습니다. useStream()은 맞춤형 채팅 경험을 만들기 위한 견고한 기반을 제공합니다. 사전 구축된 채팅 컴포넌트 및 인터페이스를 원하신다면 CopilotKit 및 assistant-ui도 확인해보시기 바랍니다.

Installation

npm install @langchain/langgraph-sdk @langchain/core

Example

"use client";

import { useStream } from "@langchain/langgraph-sdk/react";
import type { Message } from "@langchain/langgraph-sdk";

export default function App() {
  const thread = useStream<{ messages: Message[] }>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    messagesKey: "messages",
  });

  return (
    <div>
      <div>
        {thread.messages.map((message) => (
          <div key={message.id}>{message.content as string}</div>
        ))}
      </div>

      <form
        onSubmit={(e) => {
          e.preventDefault();

          const form = e.target as HTMLFormElement;
          const message = new FormData(form).get("message") as string;

          form.reset();
          thread.submit({ messages: [{ type: "human", content: message }] });
        }}
      >
        <input type="text" name="message" />

        {thread.isLoading ? (
          <button key="stop" type="button" onClick={() => thread.stop()}>
            Stop
          </button>
        ) : (
          <button keytype="submit">Send</button>
        )}
      </form>
    </div>
  );
}

UI 커스터마이징

useStream() hook은 복잡한 상태 관리를 백그라운드에서 처리하여 UI를 구축할 수 있는 간단한 인터페이스를 제공합니다. 기본적으로 제공되는 기능은 다음과 같습니다:

Thread 상태 관리
로딩 및 오류 상태
Interrupts
메시지 처리 및 업데이트
분기 지원

다음은 이러한 기능을 효과적으로 사용하는 몇 가지 예시입니다:

로딩 상태

isLoading 속성은 스트림이 활성화되어 있는지 알려주며, 다음과 같은 작업을 수행할 수 있습니다:

로딩 인디케이터 표시
처리 중 입력 필드 비활성화
취소 버튼 표시

export default function App() {
  const { isLoading, stop } = useStream<{ messages: Message[] }>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    messagesKey: "messages",
  });

  return (
    <form>
      {isLoading && (
        <button key="stop" type="button" onClick={() => stop()}>
          Stop
        </button>
      )}
    </form>
  );
}

페이지 새로고침 후 스트림 재개

useStream() hook은 reconnectOnMount: true를 설정하여 마운트 시 진행 중인 run을 자동으로 재개할 수 있습니다. 이는 페이지 새로고침 후 스트림을 계속하는 데 유용하며, 다운타임 동안 생성된 메시지와 이벤트가 손실되지 않도록 보장합니다.

const thread = useStream<{ messages: Message[] }>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  reconnectOnMount: true,
});

기본적으로 생성된 run의 ID는 window.sessionStorage에 저장되며, reconnectOnMount에 커스텀 storage를 전달하여 교체할 수 있습니다. storage는 thread에 대한 진행 중인 run ID를 유지하는 데 사용됩니다(lg:stream:${threadId} 키 아래).

const thread = useStream<{ messages: Message[] }>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  reconnectOnMount: () => window.localStorage,
});

run callbacks를 사용하여 run 메타데이터를 유지하고 joinStream 함수를 사용하여 스트림을 재개함으로써 수동으로 재개 프로세스를 관리할 수도 있습니다. run을 생성할 때 streamResumable: true를 전달해야 합니다. 그렇지 않으면 일부 이벤트가 손실될 수 있습니다.

import type { Message } from "@langchain/langgraph-sdk";
import { useStream } from "@langchain/langgraph-sdk/react";
import { useCallback, useState, useEffect, useRef } from "react";

export default function App() {
  const [threadId, onThreadId] = useSearchParam("threadId");

  const thread = useStream<{ messages: Message[] }>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",

    threadId,
    onThreadId,

    onCreated: (run) => {
      window.sessionStorage.setItem(`resume:${run.thread_id}`, run.run_id);
    },
    onFinish: (_, run) => {
      window.sessionStorage.removeItem(`resume:${run?.thread_id}`);
    },
  });

  // Ensure that we only join the stream once per thread.
  const joinedThreadId = useRef<string | null>(null);
  useEffect(() => {
    if (!threadId) return;

    const resume = window.sessionStorage.getItem(`resume:${threadId}`);
    if (resume && joinedThreadId.current !== threadId) {
      thread.joinStream(resume);
      joinedThreadId.current = threadId;
    }
  }, [threadId]);

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const form = e.target as HTMLFormElement;
        const message = new FormData(form).get("message") as string;
        thread.submit(
          { messages: [{ type: "human", content: message }] },
          { streamResumable: true }
        );
      }}
    >
      <div>
        {thread.messages.map((message) => (
          <div key={message.id}>{message.content as string}</div>
        ))}
      </div>
      <input type="text" name="message" />
      <button type="submit">Send</button>
    </form>
  );
}

// Utility method to retrieve and persist data in URL as search param
function useSearchParam(key: string) {
  const [value, setValue] = useState<string | null>(() => {
    const params = new URLSearchParams(window.location.search);
    return params.get(key) ?? null;
  });

  const update = useCallback(
    (value: string | null) => {
      setValue(value);

      const url = new URL(window.location.href);
      if (value == null) {
        url.searchParams.delete(key);
      } else {
        url.searchParams.set(key, value);
      }

      window.history.pushState({}, "", url.toString());
    },
    [key]
  );

  return [value, update] as const;
}

Thread 관리

내장된 thread 관리로 대화를 추적할 수 있습니다. 현재 thread ID에 액세스하고 새 thread가 생성될 때 알림을 받을 수 있습니다:

const [threadId, setThreadId] = useState<string | null>(null);

const thread = useStream<{ messages: Message[] }>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",

  threadId: threadId,
  onThreadId: setThreadId,
});

사용자가 페이지 새로고침 후 대화를 재개할 수 있도록 URL의 query parameter에 threadId를 저장하는 것을 권장합니다.

메시지 처리

useStream() hook은 서버로부터 받은 메시지 청크를 추적하고 이를 연결하여 완전한 메시지를 형성합니다. 완성된 메시지 청크는 messages 속성을 통해 검색할 수 있습니다. 기본적으로 messagesKey는 messages로 설정되어 있으며, 새 메시지 청크를 values["messages"]에 추가합니다. 메시지를 다른 키에 저장하는 경우 messagesKey의 값을 변경할 수 있습니다.

import type { Message } from "@langchain/langgraph-sdk";
import { useStream } from "@langchain/langgraph-sdk/react";

export default function HomePage() {
  const thread = useStream<{ messages: Message[] }>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    messagesKey: "messages",
  });

  return (
    <div>
      {thread.messages.map((message) => (
        <div key={message.id}>{message.content as string}</div>
      ))}
    </div>
  );
}

내부적으로 useStream() hook은 streamMode: "messages-tuple"을 사용하여 그래프 노드 내의 모든 LangChain chat model 호출로부터 메시지 스트림(즉, 개별 LLM 토큰)을 수신합니다. 메시지 스트리밍에 대한 자세한 내용은 streaming 가이드를 참조하세요.

Interrupts

useStream() hook은 interrupt 속성을 노출하며, 이는 thread의 마지막 interrupt로 채워집니다. interrupt를 사용하여 다음을 수행할 수 있습니다:

노드를 실행하기 전에 확인 UI 렌더링
사용자 입력 대기, 에이전트가 사용자에게 명확한 질문을 할 수 있도록 허용

interrupt에 대한 자세한 내용은 How to handle interrupts 가이드를 참조하세요.

const thread = useStream<{ messages: Message[] }, { InterruptType: string }>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  messagesKey: "messages",
});

if (thread.interrupt) {
  return (
    <div>
      Interrupted! {thread.interrupt.value}
      <button
        type="button"
        onClick={() => {
          // `resume` can be any value that the agent accepts
          thread.submit(undefined, { command: { resume: true } });
        }}
      >
        Resume
      </button>
    </div>
  );
}

분기

각 메시지에 대해 getMessagesMetadata()를 사용하여 메시지가 처음 표시된 첫 번째 checkpoint를 가져올 수 있습니다. 그런 다음 첫 번째 표시된 checkpoint 이전의 checkpoint에서 새 run을 생성하여 thread에 새 분기를 만들 수 있습니다. 분기는 다음과 같은 방법으로 생성할 수 있습니다:

이전 사용자 메시지 편집.
이전 assistant 메시지의 재생성 요청.

"use client";

import type { Message } from "@langchain/langgraph-sdk";
import { useStream } from "@langchain/langgraph-sdk/react";
import { useState } from "react";

function BranchSwitcher({
  branch,
  branchOptions,
  onSelect,
}: {
  branch: string | undefined;
  branchOptions: string[] | undefined;
  onSelect: (branch: string) => void;
}) {
  if (!branchOptions || !branch) return null;
  const index = branchOptions.indexOf(branch);

  return (
    <div className="flex items-center gap-2">
      <button
        type="button"
        onClick={() => {
          const prevBranch = branchOptions[index - 1];
          if (!prevBranch) return;
          onSelect(prevBranch);
        }}
      >
        Prev
      </button>
      <span>
        {index + 1} / {branchOptions.length}
      </span>
      <button
        type="button"
        onClick={() => {
          const nextBranch = branchOptions[index + 1];
          if (!nextBranch) return;
          onSelect(nextBranch);
        }}
      >
        Next
      </button>
    </div>
  );
}

function EditMessage({
  message,
  onEdit,
}: {
  message: Message;
  onEdit: (message: Message) => void;
}) {
  const [editing, setEditing] = useState(false);

  if (!editing) {
    return (
      <button type="button" onClick={() => setEditing(true)}>
        Edit
      </button>
    );
  }

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const form = e.target as HTMLFormElement;
        const content = new FormData(form).get("content") as string;

        form.reset();
        onEdit({ type: "human", content });
        setEditing(false);
      }}
    >
      <input name="content" defaultValue={message.content as string} />
      <button type="submit">Save</button>
    </form>
  );
}

export default function App() {
  const thread = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    messagesKey: "messages",
  });

  return (
    <div>
      <div>
        {thread.messages.map((message) => {
          const meta = thread.getMessagesMetadata(message);
          const parentCheckpoint = meta?.firstSeenState?.parent_checkpoint;

          return (
            <div key={message.id}>
              <div>{message.content as string}</div>

              {message.type === "human" && (
                <EditMessage
                  message={message}
                  onEdit={(message) =>
                    thread.submit(
                      { messages: [message] },
                      { checkpoint: parentCheckpoint }
                    )
                  }
                />
              )}

              {message.type === "ai" && (
                <button
                  type="button"
                  onClick={() =>
                    thread.submit(undefined, { checkpoint: parentCheckpoint })
                  }
                >
                  <span>Regenerate</span>
                </button>
              )}

              <BranchSwitcher
                branch={meta?.branch}
                branchOptions={meta?.branchOptions}
                onSelect={(branch) => thread.setBranch(branch)}
              />
            </div>
          );
        })}
      </div>

      <form
        onSubmit={(e) => {
          e.preventDefault();

          const form = e.target as HTMLFormElement;
          const message = new FormData(form).get("message") as string;

          form.reset();
          thread.submit({ messages: [message] });
        }}
      >
        <input type="text" name="message" />

        {thread.isLoading ? (
          <button key="stop" type="button" onClick={() => thread.stop()}>
            Stop
          </button>
        ) : (
          <button key="submit" type="submit">
            Send
          </button>
        )}
      </form>
    </div>
  );
}

고급 사용 사례의 경우 experimental_branchTree 속성을 사용하여 thread의 트리 표현을 가져올 수 있으며, 이는 메시지 기반이 아닌 그래프에 대한 분기 컨트롤을 렌더링하는 데 사용할 수 있습니다.

Optimistic Updates

에이전트에 네트워크 요청을 수행하기 전에 클라이언트 상태를 낙관적으로 업데이트하여 에이전트가 요청을 보기 전에 사용자 메시지를 즉시 표시하는 등 사용자에게 즉각적인 피드백을 제공할 수 있습니다.

const stream = useStream({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  messagesKey: "messages",
});

const handleSubmit = (text: string) => {
  const newMessage = { type: "human" as const, content: text };

  stream.submit(
    { messages: [newMessage] },
    {
      optimisticValues(prev) {
        const prevMessages = prev.messages ?? [];
        const newMessages = [...prevMessages, newMessage];
        return { ...prev, messages: newMessages };
      },
    }
  );
};

캐시된 Thread 표시

initialValues 옵션을 사용하여 서버에서 기록을 로드하는 동안 캐시된 thread 데이터를 즉시 표시할 수 있습니다. 이는 기존 thread로 이동할 때 캐시된 데이터를 즉시 표시하여 사용자 경험을 개선합니다.

import { useStream } from "@langchain/langgraph-sdk/react";

const CachedThreadExample = ({ threadId, cachedThreadData }) => {
  const stream = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    threadId,
    // Show cached data immediately while history loads
    initialValues: cachedThreadData?.values,
    messagesKey: "messages",
  });

  return (
    <div>
      {stream.messages.map((message) => (
        <div key={message.id}>{message.content as string}</div>
      ))}
    </div>
  );
};

Optimistic Thread 생성

submit 함수의 threadId 옵션을 사용하여 thread가 실제로 생성되기 전에 thread ID를 알아야 하는 optimistic UI 패턴을 활성화할 수 있습니다.

import { useState } from "react";
import { useStream } from "@langchain/langgraph-sdk/react";

const OptimisticThreadExample = () => {
  const [threadId, setThreadId] = useState<string | null>(null);
  const [optimisticThreadId] = useState(() => crypto.randomUUID());

  const stream = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    threadId,
    onThreadId: setThreadId, // (3) Updated after thread has been created.
    messagesKey: "messages",
  });

  const handleSubmit = (text: string) => {
    // (1) Perform a soft navigation to /threads/${optimisticThreadId}
    // without waiting for thread creation.
    window.history.pushState({}, "", `/threads/${optimisticThreadId}`);

    // (2) Submit message to create thread with the predetermined ID.
    stream.submit(
      { messages: [{ type: "human", content: text }] },
      { threadId: optimisticThreadId }
    );
  };

  return (
    <div>
      <p>Thread ID: {threadId ?? optimisticThreadId}</p>
      {/* Rest of component */}
    </div>
  );
};

TypeScript

useStream() hook은 TypeScript로 작성된 앱에 친화적이며 상태에 대한 타입을 지정하여 더 나은 타입 안전성과 IDE 지원을 받을 수 있습니다.

// Define your types
type State = {
  messages: Message[];
  context?: Record<string, unknown>;
};

// Use them with the hook
const thread = useStream<State>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  messagesKey: "messages",
});

다음과 같은 다양한 시나리오에 대한 타입을 선택적으로 지정할 수도 있습니다:

ConfigurableType: config.configurable 속성의 타입 (기본값: Record<string, unknown>)
InterruptType: interrupt 값의 타입 - 즉, interrupt(...) 함수의 내용 (기본값: unknown)
CustomEventType: 커스텀 이벤트의 타입 (기본값: unknown)
UpdateType: submit 함수의 타입 (기본값: Partial<State>)

const thread = useStream<
  State,
  {
    UpdateType: {
      messages: Message[] | Message;
      context?: Record<string, unknown>;
    };
    InterruptType: string;
    CustomEventType: {
      type: "progress" | "debug";
      payload: unknown;
    };
    ConfigurableType: {
      model: string;
    };
  }
>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  messagesKey: "messages",
});

LangGraph.js를 사용하는 경우 그래프의 annotation 타입을 재사용할 수도 있습니다. 그러나 전체 LangGraph.js 런타임을 가져오지 않도록 annotation schema의 타입만 가져와야 합니다(즉, import type { ... } 지시문을 통해).

import {
  Annotation,
  MessagesAnnotation,
  type StateType,
  type UpdateType,
} from "@langchain/langgraph/web";

const AgentState = Annotation.Root({
  ...MessagesAnnotation.spec,
  context: Annotation<string>(),
});

const thread = useStream<
  StateType<typeof AgentState.spec>,
  { UpdateType: UpdateType<typeof AgentState.spec> }
>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  messagesKey: "messages",
});

Event 처리

useStream() hook은 다양한 이벤트에 응답하는 데 도움이 되는 여러 callback 옵션을 제공합니다:

onError: 오류가 발생할 때 호출됩니다.
onFinish: 스트림이 완료될 때 호출됩니다.
onUpdateEvent: update 이벤트가 수신될 때 호출됩니다.
onCustomEvent: 커스텀 이벤트가 수신될 때 호출됩니다. 커스텀 이벤트를 스트리밍하는 방법은 streaming 가이드를 참조하세요.
onMetadataEvent: Run ID와 Thread ID를 포함하는 metadata 이벤트가 수신될 때 호출됩니다.

더 알아보기

JS/TS SDK Reference

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.

Deploy to Cloud

Configure for deployment

App development

Studio

Auth & access control

Server customization

Reference

React 애플리케이션에 LangGraph를 통합하는 방법

Installation

Example

UI 커스터마이징

로딩 상태

페이지 새로고침 후 스트림 재개

Thread 관리

메시지 처리

Interrupts

분기

Optimistic Updates

캐시된 Thread 표시

Optimistic Thread 생성

TypeScript

Event 처리

더 알아보기

Deploy to Cloud

Configure for deployment

App development

Studio

Auth & access control

Server customization

Reference

​Installation

​Example

​UI 커스터마이징

​로딩 상태

​페이지 새로고침 후 스트림 재개

​Thread 관리

​메시지 처리

​Interrupts

​분기

​Optimistic Updates

​캐시된 Thread 표시

​Optimistic Thread 생성

​TypeScript

​Event 처리

​더 알아보기

Installation

Example

UI 커스터마이징

로딩 상태

페이지 새로고침 후 스트림 재개

Thread 관리

메시지 처리

Interrupts

분기

Optimistic Updates

캐시된 Thread 표시

Optimistic Thread 생성

TypeScript

Event 처리

더 알아보기