Liam 项目 LangGraph.js 流式输出实战指南:从 Stream Modes 到 Token 级与自定义事件流

原创2026-09-17 15:13:271,952 阅读
文章标签:数据可视化前端开发工具CLI数据库人工智能AI AgentMCP 服务

Liam 项目 LangGraph.js 流式输出实战指南:从 Stream Modes 到 Token 级与自定义事件流

Liam 是一个从数据库自动生成 ER 图的开源工具,其 Agent 工作流(frontend/internal-packages/agent)基于 LangGraph.js 构建,覆盖需求分析、Schema 设计与测试用例生成等多个阶段。在交互式场景中,Agent 的输出必须以"流"的方式逐步呈现给用户,本指南以 docs/langgraph/streaming.md 为核心骨架,系统讲解 LangGraph.js 的四种流式能力:State 级 Stream Modes、Token 级流式输出、自定义数据流,以及从工具与节点内部发起的事件流,并结合 Liam 仓库的真实实现说明生产环境中的落地方式。

读完本文,你将掌握 app.stream() 与 app.streamEvents() 的完整用法、values/updates/messages 等流模式的取舍、dispatchCustomEvent 与 config.writer 两种自定义数据通道,以及如何通过 tags 精准过滤来自特定工具或最终节点的 Token 流。

一、LangGraph 流式输出的整体图景

LangGraph 把"流式"分为两个层次:

  • 状态流(State Stream):通过 graph.stream() 按节点执行顺序逐步产出图的 State 或其增量更新,粒度是"节点级"。
  • 事件流(Event Stream):通过 graph.streamEvents() 暴露 LangChain Runnable 内部的细粒度事件(如 LLM 的每个 token 分片),粒度是"事件级"。

两者的核心区别可以概括为:stream 让你看到"图走到哪一步",streamEvents 让你看到"某一步内部发生了什么"。Liam 的 deepModelingStream.ts 正是把二者组合使用的范例——它以 streamEvents 消费消息级事件,再从事件流中过滤出自定义事件转发给前端。

在深入细节前,先说明流式功能所依赖的基础图结构。文档用 MessagesAnnotation 定义一个"消息累加"的 State,这也是大多数对话型 Agent 的默认状态定义:

import { Annotation, START } from "@langchain/langgraph";
import { BaseMessage } from "@langchain/core/messages";

const StateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({
    reducer: (x, y) => x.concat(y),
  }),
});

reducer: (x, y) => x.concat(y) 表示每个节点返回的消息都会追加到现有消息列表尾部,这是状态管理中"合并更新"的标准写法,详见 state-management.md。

二、Stream Modes:values、updates 与多模式组合

2.1 基础图定义

下面的示例构建一个带天气工具的 ReAct 风格 Agent:agent 节点调用模型,模型返回 tool_calls 时路由到 tools 节点执行工具,否则走向 END。

// process.env.OPENAI_API_KEY = "sk-...";

import { END, START, StateGraph, MessagesAnnotation } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import * as v from "valibot";
import { tool } from "@langchain/core/tools";
import { toJsonSchema } from "@valibot/to-json-schema";
import { AIMessage, HumanMessage } from "@langchain/core/messages";

const getWeather = tool(
  async ({ city }) => {
    if (city === "nyc") {
      return "It might be cloudy in nyc";
    } else if (city === "sf") {
      return "It's always sunny in sf";
    } else {
      throw new Error("Unknown city.");
    }
  },
  {
    name: "get_weather",
    description: "Use this to get weather information",
    schema: toJsonSchema(v.object({
      city: v.picklist(["nyc", "sf"]),
    })),
  }
);

const tools = [getWeather];
const toolNode = new ToolNode(tools);

const model = new ChatOpenAI({ model: "gpt-4o" }).bindTools(tools);

const shouldContinue = (state: typeof MessagesAnnotation.State) => {
  const messages = state.messages;
  const lastMessage = messages[messages.length - 1] as AIMessage;

  if (lastMessage.tool_calls?.length) {
    return "tools";
  }
  return END;
};

const callModel = async (state: typeof MessagesAnnotation.State) => {
  const messages = state.messages;
  const response = await model.invoke(messages);
  return { messages: [response] };
};

const workflow = new StateGraph(MessagesAnnotation)
  .addNode("agent", callModel)
  .addNode("tools", toolNode)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", shouldContinue)
  .addEdge("tools", "agent");

const app = workflow.compile();

注意:条件路由用 addConditionalEdges("agent", shouldContinue),返回值 "tools" 或 END 决定下一跳,这是 control-flow.md 中"条件路由"模式的直接应用。

2.2 values 模式:流式输出图的完整状态

streamMode: "values" 会在每个节点执行完成后推送一次图的完整 State。也就是说,每次输出都包含到目前为止全部消息、全部累积字段,适合需要"快照式"展示的客户端:

const inputs = { messages: [new HumanMessage("what is the weather in sf")] };
for await (const output of await app.stream(inputs, {
  streamMode: "values",
})) {
  console.log("Full state:", output);
}

由于每次输出都是全量 State,客户端只需"整体覆盖"即可渲染最新状态,实现最简单,但数据冗余也最大——消息越长,单次负载越大。

2.3 updates 模式:只流式输出状态的增量

streamMode: "updates" 只推送每个节点返回的那部分状态更新(即节点 return 的字段),而非全量 State。输出结构为 { 节点名: 该节点的更新 }:

const inputs = { messages: [new HumanMessage("what is the weather in sf")] };
for await (const output of await app.stream(inputs, {
  streamMode: "updates",
})) {
  console.log("Node updates:", output);
}

例如 agent 节点返回 { messages: [response] },则 output 形如 { agent: { messages: [AIMessage...] } }。这种模式带宽效率更高,前端可以针对"哪个节点产生了什么更新"做差异化处理。

2.4 同时启用多个流模式

LangGraph 允许一次配置多个模式,输出为数组,元素顺序与 streamMode 数组一致:

const inputs = { messages: [new HumanMessage("what is the weather in sf")] };
for await (const output of await app.stream(inputs, {
  streamMode: ["values", "updates"],
})) {
  console.log("Combined stream:", output);
}

例如 output[0] 是 values 快照、output[1] 是 updates 增量,两者可在同一轮迭代中一并消费。在实际产品中,这种组合常用于"一边增量渲染、一边保留全量快照用于回放"。

三、Token 级流式:streamEvents 与 on_chat_model_stream

节点级 State 流粒度太粗,无法实现"打字机"效果。LangGraph 的 streamEvents(inputs, { version: "v2" }) 可以把 LLM 产生的每个 token 分片(chunk)实时吐出来。事件协议 v2 是当前推荐版本,返回的每条记录包含 event 名称与 data 载荷。

沿用 2.1 的图(模型换成 gpt-4o-mini 亦可),Token 级流式代码如下:

const inputs = { messages: [new HumanMessage("what is the weather in sf")] };
const eventStream = await app.streamEvents(inputs, { version: "v2" });

for await (const { event, data } of eventStream) {
  if (event === "on_chat_model_stream") {
    console.log(data.chunk.content);
  }
}

其中 on_chat_model_stream 是"聊天模型正在产生新 token"的事件名,data.chunk.content 是单个 token 分片的内容,逐个拼接即得到完整回复。

Liam 的落地证据:Liam 的流式实现没有逐行手写这套样板,而是把相关配置收敛到 setupStreamOptions.ts,其中关键设置包括:

  • streamMode: 'messages':与文档示例的 "values"/"updates" 同属一组,但更细——它以"消息"为单位流式输出,适合长对话场景;
  • version: 'v2':使用 v2 事件协议;
  • subgraphs: true:允许子图内部的事件穿透到主事件流(Liam 的 Agent 由 lead/pm/db/qa 等多个子图组成);
  • signal:传入 AbortSignal,支持前端中断时取消整个流;
  • callbacks: [runCollector]:通过 RunCollectorCallbackHandler 收集运行轨迹,用于追踪与回放。

而 deepModelingStream.ts 则在拿到事件流后做了一层关键过滤——只转发 on_custom_event:

async function* iter() {
  for await (const ev of stream) {
    if (ev.event === 'on_custom_event') {
      yield {
        event: ev.name,
        data: [ev.data, ev.metadata],
      }
    }
  }
}

这意味着 Liam 的产品层并不直接消费原始 LLM token 事件,而是把"自定义事件"作为与前端通信的统一协议,Token 级内容在节点内部被整理成结构化事件后再上抛。这与本文第四节的自定义数据流一脉相承。

四、自定义数据流:config.writer 与 dispatchCustomEvent

不是所有需要流式呈现的内容都来自 LLM token。例如:一个耗时的工具调用,你可能想先给用户推送"正在执行步骤 1/3"之类的进度提示;一个数据库 Schema 生成任务,你可能想实时推送"已提取 5 张表"。LangGraph 提供两种自定义数据通道。

4.1 方式一:graph.stream + streamMode: "custom"

在节点内部通过 config.writer 写入任意数据,消费端以 streamMode: "custom" 读取。节点签名需要接收 config: RunnableConfig:

import { END, StateGraph, MessagesAnnotation } from "@langchain/langgraph";
import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
import type { RunnableConfig } from "@langchain/core/runnables";
import { HumanMessage } from "@langchain/core/messages";

const myNode = async (
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig
) => {
  console.log("--- Node 1 ---");
  return { messages: state.messages };
};

const myOtherNode = async (
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig
) => {
  console.log("--- Node 2 ---");

  // Use the config.writer to write custom data to the stream
  config.writer?.({
    myCustomData: "some_value",
    moreCustomData: "some_other_value",
  });

  return { messages: state.messages };
};

const graph = new StateGraph(MessagesAnnotation)
  .addNode("myNode", myNode)
  .addNode("myOtherNode", myOtherNode)
  .addEdge(START, "myNode")
  .addEdge("myNode", "myOtherNode")
  .addEdge("myOtherNode", END)
  .compile();

消费端:

const inputs = { messages: [new HumanMessage("hello world")] };

for await (const chunk of await graph.stream(inputs, {
  streamMode: "custom",
})) {
  console.log(chunk);
}

config.writer 是可选的(?.),因为它只在这个节点被"流式上下文"调用时才存在。每调用一次 config.writer(data),消费端就会收到一条 data。

4.2 方式二:dispatchCustomEvent + streamEvents

另一种方式是使用 dispatchCustomEvent 主动派发命名事件,并通过 streamEvents 监听 on_custom_event。这样事件可以带 name,消费端按名字分类处理,语义更清晰:

const myNodeWithEvents = async (
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig
) => {
  console.log("--- Node 1 ---");

  await dispatchCustomEvent("my_custom_event", {
    message: "hello from node 1",
  }, config);

  return { messages: state.messages };
};

const myOtherNodeWithEvents = async (
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig
) => {
  console.log("--- Node 2 ---");

  await dispatchCustomEvent("my_custom_event", {
    message: "hello from node 2",
  }, config);

  return { messages: state.messages };
};

const graphWithEvents = new StateGraph(MessagesAnnotation)
  .addNode("myNode", myNodeWithEvents)
  .addNode("myOtherNode", myOtherNodeWithEvents)
  .addEdge(START, "myNode")
  .addEdge("myNode", "myOtherNode")
  .addEdge("myOtherNode", END)
  .compile();
const inputs = { messages: [new HumanMessage("hello world")] };
const eventStream = await graphWithEvents.streamEvents(inputs, { version: "v2" });

for await (const { event, data } of eventStream) {
  if (event === "on_custom_event") {
    console.log(data);
  }
}

两种方式的差异与选择:

维度 config.writer + streamMode: "custom" dispatchCustomEvent + streamEvents
使用场景 只想流出自定义数据的简单场景 需要同时监听 LLM token 事件与自定义事件的复杂场景
事件命名 无,直接透传数据 带 name,可按事件名分流
与 token 流的结合 不能与其他模式之外的语义混流 可与 on_chat_model_stream 等事件统一消费

Liam 的落地证据:Liam 正是选择"命名事件"路线。在 deepModelingStream.ts 中,事件流只保留 on_custom_event,并把 ev.name 提升为对外事件的 event 字段。更通用的封装见 customEventIterator.ts:它接受任意 AsyncIterable 事件流,过滤出 event === 'on_custom_event' && ev.name 的记录,归一化为 { event, data: <a href="https://link.gitcode.com/i/9c2a61b3f7132204a5f8bcd8f55a3b34" target="_blank">ev.data, ev.metadata] }。metadata 一并透传,是因为 Liam 用它携带 thread_id 等会话上下文。事件命名常量集中在 [constants.ts,定义了 messages、end、error、analyzed_requirements 四类 SSE 事件,其中 analyzed_requirements 即由 PM Agent 的分析节点通过自定义事件推送。

五、从工具与节点内部流式输出

5.1 在工具内部流式输出底层 Runnable 的事件

当工具内部调用了另一个 LLM 或 LCEL 链(乃至其他图、检索器)时,默认情况下这些内部事件不会自动冒泡到顶层。解决办法是给工具内部的调用打上 tags,再用 includeTags 过滤:

import * as v from "valibot";
import { tool } from "@langchain/core/tools";
import { toJsonSchema } from "@valibot/to-json-schema";
import { ChatAnthropic } from "@langchain/anthropic";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const getItems = tool(
  async (input, config) => {
    const template = ChatPromptTemplate.fromMessages([
      ["human", "{input}"]
    ]);

    const model = new ChatAnthropic({
      model: "claude-3-5-sonnet-20240620",
      temperature: 0,
    });

    const chain = template.pipe(model);

    const response = await chain.invoke(
      { input: input.input },
      { ...config, tags: ["my_tool"] }
    );

    return response.content;
  },
  {
    name: "get_items",
    description: "Get items from the database",
    schema: toJsonSchema(v.object({
      input: v.string(),
    })),
  }
);

const tools = [getItems];

const model = new ChatAnthropic({
  model: "claude-3-5-sonnet-20240620",
  temperature: 0,
});

const graph = createReactAgent({ llm: model, tools });

注意第 338-340 行:chain.invoke(..., { ...config, tags: ["my_tool"] }) 中 ...config 是关键——它把外部的运行配置(包括 run id 与追踪上下文)透传给内部链,保证事件冒泡链路完整;tags: ["my_tool"] 则给这条内部链打上标记,供外层过滤:

import { HumanMessage } from "@langchain/core/messages";

const inputs = { messages: [new HumanMessage("get some items")] };
const eventStream = await graph.streamEvents(inputs, {
  version: "v2",
  includeTags: ["my_tool"]
});

for await (const { event, data } of eventStream) {
  if (event === "on_chat_model_stream") {
    console.log(data.chunk.content);
  }
}

includeTags: ["my_tool"] 表示"只返回携带该 tag 的事件",于是工具内部的 token 流被单独剥离出来。

提示:上面的示例为了演示从工具内部流式输出,使用了预构建的 createReactAgent。但在 Liam 项目中,团队在 docs/langgraph/README.md 中明确禁止使用 createReactAgent——它把 Prompt 工程封装成黑盒,违背 12-factor-agents 中"Own Your Prompts"的原则。Liam 全部用 StateGraph 底层原语手工构建 Agent,因此本文其他示例也以 StateGraph 为准。

5.2 只从最终节点流式输出

一个常见诉求是:多轮工具调用的中间过程不必逐 token 展示,只在最终回答节点启用流式。实现思路是给最终模型打上专属 tag,然后按 tag 过滤事件。先定义两个模型:model 负责正常的 agent 推理,finalModel 加 tags: ["final_node"] 负责最终润色输出:

import * as v from "valibot";
import { tool } from "@langchain/core/tools";
import { toJsonSchema } from "@valibot/to-json-schema";
import { ChatAnthropic } from "@langchain/anthropic";

const getWeather = tool(async ({ city }) => {
  if (city === "nyc") {
    return "It might be cloudy in nyc";
  } else if (city === "sf") {
    return "It's always sunny in sf";
  } else {
    throw new Error("Unknown city.");
  }
}, {
  name: "get_weather",
  schema: toJsonSchema(v.object({
    city: v.picklist(["nyc", "sf"]),
  })),
  description: "Use this to get weather information",
});

const tools = [getWeather];

const model = new ChatAnthropic({
  model: "claude-3-5-sonnet-20240620",
}).bindTools(tools);

const finalModel = new ChatAnthropic({
  model: "claude-3-5-sonnet-20240620",
}).withConfig({
  tags: ["final_node"],
});

图中新增 final 节点,条件路由在"有 tool_calls 走 tools、否则走 final"之间切换:

import { END, StateGraph, MessagesAnnotation } from "@langchain/langgraph";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import { AIMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";

const shouldContinue = async (state: typeof MessagesAnnotation.State) => {
  const messages = state.messages;
  const lastMessage: AIMessage = messages[messages.length - 1];

  if (lastMessage.tool_calls?.length) {
    return "tools";
  }
  return "final";
};

const callModel = async (state: typeof MessagesAnnotation.State) => {
  const messages = state.messages;
  const response = await model.invoke(messages);
  return { messages: [response] };
};

const callFinalModel = async (state: typeof MessagesAnnotation.State) => {
  const messages = state.messages;
  const lastAIMessage = messages[messages.length - 1];

  const response = await finalModel.invoke([
    new SystemMessage("Rewrite this in the voice of Al Roker"),
    new HumanMessage({ content: lastAIMessage.content })
  ]);

  response.id = lastAIMessage.id;
  return { messages: [response] };
};

const toolNode = new ToolNode<typeof MessagesAnnotation.State>(tools);

const graph = new StateGraph(MessagesAnnotation)
  .addNode("agent", callModel)
  .addNode("tools", toolNode)
  .addNode("final", callFinalModel)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", shouldContinue, {
    tools: "tools",
    final: "final",
  })
  .addEdge("tools", "agent")
  .addEdge("final", END)
  .compile();

消费端在事件解构中多取一个 tags 字段,只有当事件属于 final_node 时才输出 token 内容:

const inputs = { messages: [new HumanMessage("What's the weather in nyc?")] };
const eventStream = await graph.streamEvents(inputs, { version: "v2" });

for await (const { event, tags, data } of eventStream) {
  if (event === "on_chat_model_stream" && tags.includes("final_node")) {
    if (data.chunk.content) {
      console.log(data.chunk.content, "|");
    }
  }
}

注意 callFinalModel 中的 response.id = lastAIMessage.id:把最终回复的 message id 对齐到上一轮 AI 消息,这样 MessagesAnnotation 的 reducer 会将其视为对同一消息的更新而非新增,前端流式拼接时不会出现重复气泡。addConditionalEdges 的第三个参数 { tools: "tools", final: "final" } 是路由映射表,把返回值映射到具体节点,完整写法参见 control-flow.md。

六、Liam 中的生产级流式架构参考

把文档中的能力放回 Liam 的实际工程,可以梳理出如下分层:

  1. 入口层:deepModelingStream.ts 与 deepModeling.ts 并存——前者走 streamEvents 返回异步生成器供流式消费,后者走 executeWorkflowWithTracking 一次性执行完毕,二者共享 createGraph 与 setupWorkflowState,业务逻辑零重复。
  2. 配置层:setupStreamOptions.ts 统一组装 streamEvents 的全部选项(recursionLimit、configurable、callbacks、tags、metadata、streamMode、version、signal、runId、subgraphs),并把 organizationId、designSessionId、userId 写入 metadata 与 tags,供观测与追溯。
  3. 事件规整层:customEventIterator.ts 把原始事件流过滤、重命名、归一化,形成稳定的对外协议。
  4. 展示层:handlers.ts 按消息类型分流渲染——handleReasoningMessage 用"增量 diff"(currentText.slice(lastText.length))流式输出灰色斜体的推理过程,handleRegularMessage 增量输出正文,handleToolCallMessage 只在出现新的 tool call 时打印 🔧 toolName(args)。其 diff 思路与文档中"按 message id 维护已输出内容、只取增量"的模式一致,是实现无重复流式 UI 的通用手法。

Liam 对"增量 diff"的处理值得单独强调:三类 handler 都维护 Map<messageId, 已输出内容>,每次从完整内容中切出新增片段。这对应文档中"token 分片按序拼接"思想的工程化版本——即使底层事件乱序或重复,前端也能保证渲染不重不漏。

此外,仓库的集成测试(如 createGraph.integration.test.ts、analyzeRequirementsNode.integration.test.ts)大量出现 streamMode 与自定义事件的断言,说明"流式行为"已被纳入 CI 回归范围,读者可在这些测试中看到 streamEvents/dispatchCustomEvent 更丰富的组合用法。

七、小结与选型建议

回到文档的脉络,LangGraph.js 的流式能力可以按需求梯度选择:

  • 需要"节点级快照"、实现最简单 → streamMode: "values";
  • 需要"节点级增量"、节省带宽 → streamMode: "updates";
  • 需要"打字机"效果 → streamEvents(..., { version: "v2" }) + on_chat_model_stream;
  • 需要推送进度、结构化中间产物 → config.writer + streamMode: "custom" 或 dispatchCustomEvent + on_custom_event(推荐后者,可携带事件名);
  • 需要只展示最终回答、隐藏中间推理 → 最终模型打 tag + 消费端按 tag 过滤。

在 Liam 中,最终的选择是:streamEvents(v2、messages 模式、subgraphs 开启)为底层通道,dispatchCustomEvent 派发命名事件,customEventIterator 归一化对外协议,handlers.ts 按消息类型做增量渲染。这一整套模式可以作为 LangGraph.js 生产级流式应用的直接参考。

若需进一步了解流式所需的前置知识,建议按顺序阅读 core-concepts.md(图与状态)、state-management.md(reducer 与持久化)、control-flow.md(条件路由与循环),以及 tool-calling.md(ToolNode 与工具状态更新);有关子图与递归限制等与流式配置密切相关的进阶话题,见 advanced-features.md。

登录后查看全文
liam