以编程方式使用文档

以下页面详细说明了一个示例应用，该应用部署了一个 LangChain **深度智能体** 完全在 Next.js App Router 项目中：流式聊天 UI、子智能体和线程历史，全部由 Agent Streaming Protocol 提供支持，实现为 Next.js Route Handlers（HTTP + SSE）。无需单独的后端进程。

Source: js-next 部署指南中。

部署到 Vercel

Import the repository

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

Deploy with Vercel

Configure the project

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

Deploy

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

（可选）通过添加 .env.example.

所需的 API 端点

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

最小配置（流式聊天）

这三个端点足以运行带有 @langchain/react'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"]
    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 发送 run.start to /commands 并接收 run_id.
  3. SDK 订阅 /stream （SSE）以进行重放 + 实时协议事件。
  4. 子智能体（task）运行发出命名空间事件，作为 stream.subagents.

生产环境持久化

开箱即用，智能体使用内存中 MemorySaver 检查点（lib/agent/index.ts) 和一个进程本地的会话映射 (lib/server/registry.ts). 这适用于本地开发和单实例服务器，但在 Vercel（无服务器、多副本）上，对话状态是 **非持久化的** 在冷启动或实例间不持久化。

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

PackageBackend
@langchain/langgraph-checkpoint-redisRedis (RedisSaver)
@langchain/langgraph-checkpoint-postgresPostgres (PostgresSaver)
@langchain/langgraph-checkpoint-sqliteSQLite (SqliteSaver)

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

Vercel 上的 Redis

Vercel 的常见选择是通过 市场 使用 Redis（例如 Upstash Redis）。在 Vercel 项目上安装集成；凭证会自动注入为环境变量。

然后连接 @langchain/langgraph-checkpoint-redis:

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

使用 Redis 提供商公开的连接字符串（Upstash 同时提供 REST 和 Redis 协议 URL；检查点器需要 Redis URL）。

You will also want a shared session/replay store in lib/server/registry.ts 这样 SSE 重连就能跨无服务器调用工作。检查点器交换是实现持久化线程历史记录的主要步骤；会话存储是实时运行回放的独立问题。

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

本地开发

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/：深度智能体 (createDeepAgent) 配合 researcher 和 math-whiz 子智能体及模拟工具。标记 server-only.
  • - lib/server/：协议服务器逻辑： session.ts （SSE 运行）， threads.ts （检查点器支持的状态）， serialize.ts, registry.ts.
  • - app/api/threads/：上述协议端点的路由处理程序。
  • - lib/chat/threads-client.ts：浏览器线程引导和侧边栏辅助函数。
  • - components/：聊天 UI (ChatApp, Chat, MessageList, Subagents, ThreadHistory, …).

另请参阅