使用 SvelteKit 部署

在 Cloudflare Workers 上的 SvelteKit 项目中部署 LangChain deep agent，支持流式聊天和线程历史。

以下页面详细介绍一个示例应用：它在 SvelteKit 项目中部署 LangChain deep agent，针对 Cloudflare Workers 构建，使用 @sveltejs/adapter-cloudflare：流式聊天 UI、子 agent 详情视图、线程历史，以及在 /api/threads/... 下暴露的 Agent Streaming Protocol。无需单独的后端进程。

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

部署到 Cloudflare

Install and build

cd js-sveltekit
cp .env.example .env   # 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

svelte.config.js 使用 adapter-cloudflare()。wrangler.jsonc 将 Wrangler 指向 .svelte-kit/cloudflare/_worker.js，并从 .svelte-kit/cloudflare 提供静态资源，与 SvelteKit Cloudflare adapter 文档一致。构建脚本会将 ThreadSession Durable Object 导出追加到生成的 Worker 入口，因为 Durable Object 类必须由 Worker 模块导出。

启用 nodejs_compat 和 nodejs_compat_populate_process_env，因为 LangChain 运行时和追踪集成需要 Node 兼容的 API 和环境访问。

可选地，通过将 .env.example 中的变量添加为 Worker secret 或 var 来启用 LangSmith 追踪。

必需的 API 端点

应用在 /api/threads/... 下暴露 Agent Streaming Protocol。SvelteKit 路由处理函数位于 src/routes/api/threads/。

最小集（流式聊天）

方法	路径	用途
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 历史

Cloudflare 后端设计

关注点	实现
前端	SvelteKit 客户端路由和组件
API 层	src/routes/api/threads/ 中的 SvelteKit 服务端端点
运行时	Workers V8 + nodejs_compat
SSE 重放	每线程一个 Durable Object（ThreadSession）
Agent 运行	Worker isolate；协议事件 POST 到 DO
静态资源	通过 adapter-cloudflare 使用 Workers Static Assets
密钥	wrangler secret / 本地 .env

生产持久化

开箱即用，agent 使用内存中的 MemorySaver checkpointer（src/lib/server/agent/index.ts）。每线程的 SSE 重放/会话日志位于 Durable Object 中，因此流式客户端会重新连接到一个协调点，而不是进程本地映射。

该 checkpointer 仍是 isolate 本地的演示状态。Cloudflare isolate 是临时的，并且可能水平扩展，因此 checkpoint 的对话状态在部署、冷启动或 isolate 之间不持久。

对于生产环境：

1. 换用持久化 checkpointer（例如通过 Hyperdrive 使用 Postgres，或由 Durable Object 支持的自定义存储）。
2. 如果客户端需要在 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/ — deep agent（createDeepAgent），带有 researcher 和 math-whiz 子 agent 以及 mock 工具。
• src/lib/server/durable-objects/thread-session.ts — 用于 SSE 重放的每线程 Durable Object 事件日志。
• src/lib/server/protocol/ — Agent Streaming Protocol 辅助函数：由 checkpointer 支持的状态/历史、run 发布、序列化和注册表。
• 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 Cloudflare adapter
• Agent Streaming Protocol
• @langchain/svelte

---