langchain-ai/agent-chat-ui

🦜💬 Web app for interacting with any LangGraph agent (PY & TS) via a chat interface.

Agent Chat UI – 무엇인가요

Agent Chat UI 는 어떤 LangGraph 서버(예: LangChain 스타일의 에이전트 그래프를 실행하는 백엔드)와 대화할 수 있는 작은 Next.js 웹 앱입니다. UI를 LangGraph 엔드포인트에 연결하고, 사용하고자 하는 어시스턴트/그래프의 ID를 지정하면, 사용자의 입력이 서버로 전송되고 LLM이 생성한 응답이 스트리밍으로 반환됩니다.

이 프로젝트는 몇 가지 편의 기능을 갖춘 LangGraph 에이전트용 프론트엔드 클라이언트입니다:

빠른 시작 폼(또는 환경 변수 오버라이드)를 통해 서버 URL, 어시스턴트 ID, 선택적 LangSmith API 키를 구성할 수 있습니다.
특수 태그(langsmith:nostream, langsmith:do-not-render)를 사용하여 스트리밍 메시지를 숨기거나 영구적으로 억제할 수 있습니다.
아티팩트(생성된 파일, 시각화 등)를 표시하는 사이드 패널을 제공하는 커스텀 React 훅을 포함합니다.
API-패스스루 프록시(서버 측에서 LangSmith 키를 주입) 및 더 높은 보안을 위한 선택적 커스텀 인증을 포함한 프로덕션 배포 가이드라인도 제공합니다.

빠른 시작 (로컬 개발)

# 새 프로젝트 생성 (또는 리포지토리 복제)
npx create-agent-chat-app
# 또는
git clone https://github.com/langchain-ai/agent-chat-ui.git && cd agent-chat-ui

# 종속성 설치 (pnpm 추천)
pnpm install

# 개발 서버 실행
pnpm dev   # → http://localhost:3000

앱이 로드되면 짧은 폼이 표시됩니다. 다음을 입력하세요:

배포 URL – 사용 중인 LangGraph 서버의 HTTP 주소.
어시스턴트/그래프 ID – 대화하고자 하는 에이전트의 이름 또는 UUID.
LangSmith API 키 – 서버가 LangSmith 키를 필요로 하는 경우에만 필요합니다 (예: 내장된 Agent Builder 배포 사용 시).
Agent Builder로 생성됨 – 서버가 LangSmith의 Agent Builder로 생성된 경우 활성화합니다. 자동으로 올바른 인증 스키마를 선택합니다.

계속을 클릭하면 채팅 뷰로 이동합니다.

설정 폼을 건너뛰고 실행하기

세 가지 환경 변수를 설정하거나 (또는 .env.example 기반의 .env 파일에 추가) 인터랙티브 폼을 건너뛸 수 있습니다:

NEXT_PUBLIC_API_URL=http://localhost:2024   # LangGraph 엔드포인트
NEXT_PUBLIC_ASSISTANT_ID=agent            # 그래프/어시스턴트 ID
NEXT_PUBLIC_AUTH_SCHEME=                  # 예: Agent Builder용 "langsmith-api-key"

이 변수들이 존재하면 UI는 즉시 연결됩니다.

UI가 표시하는 내용 제어하기

스트리밍 출력 숨기기

채팅 모델 구성에 태그 langsmith:nostream 를 추가하세요. UI는 on_chat_model_stream 이벤트를 감시하며, 이 태그는 해당 이벤트를 억제하여 사용자는 최종 메시지만 보게 됩니다.

# Python 예제
model = ChatAnthropic().with_config({"tags": ["langsmith:nostream"]})

// TypeScript 예제
const model = new ChatAnthropic().withConfig({ tags: ["langsmith:nostream"] })

메시지 완전히 숨기기

메시지 id 앞에 do-not-render- 를 붙이고, 태그 langsmith:do-not-render 도 추가하세요. UI는 ID가 이 접두사로 시작하는 메시지를 필터링하므로, 콘텐츠는 채팅 패널에 전혀 나타나지 않습니다.

result = model.invoke([messages])
result.id = f"do-not-render-{result.id}"
return {"messages": [result]}

const result = await model.invoke([messages])
result.id = `do-not-render-${result.id}`
return { messages: [result] }

아티팩트 렌더링

LangGraph 그래프는 thread.meta.artifact 에 추가 데이터를 반환할 수 있습니다. UI는 useArtifact 훅을 제공하여 다음을 제공합니다:

콜랩시블 사이드 패널에 콘텐츠를 렌더링하는 React 컴포넌트 (Artifact).
패널 가시성을 제어하는 상태 (open, setOpen).
저장한 모든 내용을 포함하는 원시 context 객체.

최소한의 사용 예는 다음과 같습니다:

import { useArtifact } from "../utils/use-artifact"

export function Writer({title, content, description}) {
  const [Artifact, {open, setOpen}] = useArtifact()
  return (
    <>
      <div => setOpen(!open)} className="cursor-pointer rounded-lg border p-4">
        <p className="font-medium">{title}</p>
        <p className="text-sm text-gray-500">{description}</p>
      </div>
      <Artifact title={title}>
        <p className="whitespace-pre-wrap p-4">{content}</p>
      </Artifact>
    </>
  )
}

이를 통해 생성된 파일, 차트, 또는 기타 사용자 정의 UI를 채팅과 함께 표시할 수 있습니다.

프로덕션 배포

공개된 LangGraph 엔드포인트에 UI를 직접 연결하면 모든 사용자의 LangSmith 키가 노출될 수 있습니다. 이 리포지토리는 이를 방지하기 위한 두 가지 추천 방법을 제공합니다.

1. API 패스스루 (가장 빠름)

langgraph-nextjs-api-passthrough 패키지 설치 (이미 번들됨).
Next.js 앱 배포 (예: Vercel). 내장된 /api 경로가 LangGraph 서버로의 요청을 프록시하며, 서버 측에서 LangSmith 키를 주입합니다.

배포 플랫폼에 다음 환경 변수 설정:

NEXT_PUBLIC_ASSISTANT_ID=agent
LANGGRAPH_API_URL=https://my-agent.default.us.langgraph.app   # 사용 중인 LangGraph 배포
NEXT_PUBLIC_API_URL=https://my-website.com/api                # 이 UI + /api의 URL
LANGSMITH_API_KEY=lsv2_…                                      # 비밀, NEXT_PUBLIC_로 시작하지 않음

중요: 패스스루는 호출자를 인증하지 않습니다. 자체 게이트웨이(예: Vercel 엣지 미들웨어)를 추가하거나 아래의 고급 커스텀 인증 옵션을 사용하세요.

2. 커스텀 인증 (더 안전함)

LangGraph의 커스텀 인증 문서(파이썬 또는 타입스크립트)를 따라 LangGraph 서버가 Bearer 토큰 또는 기타 인증 방식을 요구하도록 설정합니다.

UI에서 useTypedStream (또는 기본 useStream)을 수정하여 요청 헤더에 토큰을 첨부합니다:

const streamValue = useTypedStream({
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID,
  defaultHeaders: { Authentication: `Bearer ${myToken}` },
  // …기타 옵션
})

이로써 클라이언트는 LangSmith 키를 노출하지 않고 LangGraph 서버에 직접 연결할 수 있습니다.

누구에게 적합한가요?

데모나 내부 테스트용으로 즉시 사용 가능한 채팅 UI가 필요한 LangGraph 에이전트 개발자.
커스텀 UI를 처음부터 구축하지 않고도 LLM 기반 어시스턴트를 최종 사용자에게 공개하고 싶은 제품 팀.
스트리밍 제어나 아티팩트 렌더링을 실험하면서 프론트엔드 코드를 최소화하고 싶은 연구자.

TL;DR

git clone 또는 npx create-agent-chat-app → pnpm dev.
UI를 LangGraph 서버(URL + 어시스턴트 ID)에 연결. 선택적으로 LangSmith 키 제공.
태그(langsmith:nostream, langsmith:do-not-render)를 사용해 메시지 숨기기.
useArtifact 훅을 통해 추가 데이터 렌더링.
프로덕션에서는 내장된 API 패스스루(비밀 LangSmith 키 포함) 또는 LangGraph 측에서 커스텀 인증 설정.