- Role:标识 message 类型,例如
system、user - Content:表示 message 的实际内容,例如文本、图像、音频、文档等
- Metadata:可选字段,例如响应信息、message IDs 和 token 用量
基本用法
使用 messages 最简单的方式,是创建 message 对象,并在 invoking 模型时将其传给模型。Text prompts
Text prompts 是字符串,适合不需要保留对话历史的简单生成任务。- 你有单个独立请求
- 你不需要对话历史
- 你希望代码复杂度最低
Message prompts
也可以通过提供 message 对象列表,将一组 messages 传给模型。- 管理多轮对话
- 处理多模态内容(图像、音频、文件)
- 包含 system instructions
Dictionary format
也可以直接使用 OpenAI chat completions 格式指定 messages。Message types
- System message:告诉模型如何行动,并为交互提供上下文
- Human message:表示用户输入以及与模型的交互
- AI message:模型生成的响应,包括文本内容、工具调用和 metadata
- Tool message:表示 tool calls 的输出
System message
SystemMessage 表示一组用于引导模型行为的初始指令。可以使用 system message 设置语气、定义模型角色,并建立响应准则。
Basic instructions
Detailed persona
Human message
HumanMessage 表示用户输入和交互。它可以包含文本、图像、音频、文件,以及任意数量的多模态 content。
Text content
Message object
String shortcut
Message metadata
Add metadata
name 字段的行为因 provider 而异,有些 provider 会用它识别用户,其他 provider 会忽略它。如需确认,请参阅模型 provider 的 reference。AI message
AIMessage 表示模型调用的输出。它可以包含多模态数据、工具调用,以及稍后可访问的 provider-specific metadata。
AIMessage 对象,其中包含响应中的所有相关 metadata。
不同 providers 会以不同方式权衡和理解不同类型的 messages,因此有时手动创建新的 AIMessage 对象并将其插入 message 历史会很有用,就像它来自模型一样。
Attributes
Attributes
Message 的文本内容。
Message 的原始内容。
模型发出的工具调用。如果没有调用 tools,则为空。
Message 的唯一标识符,由 LangChain 自动生成或在 provider 响应中返回。
Message 的 usage metadata,可在可用时包含 token 计数。参阅
UsageMetadata。Message 的 response metadata。
Tool calls
当模型发出 tool calls 时,这些调用会包含在AIMessage 中:
Token usage
AIMessage 可以在其 usage_metadata 字段中保存 token 计数和其他 usage metadata:
UsageMetadata。
Streaming and chunks
在 streaming 期间,你会收到AIMessageChunk 对象,它们可以合并成完整的 message 对象:
Tool message
对于支持 tool calling 的模型,AI messages 可以包含工具调用。Tool messages 用于将单个工具执行的结果传回模型。 Tools 可以直接生成ToolMessage 对象。下面展示一个简单示例。更多内容请阅读 tools guide。
Attributes
Attributes
artifact 字段存储不会发送给模型、但可通过程序访问的补充数据。这适合存储原始结果、调试信息或用于下游处理的数据,同时避免污染模型上下文。示例:使用 artifact 保存 retrieval metadata
示例:使用 artifact 保存 retrieval metadata
例如,retrieval 工具可以从文档中检索一段文本,供模型参考。Message 如需查看使用 LangChain 构建 retrieval agents 的端到端示例,请参阅 RAG tutorial。
content 包含模型会引用的文本,而 artifact 可以包含文档标识符或应用可使用的其他 metadata,例如用于渲染页面。请参阅下面的示例:Message content
可以将 message 的 content 理解为发送给模型的数据负载。Messages 具有一个弱类型的content 属性,支持字符串和无类型对象列表(例如字典)。这让 LangChain chat models 能够直接支持 provider-native 结构,例如 multimodal 内容和其他数据。
此外,LangChain 为文本、reasoning、citations、多模态数据、server-side tool calls 以及其他 message content 提供专用 content 类型。请参阅下面的 content blocks。
LangChain chat models 通过 content 属性接收 message content。
它可以包含以下任一内容:
- 字符串
- provider-native 格式的 content blocks 列表
- LangChain’s standard content blocks 列表
Standard content blocks
LangChain 为 message content 提供可跨 providers 使用的标准表示。 Message 对象实现了contentBlocks 属性,会将 content 属性惰性解析为标准、类型安全的表示。例如,由 ChatAnthropic 或 ChatOpenAI 生成的 messages 会包含对应 provider 格式的 thinking 或 reasoning blocks,但可以惰性解析为一致的 ReasoningContentBlock 表示:
- Anthropic
- OpenAI
序列化标准 content如果 LangChain 外部的应用需要访问标准 content block 表示,可以选择将 content blocks 存储在 message content 中。为此,可以将
LC_OUTPUT_VERSION 环境变量设置为 v1。也可以使用 outputVersion: "v1" 初始化任意 chat model:Multimodal
Multimodality 指处理不同形式数据的能力,例如文本、音频、图像和视频。LangChain 为这些数据提供可跨 providers 使用的标准类型。 Chat models 可以接受多模态数据作为输入,并生成多模态数据作为输出。下面展示包含多模态数据的输入 messages 简短示例。额外 keys 可以包含在 content block 顶层,或嵌套在
"extras": {"key": value} 中。OpenAI,
例如,PDF 需要 filename。具体要求请参阅所选模型的 provider page。Content block reference
Content blocks 表示为类型化对象列表,无论是在创建 message 时,还是访问contentBlocks 字段时都是如此。列表中的每一项都必须符合以下 block 类型之一:
Core
Core
Multimodal
Multimodal
ContentBlock.Multimodal.Image
ContentBlock.Multimodal.Image
ContentBlock.Multimodal.Audio
ContentBlock.Multimodal.Audio
ContentBlock.Multimodal.Video
ContentBlock.Multimodal.Video
ContentBlock.Multimodal.File
ContentBlock.Multimodal.File
Tool Calling
Tool Calling
ContentBlock.Tools.ToolCall
ContentBlock.Tools.ToolCall
ContentBlock.Tools.ToolCallChunk
ContentBlock.Tools.ToolCallChunk
Server-Side Tool Execution
Server-Side Tool Execution
ContentBlock.Tools.ServerToolCall
ContentBlock.Tools.ServerToolCall
ContentBlock.Tools.ServerToolCallChunk
ContentBlock.Tools.ServerToolCallChunk
Provider-Specific Blocks
Provider-Specific Blocks
ContentBlock.NonStandard
ContentBlock.NonStandard
ContentBlock 类型后,上述每个 content block 都可以作为单独类型寻址。
Content blocks 是 LangChain v1 在 messages 上引入的新属性,用于在保持现有代码向后兼容的同时,跨 providers 标准化 content 格式。Content blocks 并不是
content 属性的替代品,而是一个新属性,可用于以标准化格式访问 message content。Use with chat models
Chat models 接受一组 message 对象作为输入,并返回AIMessage 作为输出。交互通常是无状态的,因此简单的对话循环会使用不断增长的 messages 列表调用模型。
请参阅以下指南了解更多:
- 用于 persisting and managing conversation histories 的内置功能
- 管理上下文窗口的策略,包括 trimming and summarizing messages
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

