使用 Nuxt 部署 - 以编程方式使用文档

以下页面详细介绍了一个部署 LangChain 的示例应用 **深度代理** 在 Nuxt 4 项目中：流式聊天 UI、子代理详情视图、线程历史记录和推理令牌流，全部由 Agent Streaming Protocol 提供支持，实现为 Nitro 路由处理器（HTTP + SSE）。无需单独的后端进程。

Source: js-nuxt 在部署指南中。

部署

Vercel

Import the repository

点击 **使用 Vercel 部署** 下方，或导入 langchain-ai/deployment-cookbook manually.

Configure the project

设置 **根目录** to js-nuxt 并添加 OPENAI_API_KEY 在项目设置中。

Deploy

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

Netlify

Import the repository

点击 **部署到 Netlify** 下方，或导入 langchain-ai/deployment-cookbook manually.

Configure the project

设置 **基础目录** to js-nuxt. Netlify 从该子目录运行 Nuxt 构建。

Set environment variables

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

Node

Build for production

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

Set environment variables

导出 OPENAI_API_KEY 在主机上。Nitro 在运行时从环境变量中读取它。

可选：添加以下变量以启用 LangSmith 追踪 .env.example.

Start the Nitro server

node .output/server/index.mjs

在任何保持 Node.js 进程运行的过程管理器或容器编排器后面运行。

必需的 API 端点

应用在以下位置公开了代理流式协议 /api/threads/...。Nitro 路由处理程序位于 server/api/threads/.

最小集（流式聊天）

这三个端点足以运行带有 @langchain/vue's HttpAgentServerAdapter:

方法	路径	用途
`POST`	`/api/threads/:threadId/commands`	接受协议命令（`run.start`、…）并启动代理运行
`POST`	`/api/threads/:threadId/stream`	运行的 SSE 协议事件流
`GET` / `POST`	`/api/threads/:threadId/state`	读取并引导检查点线程状态

客户端使用 GET /state （和 POST /state 在 404 时）引导线程，以防止首次发送消息前水合作用 404。

可选（线程侧边栏）

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

方法	路径	用途
`GET`	`/api/threads`	列出检查点已知的所有线程
`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

引导线程状态（GET/POST /state).
提交时，SDK 发送 run.start to /commands 并接收 run_id.
SDK 订阅 /stream （SSE）用于重放和实时协议事件。
子代理（task）运行发出的命名空间事件作为 stream.subagents.

Nitro 后端设计

关注点	实现
前端	Vue 组件位于 `app/` （包装在 `` 中以支持 SSE）
API 层	Nitro 路由处理器位于 `server/api/threads/`
运行时	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）。这适用于本地开发和单实例服务器，但在无服务器或多实例主机上，会话状态在冷启动或副本之间 **不能持久化** 。

对于生产环境，换用持久化检查点:

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

替换 MemorySaver in server/agent/index.ts 并将新的检查点传递给 createDeepAgent。Nitro 路由处理器和 server/utils/threads.ts 辅助函数保持不变。

You will also want a shared session/replay store in server/utils/runtime.ts 这样 SSE 重连就可以跨无服务器调用工作。

更多信息，请参阅检查点库和 add memory / persistence.

本地开发

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/ — 深度代理 (createDeepAgent) 与 researcher 和 math-whiz 子代理、模拟工具和 stripReasoningReplay middleware.
- server/utils/ — 协议服务器逻辑： session.ts (SSE 运行)， threads.ts (检查点支持的状态)， serialize.ts, runtime.ts.
- server/api/threads/ — 上述协议端点的 Nitro 路由处理器。
- app/components/ — Vue 聊天 UI (ChatApp, Chat, ThreadHistory, SubagentList, MessageReasoning，…) 使用 @langchain/vue.
- app/utils/threads.ts — 服务器驱动的线程助手和 LangGraph SDK 引导。

Backend details

- server/agent/index.ts — 协调器通过 Responses API 使用推理模型；使用工具的子代理使用聊天补全（以避免通过检查点重放推理项）。
- server/agent/middleware.ts — 从 content + tool_calls 重新构建之前的助手消息，这样过时的推理 ID 就不会重放到 Responses API。
- server/utils/session.ts — LocalThreadSession 缓冲协议事件并通过 SSE 将匹配的帧分发出 matchesSubscription.
- 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 — 用于推理摘要的可折叠"思考"块。

另请参见

- 框架和平台概述
- 代理流协议
- react-custom-backend — 自定义协议服务器的原始 Vite + Hono 参考
- @langchain/vue — useStream, provideStream和选择器组合
- 前端概述