使用 Cloudflare Workers 部署

使用 Vite、React、Hono 和 Durable Objects 在 Cloudflare Workers 上部署 LangChain deep agent，实现 SSE 重放。

以下页面详细介绍一个示例应用：它在 Cloudflare Workers 上部署 LangChain deep agent，包含流式聊天 UI、子 agent 和线程历史，全部由以 Worker 路由（HTTP + SSE）形式实现的 Agent Streaming Protocol 提供支持。React SPA 通过 Workers Assets 从同一个 Worker 提供。无需单独的后端进程：一个 Worker 同时提供 SPA 和协议 API。

来源：部署 cookbook 中的 js-cloudflare。

部署到 Cloudflare

Install and build

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

Configure secrets

npx wrangler login
npx wrangler secret put OPENAI_API_KEY

Deploy

pnpm run deploy

Wrangler 在一次部署中同时上传 Vite 构建产物（SPA）和 Worker 脚本。启用了 nodejs_compat 和 nodejs_compat_populate_process_env，以便 LangChain 从环境中读取 OPENAI_API_KEY。

wrangler.jsonc 使用 new_sqlite_classes 注册 ThreadSession Durable Object，这是在 Workers Free 套餐上所必需的。

必需的 API 端点

该应用在 /api/threads/... 下暴露 Agent Streaming Protocol。路由在 worker/index.ts 中使用 Hono 实现。

最小集（流式聊天）

方法	路径	用途
POST	/api/threads/:threadId/commands	接受协议命令（run.start 等）并启动 agent run
POST	/api/threads/:threadId/stream	某次 run 的协议事件 SSE 流
GET / POST	/api/threads/:threadId/state	读取并引导已 checkpoint 的线程状态

可选（侧栏）

方法	路径	用途
GET	/api/threads	列出 checkpointer 已知的线程
DELETE	/api/threads/:threadId	删除线程的会话和 checkpoint
POST	/api/threads/:threadId/history	分页的 checkpoint 历史

请求流程

%%{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 中。
4. SDK 订阅 /stream（SSE）。DO 会重放缓冲的事件，并保持连接以接收实时帧，即使 Worker isolate 重启也不中断。
5. 子 agent（task）运行会发出带命名空间的事件，这些事件以 stream.subagents 的形式呈现。

Cloudflare 后端设计

关注点	实现
前端	Vite + React SPA（src/）
API 层	worker/index.ts 中的 Hono 路由
运行时	Workers V8 + nodejs_compat
SSE 重放	每线程 Durable Object（ThreadSession）
Agent 运行	Worker isolate；协议事件 POST 到 DO
静态资源	Workers Assets（wrangler.jsonc → assets）
密钥	wrangler secret / .dev.vars
本地开发	vite（Cloudflare Vite 插件运行 Worker 运行时）

Worker（agent + checkpointer）与 Durable Object（SSE 事件日志）之间的拆分是 Cloudflare 上的主要设计选择。Worker isolate 是短暂的，因此重放缓冲区存放在 Durable Objects 中，而不是进程内存中。

生产持久化

开箱即用时，agent 使用内存中的 MemorySaver checkpointer（worker/agent/index.ts）。这适用于本地开发和演示，但在 Cloudflare 上（多个 isolate、冷启动），对话状态在部署或 isolate 之间不具备持久性。

对于生产环境：

1. 换用持久 checkpointer（例如通过 Hyperdrive 使用 Postgres，或自定义的基于 DO 的存储）。
2. 保留每线程 Durable Objects 用于 SSE 重放（或将事件日志持久化到 DO storage / KV，以支持长期重连）。

更多信息请参阅 checkpointer 库和添加内存 / 持久化。

本地开发

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

打开 http://localhost:5173。Cloudflare Vite 插件在开发期间会在 Workers 运行时中运行你的 Worker，因此 /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/ — deep agent（createDeepAgent），包含 researcher 和 math-whiz 子 agent 以及 mock 工具。
• worker/server/ — 协议辅助函数：runs.ts（在 Worker 上启动运行）、threads.ts（由 checkpointer 支持的状态）、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

---