使用 Nuxt 部署

以下页面详细介绍了一个示例应用，该应用将 LangChain deep agent 部署在 Nuxt 4 项目中：支持流式聊天界面、子代理详情视图、线程历史记录和推理令牌流式传输，所有功能都由通过 Nitro 路由处理器（HTTP + SSE）实现的 Agent Streaming Protocol 提供支持。无需单独的后端进程。源代码位于部署示例仓库中的 js-nuxt。

部署

Vercel
Netlify
Node

导入仓库

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

配置项目

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

部署

部署项目。Nuxt 会自动检测 Vercel，并为 Agent Streaming Protocol API 构建 Nitro 服务器路由。

导入仓库

点击下面的 Deploy to Netlify，或手动导入 langchain-ai/deployment-cookbook。

配置项目

将 Base directory 设置为 js-nuxt。Netlify 会从该子目录运行 Nuxt 构建。

设置环境变量

在首次构建完成前，将 OPENAI_API_KEY 添加到 Netlify 部署设置中。

构建生产版本

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

设置环境变量

在主机上导出 OPENAI_API_KEY。Nitro 会在运行时从环境中读取该变量。你也可以选择通过添加 .env.example 中的变量来启用 LangSmith tracing。

启动 Nitro 服务器

node .output/server/index.mjs

使用任何能够让 Node.js 进程持续运行的进程管理器或容器编排器来运行。

@langchain/vue 会从流中发现子代理，并为每个子代理渲染一个可点击的标签。选择某个标签后，会打开一个限定范围的聊天视图，该视图通过 useMessages 绑定到该子代理命名空间中的 messages 和 tools 通道。推理摘要会流式传输到可折叠的 “Thinking” 块中，并在流式传输期间自动展开。

必需的 API 端点

应用通过 /api/threads/... 暴露 Agent Streaming Protocol。Nitro 路由处理器位于 server/api/threads/。

最低要求（流式聊天）

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

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

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

可选功能（线程侧边栏）

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

Method	Path	Purpose
`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 的形式提供。

Nitro 后端设计

Concern	Implementation
前端	`app/` 中的 Vue 组件（使用 `<ClientOnly>` 包装，以支持 SSE）
API 层	`server/api/threads/` 中的 Nitro 路由处理器
运行时	Node.js（Nitro preset 取决于部署目标）
SSE 重放	进程本地的 `LocalThreadSession`（`server/utils/session.ts`）
Agent 运行	同一个 Nitro 进程；事件缓存在 LangGraph `StreamChannel` 中
线程存储	内存中的 `MemorySaver` 检查点保存器（`server/agent/index.ts`）
密钥	本地使用 `.env`；生产环境使用主机环境变量

Agent 的检查点保存器是线程的唯一事实来源。客户端没有缓存：侧边栏始终从服务器获取，重启服务器会清除所有线程。

生产环境持久化

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

Package	Backend
`@langchain/langgraph-checkpoint-redis`	Redis（`RedisSaver`）
`@langchain/langgraph-checkpoint-postgres`	Postgres（`PostgresSaver`）
`@langchain/langgraph-checkpoint-sqlite`	SQLite（`SqliteSaver`）

替换 server/agent/index.ts 中的 MemorySaver，并将新的检查点保存器传递给 createDeepAgent。Nitro 路由处理器和 server/utils/threads.ts 辅助函数无需更改。你还需要在 server/utils/runtime.ts 中使用共享的会话/重放存储，以确保 SSE 重连能够跨无服务器调用正常工作。更多信息请参阅检查点保存器库和添加记忆/持久化。

本地开发

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

打开 http://localhost:3000。发送一个会委派任务给子代理的提示，并观察它们的工作流式传输到专用卡片中。

pnpm build      # production build
pnpm preview    # preview the production build
pnpm typecheck  # vue-tsc over the project

项目结构

Project structure

server/agent/ — deep agent（createDeepAgent），包含 researcher 和 math-whiz 子代理、模拟工具以及 stripReasoningReplay 中间件。
server/utils/ — 协议服务器逻辑：session.ts（SSE 运行）、threads.ts（由检查点保存器支持的状态）、serialize.ts、runtime.ts。
server/api/threads/ — 上述协议端点对应的 Nitro 路由处理器。
app/components/ — Vue 聊天界面（ChatApp、Chat、ThreadHistory、SubagentList、MessageReasoning 等），使用 @langchain/vue。
app/utils/threads.ts — 由服务器驱动的线程辅助函数和 LangGraph SDK 初始化逻辑。

Backend details

server/agent/index.ts — 协调器通过 Responses API 使用推理模型；使用工具的子代理采用 chat-completions（以避免通过检查点保存器重放推理项）。
server/agent/middleware.ts — 根据 content + tool_calls 重新构建之前的 assistant 消息，确保过期的推理 ID 永远不会被重放到 Responses API。
server/utils/session.ts — LocalThreadSession 会缓存协议事件，并通过 matchesSubscription 将匹配的帧分发到 SSE。
server/api/threads/index.get.ts — GET /api/threads，由检查点保存器支持的线程列表。
server/api/threads/[threadId]/… — 处理 commands、stream、state（GET/POST）、history 和 DELETE 的处理器。

Frontend details

app/components/ChatThread.vue — 构建 HttpAgentServerAdapter，并调用 provideStream({ transport, threadId })。
app/components/Chat.vue — 包含消息视图、消息编辑器以及每个子代理的详情视图（带面包屑）。
app/components/SubagentList.vue / SubagentDetail.vue — 内嵌的子代理卡片和限定范围的子代理聊天（将 useMessages 绑定到命名空间）。
app/components/MessageReasoning.vue — 用于显示推理摘要的可折叠 “Thinking” 块。

另请参阅

框架和平台概览
Agent Streaming Protocol
react-custom-backend — 用于自定义协议服务器的原始 Vite + Hono 参考实现
@langchain/vue — useStream、provideStream 和选择器 composables
前端概览

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

部署

必需的 API 端点

最低要求（流式聊天）

可选功能（线程侧边栏）

请求流程

Nitro 后端设计

生产环境持久化

本地开发

项目结构

另请参阅

​部署

​必需的 API 端点

​最低要求（流式聊天）

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

​请求流程

​Nitro 后端设计

​生产环境持久化

​本地开发

​项目结构

​另请参阅

部署

必需的 API 端点

最低要求（流式聊天）

可选功能（线程侧边栏）

请求流程

Nitro 后端设计

生产环境持久化

本地开发

项目结构

另请参阅