풀스택 웹 앱 배포

풀스택 웹 앱 배포 (Deploy full-stack web apps)

LangChain 에이전트를 Next.js, SvelteKit, Nuxt, Cloudflare Workers, Deno Deploy, Vite에서 풀스택 웹 앱으로 배포하는 방법을 설명해요. 스트리밍 UI와 스레드 히스토리를 함께 담는 구조입니다.

출처: 풀스택 웹 앱 배포 (Deploy full-stack web apps)

다음 페이지들은 JavaScript 프레임워크와 호스팅 플랫폼에서 LangChain 에이전트를 운영에 올리는 참조 구현을 제공합니다. deployment cookbook 저장소의 각 예제는 스트리밍 UI, 서브에이전트, 스레드 히스토리를 갖춘 풀스택 채팅 앱으로, 같은 Agent Streaming Protocol을 사용해 서로 다른 플랫폼에 배포됩니다.

에이전트 기반 제품을 출시해야 할 때 이 가이드들을 쓰면 돼요. 호스팅 환경에 맞는 스택을 복사해 자체 도구와 모델로 바꾸고, 단일 인스턴스를 넘어설 때 영속성을 업그레이드하세요.

예제

LangSmith Deployment와 짝짓기

에이전트는 LangSmith Deployment로 실행되고, 별도 웹 앱이 Agent Server API에서 스트리밍합니다.

  • LangSmith + Vite — 그래프는 LangSmith Deployment에, Vite + React UI는 Agent Server API에서 스트리밍. 보기

웹 프레임워크에 임베드

에이전트는 프레임워크의 라우트 핸들러 안에서 실행되고, 하나의 배포 가능한 앱으로 호스트 플랫폼에 배포됩니다.

  • Next.js — App Router 라우트 핸들러가 /api/threads/... 아래에서 프로토콜을 구현. Vercel에 원클릭 배포. 보기
  • SvelteKit — @langchain/svelte와 스레드별 Durable Objects(SSE 재생용)를 사용하는 Cloudflare Workers의 SvelteKit 서버 라우트. 보기
  • Nuxt — 단일 배포 가능한 Nuxt 4 앱의 Nitro 라우트 핸들러와 @langchain/vue 컴포저블. 보기
  • Cloudflare Workers — Workers Assets과 Durable Objects를 사용하는 한 Worker의 Vite + React SPA와 Hono API. 보기
  • Deno Deploy — 하나의 진입점에서 프로토콜 API를 서빙하는 Deno.serve + Hono와 Vite로 빌드한 React SPA. 보기

참고 — 각 cookbook 예제는 같은 데모 에이전트를 공유합니다. mock 도구를 가진 researcher와 math-whiz 서브에이전트에 위임하는 코디네이터 구조라서, 애플리케이션 동작을 바꾸지 않고 호스팅 선택을 비교할 수 있어요.

에이전트 배포에 무엇이 들어가나

모든 예제는 같은 형태를 따릅니다. 프레임워크와 호스팅은 바뀌지만 책임은 동일해요.

에이전트 런타임

에이전트 자체로, 보통 LangGraph 그래프 또는 deepagents 코디네이터이며, 도구, 선택적 서브에이전트, 미들웨어를 갖습니다. 체크포인터로 컴파일되어 대화 상태가 턴 사이에 유지되죠. 예제는 단순함을 위해 인메모리 MemorySaver로 시작하지만, 운영 배포에서는 Redis(@langchain/langgraph-checkpoint-redis), Postgres(@langchain/langgraph-checkpoint-postgres), SQLite(@langchain/langgraph-checkpoint-sqlite) 또는 플랫폼 전용 저장소로 바꿔요.

프로토콜 서버

HTTP 라우트 핸들러가 /api/threads/... 아래에서 Agent Streaming Protocol을 구현합니다.

최소 구성 (스트리밍 채팅)

HttpAgentServerAdapter로 단일 스레드 스트리밍 채팅을 실행하는 데 이 세 엔드포인트면 충분해요.

메서드 경로 용도
POST /api/threads/:threadId/commands 명령(run.start, …) 수락 및 런 시작
POST /api/threads/:threadId/stream 런에 대한 프로토콜 이벤트의 SSE 스트림
GET / POST /api/threads/:threadId/state 체크포인트된 스레드 상태 읽기·부트스트랩

스레드 사이드바 (모든 예제)

모든 예제는 스레드 히스토리 사이드바용 엔드포인트도 구현합니다.

메서드 경로 용도
GET /api/threads 체크포인터가 아는 스레드 목록
DELETE /api/threads/:threadId 스레드의 세션·체크포인트 삭제
POST /api/threads/:threadId/history 페이지네이션된 체크포인트 히스토리

세션·런 관리

서버 측 로직이 활성 런을 추적하고, 명령을 에이전트로 연결하며, 라이브 이벤트를 SSE로 팬아웃합니다. 레지스트리 또는 세션 스토어로 클라이언트가 진행 중인 스트림에 재연결할 수 있어요. 서버리스 또는 멀티 인스턴스 호스트에서는 이 레이어가 체크포인터와 공유되거나 함께 위치해야 합니다.

채팅 프론트엔드

@langchain/react, @langchain/vue, @langchain/svelte, @langchain/angular의 HttpAgentServerAdapter로 프로토콜에 연결된 브라우저 UI입니다. 클라이언트는 스레드 상태를 부트스트랩하고, 메시지를 제출하며, SSE 스트림을 소비하고, 토큰·도구 호출·추론·서브에이전트 활동을 렌더링해요.

이 바인딩들은 자체 컴포넌트를 제공하지 않습니다. useStream 같은 훅이 메시지·도구 호출·로딩 플래그·스레드 메타데이터 같은 일반 반응형 상태를 반환하므로, 원하는 시각 레이어에 그대로 연결하면 됩니다. 어댑터 패턴과 트레이드오프는 frontend integrations overview를 참고하세요.

더 알아보기 (Learn more)