使用 Next.js 部署

以下页面详细介绍了一个示例应用：将 LangChain deep agent 完全部署在 Next.js App Router 项目中，提供流式聊天 UI、子代理和线程历史记录。所有功能都基于 Agent Streaming Protocol，并通过 Next.js Route Handlers（HTTP + SSE）实现。无需单独的后端进程。源码位于部署示例代码仓库中的 js-next。

部署到 Vercel

导入仓库

点击下方的 使用 Vercel 部署，或手动导入 langchain-ai/deployment-cookbook。

配置项目

将 Root Directory 设置为 js-next，并在项目设置中添加 OPENAI_API_KEY。

部署

部署项目。Route handlers 已经设置 runtime = "nodejs"，而 SSE 路由设置了 dynamic = "force-dynamic"，这是 Vercel 实现流式传输所必需的。

你也可以选择通过添加 .env.example 中的变量来启用 LangSmith 跟踪。

必需的 API 端点

应用通过 /api/threads/... 提供 Agent Streaming Protocol。Route handlers 位于 app/api/threads/。

最低要求（流式聊天）

以下三个端点足以运行基于 @langchain/react 的 HttpAgentServerAdapter 的单线程流式聊天：

方法	路径	用途
`POST`	`/api/threads/:threadId/commands`	接收协议命令（`run.start`、…）并启动代理运行
`POST`	`/api/threads/:threadId/stream`	为一次运行提供协议事件的 SSE 流
`GET` / `POST`	`/api/threads/:threadId/state`	读取并初始化已检查点保存的线程状态

客户端通过 GET /state 初始化线程（如果返回 404，则使用 POST /state），这样在发送第一条消息之前进行 hydration 时不会出现 404。

可选功能（线程侧边栏）

此示例还实现了线程历史记录侧边栏所需的端点。如果 UI 不需要多线程管理，可以省略这些端点：

方法	路径	用途
`GET`	`/api/threads`	列出检查点保存器已知的线程
`DELETE`	`/api/threads/:threadId`	删除线程的会话和检查点
`POST`	`/api/threads/:threadId/history`	分页获取检查点历史记录（Agent Protocol）

请求流程

初始化线程状态（GET/POST /state）。
提交时，SDK 向 /commands 发送 run.start，并接收一个 run_id。
SDK 订阅 /stream（SSE），以接收重放的协议事件和实时协议事件。
子代理（task）运行时会发出带命名空间的事件，这些事件会以 stream.subagents 的形式呈现。

生产环境中的持久化

开箱即用时，代理使用内存中的 MemorySaver 检查点保存器（lib/agent/index.ts）以及进程本地的会话映射（lib/server/registry.ts）。这适用于本地开发和单实例服务器，但在 Vercel 上（无服务器、多副本环境中），对话状态在冷启动或不同实例之间不会持久保存。在生产环境中，请替换为持久化检查点保存器：

软件包	后端
`@langchain/langgraph-checkpoint-redis`	Redis（`RedisSaver`）
`@langchain/langgraph-checkpoint-postgres`	Postgres（`PostgresSaver`）
`@langchain/langgraph-checkpoint-sqlite`	SQLite（`SqliteSaver`）

替换 lib/agent/index.ts 中的 MemorySaver，并将新的检查点保存器传递给 createDeepAgent。Route handlers 和 lib/server/threads.ts 中的辅助函数无需更改。

Vercel 上的 Redis

Vercel 上常见的选择是通过 Marketplace 使用 Redis（例如 Upstash Redis）。在 Vercel 项目中安装该集成后，凭据会自动注入为环境变量。然后接入 @langchain/langgraph-checkpoint-redis：

import { RedisSaver } from "@langchain/langgraph-checkpoint-redis";

const checkpointer = await RedisSaver.fromUrl(process.env.REDIS_URL!);

使用 Redis 服务提供商公开的连接字符串（Upstash 同时提供 REST URL 和 Redis 协议 URL；检查点保存器需要 Redis URL）。你还需要在 lib/server/registry.ts 中使用共享的会话/重放存储，这样 SSE 重连才能跨无服务器调用正常工作。替换检查点保存器是实现持久化线程历史记录的主要步骤；会话存储则是实时运行重放的独立问题。有关更多信息，请参阅检查点保存器库和添加记忆/持久化。

本地开发

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

打开 http://localhost:3000。

pnpm build   # production build
pnpm start   # serve the production build
pnpm lint    # eslint

项目结构

lib/agent/：deep agent（createDeepAgent），包含 researcher 和 math-whiz 子代理以及模拟工具。标记为 server-only。
lib/server/：协议服务器逻辑：session.ts（SSE 运行）、threads.ts（基于检查点保存器的状态）、serialize.ts、registry.ts。
app/api/threads/：用于上述协议端点的 Route Handlers。
lib/chat/threads-client.ts：浏览器端线程初始化和侧边栏辅助函数。
components/：聊天 UI（ChatApp、Chat、MessageList、Subagents、ThreadHistory 等）。

另请参阅

框架和平台概览
Agent Streaming Protocol
react-custom-backend ——用于自定义协议服务器的原始 Vite + Hono 参考实现
Next.js Route Handlers

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Deployment components

Develop & test

Frameworks and platforms

Reference

部署到 Vercel

必需的 API 端点

最低要求（流式聊天）

可选功能（线程侧边栏）

请求流程

生产环境中的持久化

Vercel 上的 Redis

本地开发

项目结构

另请参阅

​部署到 Vercel

​必需的 API 端点

​最低要求（流式聊天）

​可选功能（线程侧边栏）

​请求流程

​生产环境中的持久化

​Vercel 上的 Redis

​本地开发

​项目结构

​另请参阅

部署到 Vercel

必需的 API 端点

最低要求（流式聊天）

可选功能（线程侧边栏）

请求流程

生产环境中的持久化

Vercel 上的 Redis

本地开发

项目结构

另请参阅