使用 Nuxt 部署

在 Nuxt 4 应用中部署 LangChain deep agent，使用 Nitro 服务器路由、Vue 组合式函数和支持子 agent 的聊天 UI。

以下页面详细介绍一个示例应用：它在 Nuxt 4 项目中部署 LangChain deep agent，包含流式聊天 UI、子 agent 详情视图、线程历史和推理 token 流式传输，全部由以 Nitro 路由处理程序（HTTP + SSE）形式实现的 Agent Streaming Protocol 提供支持。无需单独的后端进程。

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

部署

导入仓库

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

配置项目

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

部署

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

TIP

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

必需的 API 端点

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

最小集（流式聊天）

这三个端点足以使用 @langchain/vue 的 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 (Vue)"]
    SP["StreamProvider"]
    Adapter["HttpAgentServerAdapter"]
    SP --- Adapter
  end

  subgraph nitro["Nitro route handlers"]
    CMD["POST /api/threads/:id/commands"]
    STR["POST /api/threads/:id/stream (SSE)"]
    STA["GET|POST /api/threads/:id/state"]
  end

  subgraph server["server/utils"]
    SRV["session · threads · runtime"]
  end

  subgraph agent["server/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,nitro 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 呈现。

Nitro 后端设计

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

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

生产持久化

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

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

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

替换 server/agent/index.ts 中的 MemorySaver，并将新的 checkpointer 传递给 createDeepAgent。Nitro 路由处理程序和 server/utils/threads.ts 辅助函数保持不变。

你还需要在 server/utils/runtime.ts 中提供一个共享的会话/重放存储，以便 SSE 重连能够跨无服务器调用工作。

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

本地开发

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

打开 http://localhost:3000。发送一个委派给子 agent 的提示词，并观察它们的工作流入专用卡片。

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

项目布局

项目结构

• server/agent/ — deep agent（createDeepAgent），包含 researcher 和 math-whiz 子 agent、mock 工具和 stripReasoningReplay 中间件。
• server/utils/ — 协议服务器逻辑：session.ts（SSE 运行）、threads.ts（由 checkpointer 支持的状态）、serialize.ts、runtime.ts。
• server/api/threads/ — 上述协议端点的 Nitro 路由处理程序。
• app/components/ — 使用 @langchain/vue 的 Vue 聊天 UI（ChatApp、Chat、ThreadHistory、SubagentList、MessageReasoning 等）。
• app/utils/threads.ts — 服务器驱动的线程辅助函数和 LangGraph SDK 引导。

后端详情

• server/agent/index.ts — 协调器在 Responses API 上使用推理模型；使用工具的子 agent 使用 chat-completions（以避免通过 checkpointer 重放推理项）。
• server/agent/middleware.ts — 从 content + tool_calls 重建先前的助手消息，确保过时的推理 id 永远不会被重放到 Responses API。
• server/utils/session.ts — LocalThreadSession 缓冲协议事件，并通过 matchesSubscription 将匹配的帧通过 SSE 分发。
• server/api/threads/index.get.ts — GET /api/threads，由 checkpointer 支持的线程列表。
• server/api/threads/[threadId]/… — commands、stream、state（GET/POST）、history 和 DELETE 的处理程序。

前端详情

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

另请参阅

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

---