消息 - LangChain LangGraph DeepAgent中文文档

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

Role (角色) - 标识消息类型（例如 system, user）
Content (内容) - 表示消息的实际内容（如文本、图像、音频、文件等）
Metadata (元数据) - 可选字段，例如响应信息、消息 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);  // Returns 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 表示一组初始指令，用于以此为基础设定模型的行为。您可以使用系统消息来设定基调、定义模型的角色并建立响应准则。

Basic instructions

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);

Detailed persona

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 表示用户输入和交互。它们可以包含文本、图像、音频、文件和任何其他数量的多模态内容。

文本内容

Message object

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

String shortcut

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

消息元数据

Add metadata

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,  // Insert as if it came from the model
  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,  // Model's tool call
  toolMessage,  // Tool execution result
];

const response = await model.invoke(messages);  // Model processes the result

属性

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 available downstream
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 构建检索 agents 的端到端示例。

消息内容

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

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

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

import { HumanMessage } from "langchain";

// String content
const humanMessage = new HumanMessage("Hello, how are you?");

// Provider-native format (e.g., OpenAI)
const humanMessage = new HumanMessage({
  content: [
    { type: "text", text: "Hello, how are you?" },
    {
      type: "image_url",
      image_url: { url: "https://example.com/image.jpg" },
    },
  ],
});

// List of standard content blocks
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" }
);

多模态

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

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

// From 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"
    },
  ],
});

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

// From provider-managed File ID
const message = new HumanMessage({
  content: [
    { type: "text", text: "Describe the content of this image." },
    { type: "image", source_type: "id", id: "file-abc123" },
  ],
});

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

内容块参考

内容块表示为（在创建消息或访问 contentBlocks 字段时）类型化对象列表。列表中的每一项都必须遵守以下块类型之一：

Core (核心)

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..."
}

Multimodal (多模态)

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)

Tool Calling (工具调用)

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，缺少必填字段

Server-Side Tool Execution (服务器端工具执行)

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

已执行工具的输出。

Provider-Specific Blocks (提供商特定块)

ContentBlock.NonStandard

用途： 提供商特定的逃生舱

type

string

required

始终为 "non_standard"

value

object

required

提供商特定的数据结构

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

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

上面提到的每个内容块在导入 ContentBlock 类型时都可以作为单独的类型进行寻址。

import { ContentBlock } from "langchain";

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

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

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

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

与聊天模型一起使用

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

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

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

将这些文档连接到 Claude、VSCode 等，通过 MCP 获得实时解答。

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

消息

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

人类消息

文本内容

消息元数据

AI 消息

工具调用

Token 使用

流式传输和块

工具消息

消息内容

标准内容块

多模态

内容块参考

与聊天模型一起使用

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

​基本用法

​文本提示

​消息提示

​字典格式

​消息类型

​系统消息

​人类消息

​文本内容

​消息元数据

​AI 消息

​工具调用

​Token 使用

​流式传输和块

​工具消息

​消息内容

​标准内容块

​多模态

​内容块参考

​与聊天模型一起使用

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

人类消息

文本内容

消息元数据

AI 消息

工具调用

Token 使用

流式传输和块

工具消息

消息内容

标准内容块

多模态

内容块参考

与聊天模型一起使用