概述

将 LangGraph 智能体渲染到前端

构建能够实时可视化 LangGraph 管道的前端。这些模式 展示了如何从自定义 StateGraph 工作流渲染带有每个节点状态和流式 内容的多步骤图执行。

LangGraph 的前端优势在于 UI 可以遵循与 图相同的结构。节点、状态键、检查点、中断、子图和流式 消息都是可见的运行时概念，因此你可以构建能够 解释系统正在做什么的界面，而不是将执行隐藏在一 条助手消息背后。

NOTE

这些模式使用 v1 前端 SDK 包。如果你使用的是更早的版本，请参阅 React、Vue、Svelte 和 Angular 的迁移指南。

架构

LangGraph 图由通过边连接的具名节点组成。每个节点执行一个步骤（分类、研究、分析、综合），并将输出写入特定的状态键。在前端，SDK 流句柄提供对节点输出、流式 token 和已发现子图的响应式访问，因此你可以将每个节点映射到一张 UI 卡片。

%%{
  init: {
    "fontFamily": "monospace",
    "flowchart": {
      "curve": "curve"
    }
  }
}%%
graph LR
  FRONTEND["useStream()"]
  GRAPH["StateGraph"]
  N1["Node A"]
  N2["Node B"]
  N3["Node C"]

  GRAPH --"stream"--> FRONTEND
  FRONTEND --"submit"--> GRAPH
  GRAPH --> N1
  N1 --> N2
  N2 --> N3

  classDef blueHighlight fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A;
  classDef greenHighlight fill:#DCFCE7,stroke:#16A34A,color:#14532D;
  classDef orangeHighlight fill:#FEF3C7,stroke:#D97706,color:#92400E;
  class FRONTEND blueHighlight;
  class GRAPH greenHighlight;
  class N1,N2,N3 orangeHighlight;

from langgraph.graph import StateGraph, MessagesState, START, END

class State(MessagesState):
    classification: str
    research: str
    analysis: str
    synthesis: str

graph = StateGraph(State)
graph.add_node("classify", classify_node)
graph.add_node("do_research", research_node)
graph.add_node("analyze", analyze_node)
graph.add_node("synthesize", synthesize_node)
graph.add_edge(START, "classify")
graph.add_edge("classify", "do_research")
graph.add_edge("do_research", "analyze")
graph.add_edge("analyze", "synthesize")
graph.add_edge("synthesize", END)

app = graph.compile()

在前端，useStream 为图节点发现暴露 stream.subgraphs， 并提供选择器辅助函数，例如面向节点作用域 流式内容的 useMessages(stream, node)。当你 需要诸如最终 synthesis 之类的字段时，stream.values 仍然持有完整的图状态。Angular 通过 injectStream 使用相同的流 API 形态。

import { useStream } from "@langchain/react";

function Pipeline() {
  const stream = useStream<typeof graph>({
    apiUrl: "http://localhost:2024",
    assistantId: "pipeline",
  });

  const classification = stream.values?.classification;
  const research = stream.values?.research;
  const analysis = stream.values?.analysis;
  const graphNodes = [...stream.subgraphs.values()];
}

它与聊天流有何不同

自定义图常常为产品工作流提供支持：研究管道、审批流、 数据管道、数据丰富、代码审查、规划和多步骤分析。 前端 SDK 让你使用图原生信号来渲染这些工作流：

运行时概念	前端 UX
具名节点	每个图节点对应一张卡片、一个时间线步骤或一个状态徽章。
状态键	为类型化输出（例如分类、来源、分析和最终综合）提供专门的 UI 区域。
流式元数据	将部分消息路由到产生它们的节点。
检查点	检查或从先前的图状态恢复，以便调试和审计。
中断	暂停某个节点以等待人工输入、审批或更正，然后继续。
子图	仅在用户需要更多细节时揭示嵌套执行。

由于 SDK 直接暴露这些概念，你可以从一个简单的 聊天面板扩展到完整的工作流调试器，而无需更改后端协议。

模式

•Graph execution

可视化多步骤图管道，并展示每个节点的状态和流式内容。

•Custom stream channels

将自定义的服务端数据流式传输到前端，并使用 useExtension 和 useChannel 读取它。

相关模式

LangChain 前端模式 —— markdown 消息、工具调用、人在回路、可恢复流和时间旅行 —— 可与任何 LangGraph 图配合使用。无论你使用 createAgent、createDeepAgent 还是自定义的 StateGraph，流 API 都提供相同的核心数据模型。

---