使用 Next.js 部署

在 Next.js App Router 项目中部署 LangChain deep agent，具备流式聊天、子 agent 和线程历史。

以下页面详细介绍一个示例应用：它完全在 Next.js App Router 项目中部署 LangChain deep agent：流式聊天 UI、子 agent 和线程历史，全部由 Agent Streaming Protocol 提供支持，并以 Next.js Route Handlers（HTTP + SSE）形式实现。无需单独的后端进程。

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

部署到 Vercel

Import the repository

点击下方的 Deploy with Vercel，或手动导入 langchain-ai/deployment-cookbook。

Configure the project

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

Deploy

部署该项目。路由处理程序已经设置了 runtime = "nodejs"，SSE 路由设置了 dynamic = "force-dynamic"，这是 Vercel 进行流式传输所需要的。

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

必需的 API 端点

该应用在 /api/threads/... 下暴露 Agent Streaming Protocol。路由处理程序位于 app/api/threads/。

最小集（流式聊天）

这三个端点足以使用 @langchain/react 的 HttpAgentServerAdapter 运行单线程流式聊天：

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

客户端使用 GET /state（以及 404 时的 POST /state）引导线程，这样在发送第一条消息之前进行水合时不会出现 404。

可选（线程边栏）

此示例还为线程历史边栏实现了端点。如果你的 UI 不需要多线程管理，可以省略它们：

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

请求流程

%%{init: {"themeVariables": {"lineColor": "#40668D", "primaryColor": "#E5F4FF", "primaryTextColor": "#030710", "primaryBorderColor": "#006DDD"}}}%%
flowchart TB
  subgraph browser["Browser"]
    SP["StreamProvider"]
    Adapter["HttpAgentServerAdapter"]
    SP --- Adapter
  end

  subgraph routes["Next.js Route Handlers (Node runtime)"]
    CMD["POST /api/threads/:id/commands"]
    STR["POST /api/threads/:id/stream (SSE)"]
    STA["GET|POST /api/threads/:id/state"]
  end

  subgraph server["lib/server"]
    SRV["session · threads · registry"]
  end

  subgraph agent["lib/agent"]
    AGT["createDeepAgent + checkpointer"]
  end

  Adapter -->|POST| CMD
  Adapter -->|POST| STR
  Adapter -->|GET / POST| STA
  CMD --> SRV
  STR --> SRV
  STA --> SRV
  SRV --> 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,routes process
  class server trigger
  class agent output

1. 引导线程状态（GET/POST /state）。
2. 提交时，SDK 向 /commands 发送 run.start 并收到一个 run_id。
3. SDK 订阅 /stream（SSE）以接收重放和实时协议事件。
4. 子 agent（task）运行会发出带命名空间的事件，并通过 stream.subagents 呈现。

生产持久化

开箱即用时，agent 使用内存中的 MemorySaver checkpointer（lib/agent/index.ts）和进程本地会话映射（lib/server/registry.ts）。这适用于本地开发和单实例服务器，但在 Vercel 上（无服务器、多个副本），对话状态在冷启动或实例之间不具备持久性。

对于生产环境，请换用持久 checkpointer：

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

将 lib/agent/index.ts 中的 MemorySaver 替换掉，并将新的 checkpointer 传给 createDeepAgent。路由处理程序和 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 和 Redis 协议 URL；checkpointer 需要 Redis URL）。

你还需要在 lib/server/registry.ts 中提供一个共享的会话/重放存储，以便 SSE 重连能够跨无服务器调用工作。替换 checkpointer 是实现持久线程历史的主要步骤；会话存储则是实时运行重放的另一个独立关注点。

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

本地开发

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 子 agent 以及 mock 工具。标记为 server-only。
• lib/server/：协议服务器逻辑：session.ts（SSE 运行）、threads.ts（由 checkpointer 支持的状态）、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

---