事件流

LangChain 智能体基于 LangGraph 构建，因此支持相同的流式处理堆栈，并提供了针对智能体的、面向消息、工具调用、状态和自定义更新的投影。对于大多数应用和前端用例，请使用通过 stream_events(..., version="v3") 实现的事件流。事件流返回一个带有类型化投影的运行对象，因此每个投影可以独立消费，而无需解析流模式的元组。

import { createAgent, tool } from "langchain";
import * as z from "zod";

const getWeather = tool(
  async ({ city }) => `It's always sunny in ${city}!`,
  {
    name: "get_weather",
    description: "获取指定城市的天气。",
    schema: z.object({ city: z.string() }),
  }
);

const agent = createAgent({
  model: "gpt-5-nano",
  tools: [getWeather],
});

const stream = await agent.streamEvents(
  { messages: [{ role: "user", content: "旧金山的天气怎么样？" }] },
  { version: "v3" }
);

for await (const message of stream.messages) {
  for await (const delta of message.text) {
    process.stdout.write(delta);
  }
}

const finalState = await stream.output;

可流式传输的内容

投影	用途
`for event in stream`	带有完整信封的原始协议事件，可访问每个通道。
`stream.messages`	模型消息流，每次 LLM 调用一个流。
`message.text`	消息的文本增量和最终文本。
`message.reasoning`	对于暴露推理内容的模型，其推理过程的增量。
`message.toolCalls`	工具调用参数块和已确定的工具调用。
`message.output`	模型调用完成后的最终消息对象。
`message.usage`	当提供者返回时，令牌使用的元数据。
`stream.values`	智能体状态快照。
`stream.output`	最终智能体状态。
`stream.subgraphs`	嵌套图运行（子智能体和普通子图）。
`stream.extensions`	自定义转换器投影。
`stream.toolCalls`	工具执行生命周期、输入、输出增量、最终输出和错误。

stream.messages 生成消息流。每个消息流都暴露了 .text、.reasoning、.toolCalls、.output 和 .usage。异步投影可迭代以获取实时增量，或等待以获取最终值。

智能体消息

当你想要获取每次 LLM 调用的模型输出时，请使用 stream.messages。

const stream = await agent.streamEvents(input, { version: "v3" });

for await (const message of stream.messages) {
  process.stdout.write(`[${message.node}] `);
  for await (const delta of message.text) {
    process.stdout.write(delta);
  }

  const fullMessage = await message.output;
  console.log(fullMessage.content);

  const usage = await message.usage;
  if (usage) {
    console.log(usage);
  }
}

message.output 为你提供最终确定的 AI 消息，包括特定于提供者的内容块。在 TypeScript 中，当你只需要令牌计数或其他使用元数据时使用 message.usage；在 Python 中，从 message.output.usage_metadata 读取使用情况。

推理内容

推理内容使用与文本内容相同的形状，但仅当所选模型发出推理块时才可用。

const stream = await agent.streamEvents(input, { version: "v3" });

for await (const message of stream.messages) {
  for await (const delta of message.reasoning) {
    process.stdout.write(`[thinking] ${delta}`);
  }

  for await (const delta of message.text) {
    process.stdout.write(delta);
  }
}

有关模型配置详情，请参阅推理指南和你的提供者的集成页面。

工具调用

有两个有用的工具调用投影：

message.tool_calls 在模型生成工具调用时，流式传输工具调用参数块。
stream.tool_calls 在工具调用开始后，流式传输工具执行的生命周期。

const stream = await agent.streamEvents(input, { version: "v3" });

await Promise.all([
  (async () => {
    for await (const message of stream.messages) {
      for await (const chunk of message.toolCalls) {
        console.log("tool call chunk", chunk);
      }
    }
  })(),
  (async () => {
    for await (const call of stream.toolCalls) {
      console.log(call.name, call.input);
      console.log(await call.output, await call.error);
    }
  })(),
]);

流式传输子智能体

当一个 createAgent 调用（通常通过包装工具）调用另一个具名的 createAgent 时，内部智能体的事件会在嵌套的命名空间中流动。你传递给 createAgent 的 name 会在流中标识该内部智能体，因此你可以按智能体进行过滤和标记。具名子智能体出现在专用的 stream.subagents 投影上。每个句柄都暴露了内部智能体自己的 .messages、.toolCalls 和 .output，以及 .name（你传递的 name=）、.cause（调度子智能体的工具调用）和嵌套的 .subagents。因为只有具名的 createAgent 运行才会出现在这里，你不需要过滤掉普通子图。

import { createAgent, tool } from "langchain";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `It's always sunny in ${city}!`,
  { name: "get_weather", schema: z.object({ city: z.string() }) }
);

const weatherAgent = createAgent({
  model: "openai:gpt-5.5",
  tools: [getWeather],
  name: "weather_agent",
});

const callWeather = tool(
  async ({ query }) => {
    const result = await weatherAgent.invoke({
      messages: [{ role: "user", content: query }],
    });
    return result.messages.at(-1)?.text ?? "";
  },
  { name: "call_weather", schema: z.object({ query: z.string() }) }
);

const supervisor = createAgent({
  model: "openai:gpt-5.5",
  tools: [callWeather],
  name: "supervisor",
});

const stream = await supervisor.streamEvents(
  { messages: [{ role: "user", content: "波士顿的天气怎么样？" }] },
  { version: "v3" }
);

for await (const subagent of stream.subagents) {
  process.stdout.write(`${subagent.name}: `);
  for await (const message of subagent.messages) {
    for await (const token of message.text) {
      process.stdout.write(token);
    }
  }
  process.stdout.write("\n");
}
// 输出: "weather_agent: The weather in Boston is sunny!"

从工具调用的普通 StateGraph 子图也会出现在 stream.subgraphs 上——在 .compile(name=...) 上设置 name= 可以在 subagent.graph_name 中获得一个标签。 stream.subagents 是具名 createAgent 子智能体的聚焦视图，而 stream.subgraphs 覆盖了每个嵌套图。使用与你的 UI 匹配的那个。

状态与最终输出

使用 stream.values 获取状态快照，使用 stream.output 获取最终智能体状态。

const stream = await agent.streamEvents(input, { version: "v3" });

for await (const snapshot of stream.values) {
  console.log(snapshot);
}

const finalState = await stream.output;

多重投影

当你想在 JavaScript 中进行多重投影时，请使用并发消费者：

const stream = await agent.streamEvents(input, { version: "v3" });

await Promise.all([
  (async () => {
    for await (const message of stream.messages) {
      console.log(await message.text);
    }
  })(),
  (async () => {
    for await (const call of stream.toolCalls) {
      console.log(call.name, call.input);
    }
  })(),
]);

要访问未作为类型化投影暴露的通道，或检查完整的事件信封，请迭代原始协议事件：

for await (const event of stream) {
  console.log(event.method, event.params.namespace, event.params.data);
}

自定义更新

当你的应用需要内置投影之外的投影（如检索进度、制品或特定领域的事件）时，请使用自定义流转换器。

const stream = await agent.streamEvents(input, {
  version: "v3",
  transformers: [toolActivityTransformer],
});

for await (const activity of stream.extensions.toolActivity) {
  console.log(activity);
}

在中间件上注册转换器

中间件注册的转换器需要 langchain@1.4.3 或更高版本。

中间件可以在其钩子和工具旁边声明流转换器工厂。工厂的形状因语言而异：将 streamTransformers 作为工厂元组传递给 createMiddleware。每个工厂的形状是 () => StreamTransformer<any>（零参数），并且在每个作用域中调用一次。每次调用都返回一个新的转换器，可以保持每个子图隔离。

import { createAgent, createMiddleware } from "langchain";

const toolActivityMiddleware = createMiddleware({
  name: "ToolActivityMiddleware",
  streamTransformers: [toolActivityTransformer],
});

const agent = createAgent({
  model: "gpt-5-nano",
  tools: [getWeather],
  middleware: [toolActivityMiddleware],
});

在编译时，createAgent 将中间件注册的工厂与传递给其自身 streamTransformers 选项的任何内容合并。编译图上的最终顺序是：

内置的 ToolCallTransformer。
中间件注册的工厂，按中间件顺序。
调用者从 createAgent 提供的 streamTransformers。

这将内置的工具调用投影保持在消费者转换器的前面，并给予调用者提供的条目最终决定权。有关转换器契约，请参阅构建你自己的投影。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

可流式传输的内容

智能体消息

推理内容

工具调用

流式传输子智能体

状态与最终输出

多重投影

自定义更新

在中间件上注册转换器

相关内容

​可流式传输的内容

​智能体消息

​推理内容

​工具调用

​流式传输子智能体

​状态与最终输出

​多重投影

​自定义更新

​在中间件上注册转换器

​相关内容

可流式传输的内容

智能体消息

推理内容

工具调用

流式传输子智能体

状态与最终输出

多重投影

自定义更新

在中间件上注册转换器

相关内容