Next.js로 배포하기

스트리밍 채팅, 하위 에이전트, 스레드 기록을 갖춘 Next.js App Router 프로젝트에 LangChain 딥 에이전트를 배포해요.

이 페이지는 Next.js App Router 프로젝트 안에 완전히 통합된 LangChain 딥 에이전트를 배포하는 예시 앱을 자세히 설명해요: 스트리밍 채팅 UI, 하위 에이전트, 스레드 기록까지, 모두 Next.js Route Handlers(HTTP + SSE)로 구현된 Agent Streaming Protocol을 기반으로 해요. 별도의 백엔드 프로세스 없음.

소스: 배포 쿡북의 js-next.

출처: 문서

본문

Vercel에 배포하기

저장소 가져오기: 아래의 Deploy with Vercel을 클릭하거나, langchain-ai/deployment-cookbook을 수동으로 가져오세요.
프로젝트 구성: Root Directory를 js-next로 설정하고 프로젝트 설정에 OPENAI_API_KEY를 추가하세요.
배포: 프로젝트를 배포하세요. Route Handlers가 이미 runtime = "nodejs"로 설정돼 있고 SSE 라우트는 dynamic = "force-dynamic"으로 설정돼 있는데, 이것이 Vercel이 스트리밍에 필요한 설정이에요.

선택적으로 .env.example의 변수를 추가해 LangSmith 추적을 활성화할 수 있어요.

필수 API 엔드포인트

앱은 /api/threads/... 아래에 Agent Streaming Protocol을 노출해요. Route Handlers는 app/api/threads/에 있어요.

최소 (스트리밍 채팅)

@langchain/react의 HttpAgentServerAdapter로 싱글 스레드 스트리밍 채팅을 실행하려면 이 세 엔드포인트로 충분해요:

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

클라이언트는 GET /state로 스레드를 부트스트랩하고(404면 POST /state) 첫 메시지가 전송되기 전에 하이드레이션이 404가 되지 않도록 해요.

선택 (스레드 사이드바)

이 예시는 스레드 기록 사이드바용 엔드포인트도 구현해요. UI에 멀티 스레드 관리가 필요 없으면 생략해도 돼요:

메서드	경로	목적
`GET`	`/api/threads`	체크포인터가 아는 스레드 나열
`DELETE`	`/api/threads/:threadId`	스레드의 세션과 체크포인트 삭제
`POST`	`/api/threads/:threadId/history`	페이지네이션된 체크포인트 기록 (Agent Protocol)

요청 흐름

%%{init: {"themeVariables": {"lineColor": "#40668D", "primaryColor": "#E5F4FF", "primaryTextColor": "#030710", "primaryBorderColor": "#006DDD"}}}%%
flowchart TB
  subgraph browser["Browser"]
    SP["StreamProvider"]
    Adapter["HttpAgentServerAdapter"]
    SP --- Adapter
  end

  subgraph routes["Next.js Route Handlers (Node runtime)"]
    CMD["POST /api/threads/:id/commands"]
    STR["POST /api/threads/:id/stream (SSE)"]
    STA["GET|POST /api/threads/:id/state"]
  end

  subgraph server["lib/server"]
    SRV["session · threads · registry"]
  end

  subgraph agent["lib/agent"]
    AGT["createDeepAgent + checkpointer"]
  end

  Adapter -->|POST| CMD
  Adapter -->|POST| STR
  Adapter -->|GET / POST| STA
  CMD --> SRV
  STR --> SRV
  STA --> SRV
  SRV --> AGT

  classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
  classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
  classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
  class browser,routes process
  class server trigger
  class agent output

스레드 상태 부트스트랩 (GET/POST /state).
제출 시 SDK는 /commands로 run.start를 보내고 run_id를 받아요.
SDK는 재생 + 라이브 프로토콜 이벤트를 위해 /stream(SSE)을 구독해요.
하위 에이전트(task) 런은 stream.subagents로 표면화되는 네임스페이스된 이벤트를 방출해요.

프로덕션 영속성

기본적으로 에이전트는 인메모리 MemorySaver 체크포인터(lib/agent/index.ts)와 프로세스 로컬 세션 맵(lib/server/registry.ts)을 사용해요. 이는 로컬 개발과 단일 인스턴스 서버에는 작동하지만, Vercel(서버리스, 여러 레플리카)에서는 콜드 스타트나 인스턴스 간에 대화 상태가 영구적이지 않아요.

프로덕션의 경우 내구성 있는 체크포인터를 교체하세요:

패키지	백엔드
`@langchain/langgraph-checkpoint-redis`	Redis (`RedisSaver`)
`@langchain/langgraph-checkpoint-postgres`	Postgres (`PostgresSaver`)
`@langchain/langgraph-checkpoint-sqlite`	SQLite (`SqliteSaver`)

lib/agent/index.ts의 MemorySaver를 교체하고 새 체크포인터를 createDeepAgent에 전달하세요. Route Handlers와 lib/server/threads.ts 헬퍼는 그대로 유지돼요.

Vercel에서 Redis

Vercel의 일반적인 선택은 Marketplace를 통한 Redis예요 (예: Upstash Redis). Vercel 프로젝트에 통합을 설치하면 자격 증명이 환경 변수로 자동 주입돼요.

그런 다음 @langchain/langgraph-checkpoint-redis를 연결하세요:

import { RedisSaver } from "@langchain/langgraph-checkpoint-redis";

const checkpointer = await RedisSaver.fromUrl(process.env.REDIS_URL!);

Redis 프로바이더가 노출하는 연결 문자열을 사용하세요 (Upstash는 REST와 Redis 프로토콜 URL을 모두 제공하며, 체크포인터는 Redis URL이 필요해요).

또한 서버리스 호출 간에 SSE 재연결이 작동하도록 lib/server/registry.ts에 공유 세션/재생 스토어를 원할 거예요. 체크포인터 교체가 내구성 있는 스레드 기록의 핵심 단계이며, 세션 스토어는 라이브 런 재생을 위한 별도의 관심사예요.

자세한 내용은 체크포인터 라이브러리와 메모리/영속성 추가를 참고하세요.

로컬 개발

cp .env.example .env.local   # set OPENAI_API_KEY
pnpm install
pnpm dev

http://localhost:3000을 여세요.

pnpm build   # production build
pnpm start   # serve the production build
pnpm lint    # eslint

프로젝트 구조

lib/agent/: researcher 및 math-whiz 하위 에이전트와 mock 도구가 있는 딥 에이전트(createDeepAgent). server-only로 표시.
lib/server/: 프로토콜 서버 로직: session.ts (SSE 런), threads.ts (체크포인터 기반 상태), serialize.ts, registry.ts.
app/api/threads/: 위 프로토콜 엔드포인트용 Route Handlers.
lib/chat/threads-client.ts: 브라우저 스레드 부트스트랩 및 사이드바 헬퍼.
components/: 채팅 UI (ChatApp, Chat, MessageList, Subagents, ThreadHistory, …).

더 알아보기

프레임워크 및 플랫폼 개요
Agent Streaming Protocol
react-custom-backend — 커스텀 프로토콜 서버를 위한 원본 Vite + Hono 참조
Next.js Route Handlers

Next.js로 배포하기