以下页面详细说明了部署 LangChain **深度智能体** on Cloudflare Workers的示例应用：流式聊天 UI、子智能体和线程历史记录，所有内容都由 智能体流式协议 提供支持，该协议通过 Worker 路由（HTTP + SSE）实现。React SPA 通过 Workers Assets从同一个 Worker 提供服务。不需要单独的后端进程：一个 Worker 同时提供 SPA 和协议 API。

Source: js-cloudflare 在部署指南中。

部署到 Cloudflare

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

npx wrangler login
npx wrangler secret put OPENAI_API_KEY

pnpm run deploy

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

wrangler.jsonc 向 ThreadSession Durable Object 注册 new_sqlite_classes，这是在 Workers **Free** plan.

上所必需的 API 端点

该应用在 /api/threads/...下公开智能体流式协议。路由在 worker/index.ts 中使用 Hono.

最小配置（流式聊天）

可选（侧边栏）

请求流程

%%{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 发送 run.start to /commands 并接收 run_id.
3. Worker 启动图运行并将每个协议事件扇出到线程的 **Durable Object**.
4. SDK 订阅 /stream （SSE）。DO 回放缓冲的事件并在实时帧期间保持连接，即使跨 Worker 隔离重启。
5. 子智能体（task）运行发出的命名空间事件作为 stream.subagents.

Cloudflare 后端设计

之间的划分 **Worker** （agent + checkpointer）和 **Durable Object** （SSE 事件日志）是 Cloudflare 的主要设计选择。Worker 隔离是临时的，因此重放缓冲区存储在 Durable Objects 中，而不是进程内存中。

生产环境持久化

开箱即用，agent 使用内存 MemorySaver checkpointer（worker/agent/index.ts）。这适用于本地开发和演示，但在 Cloudflare（多个隔离、冷启动）对话状态 **不是持久化的** 跨部署或隔离。

对于生产环境：

1. 换入 持久化 checkpointer （例如通过 Hyperdrive 的 Postgres，或自定义 DO 支持的存储）。
2. Keep per-thread Durable Objects for SSE replay (or persist the event log to DO storage / KV for long-lived reconnects).

更多信息，请参阅 checkpointer 库 和 add memory / persistence.

本地开发

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/ — 深度 agent（createDeepAgent）包含 researcher 和 math-whiz subagent 和模拟工具。
• - worker/server/ — 协议助手： runs.ts （start 在 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 流式传输协议
• - Cloudflare Workers
• - Durable Objects