Cloudflare Workers로 배포하기

Cloudflare Workers로 배포하기

SSE 재생을 위한 Vite, React, Hono, Durable Objects로 Cloudflare Workers에 LangChain 딥 에이전트를 배포해요.

이 페이지는 Cloudflare Workers에 LangChain 딥 에이전트를 배포하는 예시 앱을 자세히 설명해요: 스트리밍 채팅 UI, 하위 에이전트, 스레드 기록까지, 모두 Worker 라우트(HTTP + SSE)로 구현된 Agent Streaming Protocol을 기반으로 해요. React SPA는 Workers Assets을 통해 같은 Worker에서 서빙돼요. 별도의 백엔드 프로세스 없음: 하나의 Worker가 SPA와 프로토콜 API를 제공해요.

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

출처: 문서

본문

Cloudflare에 배포하기

1. 설치 및 빌드:

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

2. 시크릿 구성:

   npx wrangler login
   npx wrangler secret put OPENAI_API_KEY
   

3. 배포:

   pnpm run deploy
   

Wrangler는 Vite 빌드(SPA)와 Worker 스크립트를 한 번의 배포로 업로드해요. LangChain이 환경에서 OPENAI_API_KEY를 읽을 수 있도록 nodejs_compat와 nodejs_compat_populate_process_env가 활성화돼요.

wrangler.jsonc는 Workers Free 요금제에 필요한 new_sqlite_classes로 ThreadSession Durable Object를 등록해요.

필수 API 엔드포인트

앱은 /api/threads/... 아래에 Agent Streaming Protocol을 노출해요. 라우트는 Hono를 사용해 worker/index.ts에서 구현돼요.

최소 (스트리밍 채팅)

선택 (사이드바)

요청 흐름

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

  subgraph worker["Cloudflare Worker (Hono)"]
    CMD["POST /api/threads/:id/commands"]
    STR["POST /api/threads/:id/stream"]
    STA["GET|POST /api/threads/:id/state"]
    RUN["startAgentRun"]
  end

  subgraph do["Durable Object (per thread)"]
    LOG["StreamChannel event log"]
    SSE["SSE subscriptions"]
  end

  subgraph agent["worker/agent"]
    AGT["createDeepAgent + MemorySaver"]
  end

  Adapter -->|POST| CMD
  Adapter -->|POST| STR
  Adapter -->|GET / POST| STA
  CMD --> RUN
  RUN --> AGT
  RUN -->|publish events| LOG
  STR --> SSE
  LOG --> SSE
  STA --> 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,worker process
  class do trigger
  class agent output

1. 스레드 상태 부트스트랩 (GET/POST /state).
2. 제출 시 SDK는 /commands로 run.start를 보내고 run_id를 받아요.
3. Worker가 그래프 런을 시작하고 각 프로토콜 이벤트를 스레드의 Durable Object에 팬아웃(fan-out)해요.
4. SDK가 /stream(SSE)을 구독해요. DO는 버퍼링된 이벤트를 재생하고, Worker isolate 재시작에도 라이브 프레임에 계속 연결돼 있어요.
5. 하위 에이전트(task) 런은 stream.subagents로 표면화되는 네임스페이스된 이벤트를 방출해요.

Cloudflare 백엔드 설계

Worker(에이전트 + 체크포인터)와 Durable Object(SSE 이벤트 로그)의 분리는 Cloudflare의 주요 설계 선택이에요. Worker isolate는 휘발성이므로 재생 버퍼가 프로세스 메모리가 아닌 Durable Objects에 살아 있어요.

프로덕션 영속성

기본적으로 에이전트는 인메모리 MemorySaver 체크포인터(worker/agent/index.ts)를 사용해요. 이는 로컬 개발과 데모에는 작동하지만, Cloudflare(여러 isolate, 콜드 스타트)에서는 대화 상태가 배포나 isolate 간에 영구적이지 않아요.

프로덕션의 경우:

1. 내구성 있는 체크포인터를 교체하세요 (예: Hyperdrive를 통한 Postgres 또는 커스텀 DO 기반 스토어).
2. SSE 재생을 위해 스레드별 Durable Objects를 유지하세요 (또는 장수명 재연결을 위해 이벤트 로그를 DO 스토리지/KV에 영구화).

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

로컬 개발

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

http://localhost:5173을 여세요. Cloudflare Vite 플러그인이 개발 중에 Worker를 Workers 런타임에서 실행하므로 /api/* 라우트가 프로덕션처럼 동작해요.

pnpm build    # production build (client + worker)
pnpm preview  # preview the production build locally
pnpm typecheck

프로젝트 구조

• src/components/ — 채팅 UI (ChatApp, Chat, MessageThread, Subagents, ThreadHistory, …).
• src/lib/chat/threads-client.ts — 브라우저 스레드 부트스트랩 및 사이드바 헬퍼.
• worker/agent/ — researcher 및 math-whiz 하위 에이전트와 mock 도구가 있는 딥 에이전트(createDeepAgent).
• worker/server/ — 프로토콜 헬퍼: runs.ts (Worker에서 런 시작), threads.ts (체크포인터 기반 상태), serialize.ts, registry.ts.
• worker/durable-objects/thread-session.ts — 스레드별 SSE 이벤트 로그(StreamChannel + matchesSubscription).
• worker/index.ts — Hono 앱: 프로토콜 라우트 + Worker 내보내기.
• wrangler.jsonc — Worker 구성: nodejs_compat, Durable Object 바인딩, SPA 자산 라우팅(run_worker_first: ["/api/*"]).

더 알아보기

• 프레임워크 및 플랫폼 개요
• Agent Streaming Protocol
• Cloudflare Workers
• Durable Objects

더 알아보기 (Learn more)

• 프레임워크 및 플랫폼
• Cloudflare Workers