消息 - Docs by LangChain

消息是 LangChain 中模型上下文的基本单元。它们表示模型的输入和输出，携带与大语言模型(LLM)交互时表示对话状态所需的内容和元数据。消息是包含以下内容的对象：

角色 - 标识消息类型（例如 system、user）
内容 - 表示消息的实际内容（如文本、图片、音频、文档等）
元数据 - 可选字段，如响应信息、消息 ID 和 Token 用量

LangChain 提供了一种跨所有模型提供商通用的标准消息类型，确保无论调用哪个模型都能保持一致的行为。

基本用法

使用消息最简单的方式是创建消息对象，并在调用模型时传递它们。

import { initChatModel, HumanMessage, SystemMessage } from "langchain";

const model = await initChatModel("gpt-5-nano");

const systemMsg = new SystemMessage("You are a helpful assistant.");
const humanMsg = new HumanMessage("Hello, how are you?");

const messages = [systemMsg, humanMsg];
const response = await model.invoke(messages);  // 返回 AIMessage

文本提示词

文本提示词是字符串——适用于不需要保留对话历史的简单生成任务。

const response = await model.invoke("Write a haiku about spring");

在以下情况使用文本提示词：

你有一个单独的独立请求
你不需要对话历史
你希望代码复杂度最低

消息提示词

另外，你可以通过提供消息对象列表来向模型传递消息列表。

import { SystemMessage, HumanMessage, AIMessage } from "langchain";

const messages = [
  new SystemMessage("You are a poetry expert"),
  new HumanMessage("Write a haiku about spring"),
  new AIMessage("Cherry blossoms bloom..."),
];
const response = await model.invoke(messages);

在以下情况使用消息提示词：

管理多轮对话
处理多模态内容（图片、音频、文件）
包含系统指令

字典格式

你也可以直接使用 OpenAI 聊天补全格式来指定消息。

const messages = [
  { role: "system", content: "You are a poetry expert" },
  { role: "user", content: "Write a haiku about spring" },
  { role: "assistant", content: "Cherry blossoms bloom..." },
];
const response = await model.invoke(messages);

消息类型

系统消息 - 告诉模型如何行为并为交互提供上下文
人类消息 - 表示用户输入和与模型的交互
AI 消息 - 模型生成的响应，包括文本内容、工具调用和元数据
工具消息 - 表示工具调用的输出

系统消息

SystemMessage 表示一组初始指令，用于引导模型的行为。你可以使用系统消息来设定语气、定义模型角色，并建立响应准则。

基本指令

import { SystemMessage, HumanMessage, AIMessage } from "langchain";

const systemMsg = new SystemMessage("You are a helpful coding assistant.");

const messages = [
  systemMsg,
  new HumanMessage("How do I create a REST API?"),
];
const response = await model.invoke(messages);

详细角色设定

import { SystemMessage, HumanMessage } from "langchain";

const systemMsg = new SystemMessage(`
You are a senior TypeScript developer with expertise in web frameworks.
Always provide code examples and explain your reasoning.
Be concise but thorough in your explanations.
`);

const messages = [
  systemMsg,
  new HumanMessage("How do I create a REST API?"),
];
const response = await model.invoke(messages);

人类消息

HumanMessage 表示用户输入和交互。它们可以包含文本、图片、音频、文件以及任何多模态内容。

文本内容

消息对象

const response = await model.invoke([
  new HumanMessage("What is machine learning?"),
]);

字符串快捷方式

const response = await model.invoke("What is machine learning?");

消息元数据

添加元数据

const humanMsg = new HumanMessage({
  content: "Hello!",
  name: "alice",
  id: "msg_123",
});

name 字段的行为因提供商而异——有些使用它进行用户识别，有些则忽略它。要查看具体行为，请参阅模型提供商的参考文档。

AI 消息

AIMessage 表示模型调用的输出。它们可以包含多模态数据、工具调用和提供商特定的元数据，你可以在之后访问这些数据。

const response = await model.invoke("Explain AI");
console.log(typeof response);  // AIMessage

AIMessage 对象在调用模型时返回，其中包含响应中所有关联的元数据。不同的提供商对消息类型的权重/上下文化方式不同，这意味着手动创建一个新的 AIMessage 对象并将其插入消息历史中（就像它来自模型一样）有时是有帮助的。

import { AIMessage, SystemMessage, HumanMessage } from "langchain";

const aiMsg = new AIMessage("I'd be happy to help you with that question!");

const messages = [
  new SystemMessage("You are a helpful assistant"),
  new HumanMessage("Can you help me?"),
  aiMsg,  // 插入，就像它来自模型一样
  new HumanMessage("Great! What's 2+2?")
]

const response = await model.invoke(messages);

属性

text

string

消息的文本内容。

content

string | ContentBlock[]

消息的原始内容。

content_blocks

ContentBlock.Standard[]

消息的标准化内容块。（参见内容）

tool_calls

ToolCall[] | None

模型发起的工具调用。如果没有调用工具则为空。

string

消息的唯一标识符（由 LangChain 自动生成或在提供商响应中返回）

usage_metadata

UsageMetadata | None

消息的使用元数据，可用时包含 Token 计数。参见 UsageMetadata。

response_metadata

ResponseMetadata | None

消息的响应元数据。

工具调用

当模型进行工具调用时，它们被包含在 AIMessage 中：

const modelWithTools = model.bindTools([getWeather]);
const response = await modelWithTools.invoke("What's the weather in Paris?");

for (const toolCall of response.tool_calls) {
  console.log(`Tool: ${toolCall.name}`);
  console.log(`Args: ${toolCall.args}`);
  console.log(`ID: ${toolCall.id}`);
}

其他结构化数据，如推理过程或引用，也可以出现在消息内容中。

Token 用量

AIMessage 可以在其 usage_metadata 字段中保存 Token 计数和其他使用元数据：

import { initChatModel } from "langchain";

const model = await initChatModel("gpt-5-nano");

const response = await model.invoke("Hello!");
console.log(response.usage_metadata);

{
  "output_tokens": 304,
  "input_tokens": 8,
  "total_tokens": 312,
  "input_token_details": {
    "cache_read": 0
  },
  "output_token_details": {
    "reasoning": 256
  }
}

参见 UsageMetadata 了解详情。

流式输出和块

在流式输出期间，你将收到 AIMessageChunk 对象，这些对象可以合并为完整的消息对象：

import { AIMessageChunk } from "langchain";

let finalChunk: AIMessageChunk | undefined;
for (const chunk of chunks) {
  finalChunk = finalChunk ? finalChunk.concat(chunk) : chunk;
}

了解更多：

工具消息

对于支持工具调用的模型，AI 消息可以包含工具调用。工具消息用于将单个工具执行的结果传递回模型。工具可以直接生成 ToolMessage 对象。下面展示一个简单示例。更多内容请阅读工具指南。

import { AIMessage, ToolMessage } from "langchain";

const aiMessage = new AIMessage({
  content: [],
  tool_calls: [{
    name: "get_weather",
    args: { location: "San Francisco" },
    id: "call_123"
  }]
});

const toolMessage = new ToolMessage({
  content: "Sunny, 72°F",
  tool_call_id: "call_123"
});

const messages = [
  new HumanMessage("What's the weather in San Francisco?"),
  aiMessage,  // 模型的工具调用
  toolMessage,  // 工具执行结果
];

const response = await model.invoke(messages);  // 模型处理结果

属性

content

string

required

工具调用的字符串化输出。

tool_call_id

string

required

此消息所响应的工具调用 ID。必须与 AIMessage 中的工具调用 ID 匹配。

name

string

required

被调用的工具名称。

artifact

dict

不发送给模型但可以通过编程方式访问的附加数据。

artifact 字段存储不会发送给模型但可以通过编程方式访问的补充数据。这对于存储原始结果、调试信息或用于下游处理的数据非常有用，而不会污染模型的上下文。

示例：使用 artifact 存储检索元数据

例如，检索工具可以从文档中检索一段文本供模型参考。消息 content 包含模型将引用的文本，而 artifact 可以包含应用程序可以使用的文档标识符或其他元数据（例如用于渲染页面）。参见以下示例：

import { ToolMessage } from "langchain";

// artifact 可在下游使用
const artifact = { document_id: "doc_123", page: 0 };

const toolMessage = new ToolMessage({
  content: "It was the best of times, it was the worst of times.",
  tool_call_id: "call_123",
  name: "search_books",
  artifact
});

参见 RAG 教程了解使用 LangChain 构建检索智能体的端到端示例。

消息内容

你可以将消息的内容视为发送给模型的数据载荷。消息有一个 content 属性，它是松散类型的，支持字符串和无类型对象列表（例如字典）。这允许在 LangChain 聊天模型中直接支持提供商原生结构，例如多模态内容和其他数据。另外，LangChain 为文本、推理过程、引用、多模态数据、服务端工具调用和其他消息内容提供了专用内容类型。参见下面的内容块。 LangChain 聊天模型在 content 属性中接受消息内容。它可以包含以下任一类型：

字符串
提供商原生格式的内容块列表
LangChain 标准内容块列表

参见下面使用多模态输入的示例：

import { HumanMessage } from "langchain";

// 字符串内容
const humanMessage = new HumanMessage("Hello, how are you?");

// 提供商原生格式（例如 OpenAI）
const humanMessage = new HumanMessage({
  content: [
    { type: "text", text: "Hello, how are you?" },
    {
      type: "image_url",
      image_url: { url: "https://example.com/image.jpg" },
    },
  ],
});

// 标准内容块列表
const humanMessage = new HumanMessage({
  contentBlocks: [
    { type: "text", text: "Hello, how are you?" },
    { type: "image", url: "https://example.com/image.jpg" },
  ],
});

标准内容块

LangChain 提供了一种跨提供商通用的消息内容标准表示。消息对象实现了一个 contentBlocks 属性，它会惰性地将 content 属性解析为标准的、类型安全的表示。例如，从 ChatAnthropic 或 ChatOpenAI 生成的消息将包含各自提供商格式的 thinking 或 reasoning 块，但可以被惰性解析为一致的 ReasoningContentBlock 表示：

Anthropic
OpenAI

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

const message = new AIMessage({
  content: [
    {
      "type": "thinking",
      "thinking": "...",
      "signature": "WaUjzkyp...",
    },
    {
      "type":"text",
      "text": "...",
      "id": "msg_abc123",
    },
  ],
  response_metadata: { model_provider: "anthropic" },
});

console.log(message.contentBlocks);

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

const message = new AIMessage({
  content: [
    {
      "type": "reasoning",
      "id": "rs_abc123",
      "summary": [
        {"type": "summary_text", "text": "summary 1"},
        {"type": "summary_text", "text": "summary 2"},
      ],
    },
    {"type": "text", "text": "..."},
  ],
  response_metadata: { model_provider: "openai" },
});

console.log(message.contentBlocks);

参见集成指南开始使用你选择的推理提供商。

序列化标准内容如果 LangChain 之外的应用程序需要访问标准内容块表示，你可以选择将内容块存储在消息内容中。要实现这一点，你可以将 LC_OUTPUT_VERSION 环境变量设置为 v1。或者，使用 outputVersion: "v1" 初始化任何聊天模型：

import { initChatModel } from "langchain";

const model = await initChatModel(
  "gpt-5-nano",
  { outputVersion: "v1" }
);

多模态

多模态 指的是处理不同形式数据的能力，例如文本、音频、图片和视频。LangChain 包含这些数据的标准类型，可以跨提供商使用。聊天模型可以接受多模态数据作为输入并将其作为输出生成。下面展示包含多模态数据的输入消息的简短示例。

额外的键可以放在内容块的顶层或嵌套在 "extras": {"key": value} 中。例如，OpenAI 和 AWS Bedrock Converse 要求 PDF 文件提供文件名。有关具体信息，请参阅你选择的模型的提供商页面。

// 从 URL
const message = new HumanMessage({
  content: [
    { type: "text", text: "Describe the content of this image." },
    {
      type: "image",
      source_type: "url",
      url: "https://example.com/path/to/image.jpg"
    },
  ],
});

// 从 base64 数据
const message = new HumanMessage({
  content: [
    { type: "text", text: "Describe the content of this image." },
    {
      type: "image",
      source_type: "base64",
      data: "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
    },
  ],
});

// 从提供商管理的文件 ID
const message = new HumanMessage({
  content: [
    { type: "text", text: "Describe the content of this image." },
    { type: "image", source_type: "id", id: "file-abc123" },
  ],
});

并非所有模型都支持所有文件类型。请查看模型提供商的参考文档了解支持的格式和大小限制。

内容块参考

内容块表示为类型化对象的列表（无论是创建消息还是访问 contentBlocks 字段时）。列表中的每个项目必须符合以下块类型之一：

核心

ContentBlock.Text

用途： 标准文本输出

type

string

required

始终为 "text"

text

string

required

文本内容

annotations

Citation[]

文本的注释列表

示例：

{
    type: "text",
    text: "Hello world",
    annotations: []
}

ContentBlock.Reasoning

用途： 模型推理步骤

type

string

required

始终为 "reasoning"

reasoning

string

required

推理内容

示例：

{
    type: "reasoning",
    reasoning: "The user is asking about..."
}

多模态

ContentBlock.Multimodal.Image

用途： 图片数据

type

string

required

始终为 "image"

url

string

指向图片位置的 URL。

data

string

Base64 编码的图片数据。

fileId

string

外部文件存储系统中图片的引用（例如 OpenAI 或 Anthropic 的 Files API）。

mimeType

string

图片 MIME 类型（例如 image/jpeg、image/png）。base64 数据时必需。

ContentBlock.Multimodal.Audio

用途： 音频数据

type

string

required

始终为 "audio"

url

string

指向音频位置的 URL。

data

string

Base64 编码的音频数据。

fileId

string

外部文件存储系统中音频文件的引用（例如 OpenAI 或 Anthropic 的 Files API）。

mimeType

string

音频 MIME 类型（例如 audio/mpeg、audio/wav）。base64 数据时必需。

ContentBlock.Multimodal.Video

用途： 视频数据

type

string

required

始终为 "video"

url

string

指向视频位置的 URL。

data

string

Base64 编码的视频数据。

fileId

string

外部文件存储系统中视频文件的引用（例如 OpenAI 或 Anthropic 的 Files API）。

mimeType

string

视频 MIME 类型（例如 video/mp4、video/webm）。base64 数据时必需。

ContentBlock.Multimodal.File

用途： 通用文件（PDF 等）

type

string

required

始终为 "file"

url

string

指向文件位置的 URL。

data

string

Base64 编码的文件数据。

fileId

string

外部文件存储系统中文件的引用（例如 OpenAI 或 Anthropic 的 Files API）。

mimeType

string

文件 MIME 类型（例如 application/pdf）。base64 数据时必需。

ContentBlock.Multimodal.PlainText

用途： 文档文本（.txt、.md）

type

string

required

始终为 "text-plain"

text

string

required

文本内容

title

string

文本内容的标题

mimeType

string

文本的 MIME 类型（例如 text/plain、text/markdown）

工具调用

ContentBlock.Tools.ToolCall

用途： 函数调用

type

string

required

始终为 "tool_call"

name

string

required

要调用的工具名称

args

object

required

传递给工具的参数

string

required

此工具调用的唯一标识符

示例：

{
    type: "tool_call",
    name: "search",
    args: { query: "weather" },
    id: "call_123"
}

ContentBlock.Tools.ToolCallChunk

用途： 流式工具片段

type

string

required

始终为 "tool_call_chunk"

name

string

正在调用的工具名称

args

string

部分工具参数（可能是不完整的 JSON）

string

工具调用标识符

index

number | string

required

此块在流中的位置

ContentBlock.Tools.InvalidToolCall

用途： 格式错误的调用

type

string

required

始终为 "invalid_tool_call"

name

string

调用失败的工具名称

args

string

解析失败的原始参数

error

string

required

出错原因的描述

常见错误： 无效 JSON、缺少必需字段

服务端工具执行

ContentBlock.Tools.ServerToolCall

用途： 在服务端执行的工具调用。

type

string

required

始终为 "server_tool_call"

string

required

与工具调用关联的标识符。

name

string

required

要调用的工具名称。

args

string

required

部分工具参数（可能是不完整的 JSON）

ContentBlock.Tools.ServerToolCallChunk

用途： 流式服务端工具调用片段

type

string

required

始终为 "server_tool_call_chunk"

string

与工具调用关联的标识符。

name

string

正在调用的工具名称

args

string

部分工具参数（可能是不完整的 JSON）

index

number | string

此块在流中的位置

ContentBlock.Tools.ServerToolResult

用途： 搜索结果

type

string

required

始终为 "server_tool_result"

tool_call_id

string

required

对应的服务端工具调用的标识符。

string

与服务端工具结果关联的标识符。

status

string

required

服务端工具的执行状态。"success" 或 "error"。

output

已执行工具的输出。

提供商特定块

ContentBlock.NonStandard

用途： 提供商特定的兜底方案

type

string

required

始终为 "non_standard"

value

object

required

提供商特定的数据结构

用法： 用于实验性或提供商独有的功能

其他提供商特定的内容类型可以在每个模型提供商的参考文档中找到。

上述提到的每个内容块在导入 ContentBlock 类型时都可以作为独立类型单独引用。

import { ContentBlock } from "langchain";

// 文本块
const textBlock: ContentBlock.Text = {
    type: "text",
    text: "Hello world",
}

// 图片块
const imageBlock: ContentBlock.Multimodal.Image = {
    type: "image",
    url: "https://example.com/image.png",
    mimeType: "image/png",
}

在 API 参考中查看规范类型定义。

内容块作为消息的新属性在 LangChain v1 中引入，用于标准化跨提供商的内容格式，同时保持与现有代码的向后兼容性。内容块不是 content 属性的替代品，而是一个可用于以标准化格式访问消息内容的新属性。

与聊天模型配合使用

聊天模型接受消息对象序列作为输入，并返回 AIMessage 作为输出。交互通常是无状态的，因此简单的对话循环涉及使用不断增长的消息列表调用模型。参考以下指南了解更多：

持久化和管理对话历史的内置功能
管理上下文窗口的策略，包括裁剪和总结消息

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

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

Documentation Index

​基本用法

​文本提示词

​消息提示词

​字典格式

​消息类型

​系统消息

​人类消息

​文本内容

​消息元数据

​AI 消息

​工具调用

​Token 用量

​流式输出和块

​工具消息

​消息内容

​标准内容块

​多模态

​内容块参考

​与聊天模型配合使用

基本用法

文本提示词

消息提示词

字典格式

消息类型

系统消息

人类消息

文本内容

消息元数据

AI 消息

工具调用

Token 用量

流式输出和块

工具消息

消息内容

标准内容块

多模态

内容块参考

与聊天模型配合使用