图执行

可视化多步骤图管道，包含每个节点的状态和流式内容

LangGraph 智能体不是黑盒。每个图由命名节点组成，这些节点按顺序或并行执行：分类、研究、分析、综合。图执行卡片通过为每个节点渲染一张卡片，使此管道可见，显示其状态，实时流式传输其内容，并跟踪整个工作流的完成情况。用户可以准确地看到智能体正在做什么、处于哪个步骤以及每个步骤产生了什么。

图节点如何映射到 UI 卡片

LangGraph 图定义了一系列节点，每个节点负责一个特定的任务。例如，一个研究管道可能包含：

1. 分类：对用户的查询进行分类
2. 研究：收集相关信息
3. 分析：从研究中得出结论
4. 综合：生成最终的精炼响应

每个节点将其输出写入图状态中的特定键。通过将这些节点名称和状态键映射到 UI 组件，你可以创建整个管道的可视化表示。

const PIPELINE_NODES = [
  { name: "classify", stateKey: "classification", label: "Classify" },
  { name: "do_research", stateKey: "research", label: "Research" },
  { name: "analyze", stateKey: "analysis", label: "Analyze" },
  { name: "synthesize", stateKey: "synthesis", label: "Synthesize" },
];

const PIPELINE_NODE_NAMES = new Set(PIPELINE_NODES.map((n) => n.name));

设置 useStream

像往常一样连接 useStream。你将使用的关键属性是 messages（用于流式内容路由）、values（用于已完成的节点输出）和 getMessagesMetadata（用于识别哪个节点产生了每个 Token）。

定义一个与你的智能体状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以实现对状态值（包括每个管道节点的自定义状态键）的类型安全访问。在下面的示例中，将 typeof myAgent 替换为你的接口名称：

import type { BaseMessage } from "@langchain/core/messages";

interface AgentState {
  messages: BaseMessage[];
  classification: string;
  research: string;
  analysis: string;
  synthesis: string;
}

React

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

const AGENT_URL = "http://localhost:2024";

export function PipelineChat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "graph_execution_cards",
  });

  return (
    <div>
      <PipelineProgress nodes={PIPELINE_NODES} values={stream.values} />
      <NodeCardList
        nodes={PIPELINE_NODES}
        messages={stream.messages}
        values={stream.values}
        getMetadata={stream.getMessagesMetadata}
      />
    </div>
  );
}

将流式 Token 路由到节点

当智能体进行流式输出时，每条消息都带有标识哪个图节点产生它的元数据注解。使用 getMessagesMetadata 提取 langgraph_node 值，并将 Token 路由到正确的卡片：

function getStreamingContent(
  messages: BaseMessage[],
  getMetadata: (msg: BaseMessage) => MessageMetadata | undefined
): Record<string, string> {
  const content: Record<string, string> = {};

  for (const message of messages) {
    if (message.type !== "ai") continue;

    const metadata = getMetadata(message);
    const node = metadata?.streamMetadata?.langgraph_node;

    if (node && PIPELINE_NODE_NAMES.has(node)) {
      content[node] = typeof message.content === "string"
        ? message.content
        : "";
    }
  }

  return content;
}

这会给你一个从节点名称到其当前流式内容的映射。随着 Token 的到达，相应的卡片会实时更新。

streamMetadata.langgraph_node 字段由 LangGraph 自动设置。你不需要在后端进行任何特殊配置。只需像往常一样流式传输消息，元数据就会自动包含。

确定节点状态

每个节点可以处于四种状态之一：未开始、流式传输中、已完成或空闲。你可以从两个来源推导状态：流式内容映射（用于活跃节点）和 stream.values（用于已完成节点）：

type NodeStatus = "idle" | "streaming" | "complete";

function getNodeStatus(
  node: { name: string; stateKey: string },
  streamingContent: Record<string, string>,
  values: Record<string, unknown>
): NodeStatus {
  if (values?.[node.stateKey]) return "complete";
  if (streamingContent[node.name]) return "streaming";
  return "idle";
}

构建管道进度条

顶部的水平进度条为用户提供了整个管道的鸟瞰视图。每个步骤是一个标记段，随着节点完成而填充：

function PipelineProgress({
  nodes,
  values,
  streamingContent,
}: {
  nodes: typeof PIPELINE_NODES;
  values: Record<string, unknown>;
  streamingContent: Record<string, string>;
}) {
  return (
    <div className="flex items-center gap-1">
      {nodes.map((node, i) => {
        const status = getNodeStatus(node, streamingContent, values);
        const colors = {
          idle: "bg-gray-200 text-gray-500",
          streaming: "bg-blue-400 text-white animate-pulse",
          complete: "bg-green-500 text-white",
        };

        return (
          <div key={node.name} className="flex items-center">
            <div
              className={`rounded-full px-3 py-1 text-xs font-medium ${colors[status]}`}
            >
              {node.label}
            </div>
            {i < nodes.length - 1 && (
              <div
                className={`mx-1 h-0.5 w-6 ${
                  status === "complete" ? "bg-green-500" : "bg-gray-200"
                }`}
              />
            )}
          </div>
        );
      })}
    </div>
  );
}

构建可折叠的 NodeCard 组件

每个节点都有自己的卡片，显示状态徽章、内容（流式或最终）以及用于长输出的可折叠主体：

function NodeCard({
  node,
  status,
  streamingContent,
  completedContent,
}: {
  node: { name: string; stateKey: string; label: string };
  status: NodeStatus;
  streamingContent: string | undefined;
  completedContent: unknown;
}) {
  const [collapsed, setCollapsed] = useState(false);

  const displayContent =
    status === "complete"
      ? formatContent(completedContent)
      : streamingContent ?? "";

  const statusBadge = {
    idle: { text: "等待中", className: "bg-gray-100 text-gray-600" },
    streaming: {
      text: "运行中",
      className: "bg-blue-100 text-blue-700 animate-pulse",
    },
    complete: { text: "完成", className: "bg-green-100 text-green-700" },
  };

  const badge = statusBadge[status];

  return (
    <div className="rounded-lg border bg-white shadow-sm">
      <button
        onClick={() => setCollapsed(!collapsed)}
        className="flex w-full items-center justify-between p-4"
      >
        <div className="flex items-center gap-3">
          <h3 className="font-semibold">{node.label}</h3>
          <span
            className={`rounded-full px-2 py-0.5 text-xs font-medium ${badge.className}`}
          >
            {badge.text}
          </span>
        </div>
        <ChevronIcon direction={collapsed ? "down" : "up"} />
      </button>

      {!collapsed && displayContent && (
        <div className="border-t px-4 py-3">
          <div className="prose prose-sm max-w-none">
            {displayContent}
            {status === "streaming" && (
              <span className="inline-block h-4 w-1 animate-pulse bg-blue-500" />
            )}
          </div>
        </div>
      )}
    </div>
  );
}

function formatContent(value: unknown): string {
  if (typeof value === "string") return value;
  if (value == null) return "";
  return JSON.stringify(value, null, 2);
}

流式内容与已完成内容

每个节点有两个内容来源，选择正确的来源对于良好的用户体验很重要：

来源	何时使用
streamingContent[node.name]	当节点正在活跃地流式传输时，包含到达的 Token
stream.values[node.stateKey]	当节点完成后，包含最终的已提交输出

模式是：为实时更新显示流式内容，节点完成后回退到已提交的状态值。

for (const node of PIPELINE_NODES) {
  const status = getNodeStatus(node, streamingContent, stream.values);

  const content =
    status === "streaming"
      ? streamingContent[node.name]
      : stream.values?.[node.stateKey];
}

流式内容可能包含部分 Token 或尚未完全形成的 markdown。如果你渲染 markdown，请确保你的渲染器能优雅地处理不完整的语法（例如，未关闭的粗体标记 **）。

完整组合

以下是将路由、状态检测和卡片渲染组合在一起的完整卡片列表：

function NodeCardList({
  nodes,
  messages,
  values,
  getMetadata,
}: {
  nodes: typeof PIPELINE_NODES;
  messages: BaseMessage[];
  values: Record<string, unknown>;
  getMetadata: (msg: BaseMessage) => MessageMetadata | undefined;
}) {
  const streamingContent = getStreamingContent(messages, getMetadata);

  return (
    <div className="space-y-3">
      {nodes.map((node) => {
        const status = getNodeStatus(node, streamingContent, values);
        return (
          <NodeCard
            key={node.name}
            node={node}
            status={status}
            streamingContent={streamingContent[node.name]}
            completedContent={values?.[node.stateKey]}
          />
        );
      })}
    </div>
  );
}

使用场景

图执行卡片适用于任何需要可见性的多步骤管道：

• 研究管道：分类 -> 收集来源 -> 分析 -> 综合报告
• 内容生成：大纲 -> 草稿 -> 事实核查 -> 编辑 -> 发布
• 数据处理：摄入 -> 验证 -> 转换 -> 聚合 -> 导出
• 代码生成：理解需求 -> 规划架构 -> 编写代码 -> 审核 -> 测试
• 决策工作流：收集上下文 -> 评估选项 -> 评分替代方案 -> 推荐

处理动态管道

并非所有图都有固定的节点集。有些管道会根据输入添加或跳过节点。通过检查哪些状态键实际有值来处理这种情况：

const activeNodes = PIPELINE_NODES.filter(
  (node) =>
    streamingContent[node.name] ||
    values?.[node.stateKey] ||
    node.name === currentNode
);

这确保你的 UI 只显示与当前执行相关的节点卡片，避免空的占位卡片。

如果你的图有条件分支（例如，对于简单的事实性查询跳过”研究”），被跳过的节点不会出现在流式内容或状态值中。你的管道进度条应通过暗化或隐藏被跳过的步骤来反映这一点。

最佳实践

• 声明式定义节点。将你的 PIPELINE_NODES 数组作为单一真相来源，映射节点名称、状态键和显示标签。
• 对活跃节点优先使用流式内容。它给用户即时反馈。仅在节点完成后回退到已提交的状态值。
• 自动折叠已完成节点。在长管道中，自动折叠完成的卡片，让用户可以专注于当前活跃的步骤。
• 显示预估时间。如果你有关于每个节点需要多长时间的历史数据，显示时间估计以设定用户预期。
• 添加全局进度指示器。在管道视图顶部用整体进度条（例如”第 2 步，共 4 步”）补充每个节点的卡片。
• 按节点处理错误。如果某个节点失败，在其卡片中显示错误，而不是折叠整个管道。其他节点可能仍然成功完成。

---

通过 MCP 连接这些文档到 Claude、VSCode 等工具，获取实时答案。

在 GitHub 上编辑此页面或提交问题。