以编程方式使用文档

以下页面详细说明了一个部署 LangChain **深度智能体** 的示例应用，在 SvelteKit 项目中构建，适配 Cloudflare Workers ，具有 @sveltejs/adapter-cloudflare：流式聊天 UI、子智能体详情视图、线程历史记录，以及 Agent Streaming Protocol 在 /api/threads/...下暴露。无需单独的后端进程。

Source: 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 适配器文档一致。构建脚本将 ThreadSession Durable Object 导出追加到生成的 Worker 入口，因为 Durable Object 类必须由 Worker 模块导出。

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

可选：添加 .env.example 中的变量作为 Worker secrets 或 vars 来启用 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 层SvelteKit 服务端点位于 src/routes/api/threads/
运行时Workers V8 + nodejs_compat
SSE 回放每个线程一个 Durable Object（ThreadSession)
智能体运行Worker 隔离；协议事件 POST 到 DO
静态资源通过 Workers Static Assets adapter-cloudflare
密钥wrangler secret / local .env

生产环境持久化

开箱即用，智能体使用内存中的 MemorySaver 检查点（src/lib/server/agent/index.ts). The per-thread SSE replay/session log lives in a Durable Object 因此流式客户端重新连接到单个协调点，而不是进程本地映射。

检查点仍然使用隔离本地演示状态。Cloudflare隔离是临时的，可以水平扩展，因此检查点的对话状态 **不是持久化的** 在部署、冷启动或隔离之间不能保持。

对于生产环境：

  1. 换成持久化的检查点（例如 通过 Hyperdrive 连接 Postgres, or a 自定义 Durable Object 支持的存储).
  2. Persist long-lived replay/history if clients need to reconnect after the Durable Object has been evicted from memory.

本地开发

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

项目布局

Project structure

  • - src/lib/server/agent/ — 深度代理 (createDeepAgent) 包含 researcher 和 math-whiz 子代理和模拟工具。
  • - src/lib/server/durable-objects/thread-session.ts — 每个线程的 Durable Object 事件日志，用于 SSE 重放。
  • - src/lib/server/protocol/ — Agent Streaming Protocol helpers: checkpointer-backed state/history, run publishing, serialization, and registry.
  • - src/routes/api/threads/ — SvelteKit 路由处理器，用于协议端点。
  • - src/lib/chat/threads-client.ts — 浏览器线程引导和侧边栏助手。
  • - src/lib/components/ — 使用 Svelte 的聊天界面 @langchain/svelte.
  • - svelte.config.js — 使用配置 SvelteKit @sveltejs/adapter-cloudflare.
  • - scripts/export-durable-objects.mjs — 构建后补丁，从生成的 Worker 入口重新导出 Durable Object 类。
  • - wrangler.jsonc — Cloudflare Workers 静态资源和 Durable Object 配置。

另请参阅