SvelteKit으로 배포하기

스트리밍 채팅과 스레드 기록을 갖춘 SvelteKit 프로젝트의 Cloudflare Workers에 LangChain 딥 에이전트를 배포해요.

이 페이지는 @sveltejs/adapter-cloudflare를 사용해 Cloudflare Workers용으로 빌드된 SvelteKit 프로젝트 안에 LangChain 딥 에이전트를 배포하는 예시 앱을 자세히 설명해요: 스트리밍 채팅 UI, 하위 에이전트 상세 보기, 스레드 기록, 그리고 /api/threads/... 아래에 노출된 Agent Streaming Protocol. 별도의 백엔드 프로세스가 필요하지 않아요.

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

출처: 문서

본문

Cloudflare에 배포하기

설치 및 빌드:

cd js-sveltekit
cp .env.example .env   # set OPENAI_API_KEY for local dev
pnpm install
pnpm build

시크릿 구성:

npx wrangler login
npx wrangler secret put OPENAI_API_KEY

배포:
```
pnpm run deploy
```

svelte.config.js는 adapter-cloudflare()를 사용해요. wrangler.jsonc는 Wrangler를 .svelte-kit/cloudflare/_worker.js로 지정하고 .svelte-kit/cloudflare에서 자산을 서빙하며, SvelteKit Cloudflare 어댑터 문서와 일치해요. 빌드 스크립트는 Durable Object 클래스가 Worker 모듈에서 내보내져야 하므로, 생성된 Worker 엔트리에 ThreadSession Durable Object 내보내기를 추가해요.

nodejs_compat와 nodejs_compat_populate_process_env가 활성화되어 있는데, LangChain 런타임과 추적 통합이 Node 호환 API와 환경 접근을 기대하기 때문이에요.

선택적으로 .env.example의 변수를 Worker 시크릿이나 변수로 추가해 LangSmith 추적을 활성화하세요.

필수 API 엔드포인트

앱은 /api/threads/... 아래에 Agent Streaming Protocol을 노출해요. SvelteKit 라우트 핸들러는 src/routes/api/threads/에 있어요.

최소 (스트리밍 채팅)

메서드	경로	목적
`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`	페이지네이션된 체크포인트 기록

Cloudflare 백엔드 설계

관심사	구현
프론트엔드	SvelteKit 클라이언트 라우트 및 컴포넌트
API 계층	`src/routes/api/threads/`의 SvelteKit 서버 엔드포인트
런타임	Workers V8 + `nodejs_compat`
SSE 재생	스레드별 Durable Object(`ThreadSession`)
에이전트 런	Worker isolate; 프로토콜 이벤트는 DO에 POST됨
정적 자산	`adapter-cloudflare`을 통한 Workers Static Assets
시크릿	`wrangler secret` / 로컬 `.env`

프로덕션 영속성

기본적으로 에이전트는 인메모리 MemorySaver 체크포인터(src/lib/server/agent/index.ts)를 사용해요. 스레드별 SSE 재생/세션 로그는 Durable Object에 살아 있으므로 스트리밍 클라이언트가 프로세스-로컬 맵 대신 하나의 조정 지점에 재연결해요.

체크포인터는 여전히 isolate-로컬 데모 상태예요. Cloudflare isolate는 휘발성이고 수평 확장될 수 있으므로, 체크포인트된 대화 상태는 배포, 콜드 스타트 또는 isolate 간에 영구적이지 않아요.

프로덕션의 경우:

내구성 있는 체크포인터를 교체하세요 (예: Hyperdrive를 통한 Postgres 또는 커스텀 Durable Object 기반 스토어).
Durable Object가 메모리에서 축출된 후에도 클라이언트가 재연결해야 한다면 장수명 재생/기록을 영구화하세요.

로컬 개발

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

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

pnpm build      # production build for Cloudflare
pnpm preview    # preview the production build locally
pnpm typecheck  # svelte-check over the project

빌드 후 Cloudflare 스타일 로컬 테스트를 위해 다음을 실행하세요:

npx wrangler dev .svelte-kit/cloudflare/_worker.js

프로젝트 구조

src/lib/server/agent/ — researcher 및 math-whiz 하위 에이전트와 mock 도구가 있는 딥 에이전트(createDeepAgent).
src/lib/server/durable-objects/thread-session.ts — SSE 재생을 위한 스레드별 Durable Object 이벤트 로그.
src/lib/server/protocol/ — Agent Streaming Protocol 헬퍼: 체크포인터 기반 상태/기록, 런 게시, 직렬화, 레지스트리.
src/routes/api/threads/ — 프로토콜 엔드포인트를 위한 SvelteKit 라우트 핸들러.
src/lib/chat/threads-client.ts — 브라우저 스레드 부트스트랩 및 사이드바 헬퍼.
src/lib/components/ — @langchain/svelte를 사용하는 Svelte 채팅 UI.
svelte.config.js — @sveltejs/adapter-cloudflare로 구성된 SvelteKit.
scripts/export-durable-objects.mjs — 생성된 Worker 엔트리에서 Durable Object 클래스를 다시 내보내는 포스트빌드 패치.
wrangler.jsonc — Cloudflare Workers Static Assets 및 Durable Object 구성.

SvelteKit으로 배포하기