跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
TypeScriptAI大前端

LangChain 前端流式输出实现指南

LangChain 与 LangGraph 提供前端流式支持，核心通过 React Hook useStream 实现。该 Hook 集成流式传输、状态管理及分支逻辑。安装需配置 LangGraph SDK，可连接本地或 LangSmith 部署环境。基本用法包含提交消息、处理加载与错误状态。参数涵盖 assistantId、apiUrl、threadId 等，支持线程持久化恢复及乐观更新。高级特性包括工具调用渲染、自定义事件、多代理协作及人机循环。开发者可利用此 Hook 构建生产级生成式聊天界面。

并发大师发布于 2026/3/16更新于 2026/10/25117 浏览

LangChain 与 LangGraph 前端流式支持

LangChain 与 LangGraph 提供了强大的前端流式支持，主要通过 React Hook useStream 实现。该 Hook 与 LangGraph 的流式功能无缝集成，处理流式传输、状态管理以及分支逻辑的复杂性，帮助开发者专注于构建优秀的生成式 UI 体验。

useStream 的核心特性包括：

  • 消息流式传输：处理消息片段流，形成完整消息。
  • 自动状态管理：管理消息、中断、加载状态和错误。
  • 对话分支：从聊天历史中的任意点创建备用对话路径。
  • UI 无关设计：支持自定义组件和样式。

安装

在 React 应用中使用 useStream Hook 前，需要安装 LangGraph SDK：

pip install langgraph-sdk # Python 环境
npm install @langchain/langgraph-sdk # 前端环境

useStream 可连接本地运行的 LangGraph 图，或通过 LangSmith 部署的生产环境。

基本用法

import { useStream } from "@langchain/langgraph-sdk/react";

function Chat() {
  const stream = useStream({
    assistantId: "agent",
    // 本地开发
    apiUrl: "http://localhost:2024",
    // 生产部署（LangSmith 托管）
    // apiUrl: "https://your-deployment.us.langgraph.app"
  });

  const handleSubmit = (message: string) => {
    stream.submit({
      messages: [
        { content: message, type: "human" }
      ]
    });
  };

  return (
    <div>
      {stream.messages.map((message, idx) => (
        
          {message.type}:{message.content}
        
      ))}
      {stream.isLoading && Loading...}
      {stream.error && Error:{stream.error.message}}
    
  );
}
<div key={message.id ?? idx}>
</div>
<div>
</div>
<div>
</div>
</div>

建议将代理部署至 LangSmith 以获取生产级托管与观测能力。

useStream 参数详解

参数名类型默认值/必填说明
assistantIdstring必填连接的代理 ID。在 LangSmith 部署中需与仪表板一致。
apiUrlstringlocalhost:2024LangGraph 服务器 URL。
apiKeystring-LangSmith 部署时的认证密钥。
threadIdstring-连接现有线程，用于恢复对话。
onThreadId(id: string) => void-新线程创建时的回调，用于持久化线程 ID。
reconnectOnMountbooleantrue挂载时是否自动重连。
onCreated(run: Run) => void-新运行创建时的回调。
onError(error: Error) => void-错误回调。
onFinish(state: StateType, run?: Run) => void-流完成回调。
onCustomEvent(data: unknown, context: { mutate }) => void-处理自定义事件。
messagesKeystring"messages"状态中消息数组的键名。
throttlebooleantrue是否批量更新状态以提升渲染性能。
initialValuesStateTypenull初始状态值。

useStream 返回值

属性名类型说明
messagesMessage[]当前线程的所有消息。
valuesStateType当前图状态值（类型推断）。
isLoadingboolean是否正在流式传输。
errorError错误对象或 null。
interruptInterrupt中断信息。
toolCallsToolCallWithResult[]所有工具调用及其结果。
submit函数提交新输入，支持分支、乐观更新等选项。
stop函数立即停止当前流。
joinStream函数通过 run ID 恢复现有流。
setBranch函数切换到对话历史的不同分支。

线程管理

通过 threadId 和 onThreadId 回调管理对话线程，便于持久化和恢复。

const [threadId, setThreadId] = useState<string | null>(null);
const stream = useStream({
  // ...
  threadId,
  onThreadId: setThreadId,
});

推荐将 threadId 存储到 URL 参数或 localStorage。

页面刷新后恢复

设置 reconnectOnMount: true 可自动恢复运行流：

const stream = useStream({
  // ...
  reconnectOnMount: true,
  // 默认使用 sessionStorage
});

支持自定义存储，或手动通过 onCreated 和 joinStream 控制恢复。

乐观更新（Optimistic Updates）

在网络请求前乐观更新客户端状态，提供即时反馈。

stream.submit(
  { messages: [newMessage] },
  {
    optimisticValues: (prev) => ({
      ...prev,
      messages: [...(prev.messages ?? []), newMessage]
    })
  }
);

乐观线程创建

预先生成线程 ID，实现即时导航。

const optimisticThreadId = crypto.randomUUID();
stream.submit(
  { messages: [...] },
  { threadId: optimisticThreadId }
);

缓存线程显示

使用 initialValues 立即显示缓存数据。

分支（Branching）

通过编辑历史消息或重新生成 AI 响应创建分支。使用 getMessagesMetadata() 获取检查点信息。

类型安全流式（Type-safe Streaming）

支持与 createAgent、StateGraph 和 Annotation 类型结合，实现类型推断。

高级特性

  • 渲染工具调用：显示工具调用状态。
  • 自定义流式事件：通过 writer 发送自定义数据。
  • 事件处理：多种回调处理更新、元数据等。
  • 多代理流式：支持多代理协作。
  • 人与循环（Human-in-the-Loop）：处理中断和用户输入。
  • 自定义状态类型与传输：灵活扩展。

总结

useStream Hook 极大简化了 LangGraph 在前端的流式集成，提供完整的消息管理、线程持久化、分支持和乐观更新等功能。开发者可结合 LangSmith 部署快速构建生产级生成式聊天界面。建议参考官方示例（如 session-persistence）进行实践。

参考资料：https://docs.langchain.com/oss/python/langchain/streaming/frontend

目录

  1. LangChain 与 LangGraph 前端流式支持
  2. 安装
  3. 基本用法
  4. useStream 参数详解
  5. useStream 返回值
  6. 线程管理
  7. 页面刷新后恢复
  8. 乐观更新（Optimistic Updates）
  9. 乐观线程创建
  10. 缓存线程显示
  11. 分支（Branching）
  12. 类型安全流式（Type-safe Streaming）
  13. 高级特性
  14. 总结

更多推荐文章

查看全部
  • MOOTDX：Python 通达信数据接口封装方案
  • 商汤开源 SenseNova-MARS：多模态搜索推理模型突破性能瓶颈
  • GitHub Copilot 实战：AI 编程助手提升开发效率指南
  • 日程事件管理日历应用（纯前端实现，支持导出 Excel）
  • AI 辅助解码加密字符串的技术实践与实现
  • Spring Boot Web 三大核心交互案例详解
  • 滑动窗口算法实战：水果成篮与异位词
  • C++ 类与对象全面剖析：构造函数深化与静态成员特性
  • 《Agent Runtime 工程化》第四章 工具系统设计：4.3 工具版本演进
  • Dubbo 服务降级 Mock 机制详解与实战
  • 第十四届蓝桥杯 C/C++ 省赛 B 组题解
  • 6 款 AI 论文降重工具评测与选择指南
  • Web 应用架构与常见安全漏洞解析
  • Spring MVC 参数绑定详解：单多参/对象/集合/JSON/文件上传
  • 基于 LLaMA-Factory 的 LLM DPO 训练实战
  • AI 辅助撰写高质量文献综述：操作步骤与提示词指南
  • 利用腾讯云 HAI 与 DeepSeek 快速构建个人网页
  • F5 刷新时，浏览器前端究竟发生了什么？
  • Redis Hash 类型详解
  • PythonOCC-Core 零基础入门：环境搭建与 3D 可视化

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online