> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 消息

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

消息是包含以下内容的对象：

* <Icon icon="user" size={16} /> [**角色**](#message-types) - 标识消息类型（例如 `system`、`user`）
* <Icon icon="folder" size={16} /> [**内容**](#message-content) - 代表消息的实际内容（如文本、图像、音频、文档等）
* <Icon icon="tag" size={16} /> [**元数据**](#message-metadata) - 可选字段，如响应信息、消息 ID 和 Token 使用情况

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

## 基本用法

使用消息最简单的方式是创建消息对象并在[调用](/oss/python/langchain/models#invocation)时将它们传递给模型。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage, AIMessage, SystemMessage

model = init_chat_model("gpt-5-nano")

system_msg = SystemMessage("You are a helpful assistant.")
human_msg = HumanMessage("Hello, how are you?")

# 与聊天模型一起使用
messages = [system_msg, human_msg]
response = model.invoke(messages)  # 返回 AIMessage
```

### 文本提示词

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
response = model.invoke("Write a haiku about spring")
```

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

* 你有一个单独的、独立的请求
* 你不需要对话历史
* 你想要最少的代码复杂性

### 消息提示词

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import SystemMessage, HumanMessage, AIMessage

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

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

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

### 字典格式

你也可以直接使用 OpenAI chat completions 格式指定消息。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
messages = [
    {"role": "system", "content": "You are a poetry expert"},
    {"role": "user", "content": "Write a haiku about spring"},
    {"role": "assistant", "content": "Cherry blossoms bloom..."}
]
response = model.invoke(messages)
```

## 消息类型

* <Icon icon="settings" size={16} /> [系统消息](#system-message) - 告诉模型如何行为并为交互提供上下文
* <Icon icon="user" size={16} /> [人类消息](#human-message) - 代表用户输入和与模型的交互
* <Icon icon="robot" size={16} /> [AI 消息](#ai-message) - 模型生成的响应，包括文本内容、工具调用和元数据
* <Icon icon="tool" size={16} /> [工具消息](#tool-message) - 代表[工具调用](/oss/python/langchain/models#tool-calling)的输出

### 系统消息

[`SystemMessage`](https://reference.langchain.com/python/langchain-core/messages/system/SystemMessage) 代表一组初始指令，用于预设模型的行为。你可以使用系统消息来设定语气、定义模型的角色，并建立响应的准则。

```python 基本指令 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
system_msg = SystemMessage("You are a helpful coding assistant.")

messages = [
    system_msg,
    HumanMessage("How do I create a REST API?")
]
response = model.invoke(messages)
```

```python 详细角色设定 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import SystemMessage, HumanMessage

system_msg = SystemMessage("""
You are a senior Python developer with expertise in web frameworks.
Always provide code examples and explain your reasoning.
Be concise but thorough in your explanations.
""")

messages = [
    system_msg,
    HumanMessage("How do I create a REST API?")
]
response = model.invoke(messages)
```

***

### 人类消息

[`HumanMessage`](https://reference.langchain.com/python/langchain-core/messages/human/HumanMessage) 代表用户输入和交互。它们可以包含文本、图像、音频、文件以及任何数量的多模态[内容](#message-content)。

#### 文本内容

<CodeGroup>
  ```python 消息对象 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  response = model.invoke([
    HumanMessage("What is machine learning?")
  ])
  ```

  ```python 字符串快捷方式 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 使用字符串是单个 HumanMessage 的快捷方式
  response = model.invoke("What is machine learning?")
  ```
</CodeGroup>

#### 消息元数据

```python 添加元数据 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
human_msg = HumanMessage(
    content="Hello!",
    name="alice",  # 可选：标识不同的用户
    id="msg_123",  # 可选：用于追踪的唯一标识符
)
```

<Note>
  `name` 字段的行为因提供商而异——有些用它来识别用户，有些则忽略它。要查看详情，请参阅模型提供商的[参考文档](https://reference.langchain.com/python/integrations/)。
</Note>

***

### AI 消息

[`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 代表模型调用的输出。它们可以包含多模态数据、工具调用和你可以随后访问的提供商特定元数据。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
response = model.invoke("Explain AI")
print(type(response))  # <class 'langchain.messages.AIMessage'>
```

[`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 对象在调用模型时返回，其中包含响应中所有关联的元数据。

提供商对消息类型的权重/上下文化方式不同，这意味着有时手动创建一个新的 [`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 对象并将其插入消息历史中（就像它来自模型一样）是有帮助的。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import AIMessage, SystemMessage, HumanMessage

# 手动创建 AI 消息（例如，用于对话历史）
ai_msg = AIMessage("I'd be happy to help you with that question!")

# 添加到对话历史
messages = [
    SystemMessage("You are a helpful assistant"),
    HumanMessage("Can you help me?"),
    ai_msg,  # 插入，就像它来自模型
    HumanMessage("Great! What's 2+2?")
]

response = model.invoke(messages)
```

<Accordion title="属性">
  <ParamField path="text" type="string">
    消息的文本内容。
  </ParamField>

  <ParamField path="content" type="string | dict[]">
    消息的原始内容。
  </ParamField>

  <ParamField path="content_blocks" type="ContentBlock[]">
    消息的标准化[内容块](#message-content)。
  </ParamField>

  <ParamField path="tool_calls" type="dict[] | None">
    模型发起的工具调用。

    如果没有调用工具则为空。
  </ParamField>

  <ParamField path="id" type="string">
    消息的唯一标识符（由 LangChain 自动生成或在提供商响应中返回）
  </ParamField>

  <ParamField path="usage_metadata" type="dict | None">
    消息的使用元数据，可用时包含 Token 计数。
  </ParamField>

  <ParamField path="response_metadata" type="ResponseMetadata | None">
    消息的响应元数据。
  </ParamField>
</Accordion>

#### 工具调用

当模型发起[工具调用](/oss/python/langchain/models#tool-calling)时，它们包含在 [`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 中：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.chat_models import init_chat_model

model = init_chat_model("gpt-5-nano")

def get_weather(location: str) -> str:
    """Get the weather at a location."""
    ...

model_with_tools = model.bind_tools([get_weather])
response = model_with_tools.invoke("What's the weather in Paris?")

for tool_call in response.tool_calls:
    print(f"Tool: {tool_call['name']}")
    print(f"Args: {tool_call['args']}")
    print(f"ID: {tool_call['id']}")
```

其他结构化数据，如推理或引用，也可以出现在消息[内容](/oss/python/langchain/messages#message-content)中。

#### Token 使用情况

[`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 可以在其 [`usage_metadata`](https://reference.langchain.com/python/langchain-core/messages/ai/UsageMetadata) 字段中保存 Token 计数和其他使用元数据：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.chat_models import init_chat_model

model = init_chat_model("gpt-5-nano")

response = model.invoke("Hello!")
response.usage_metadata
```

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

有关详情，请参阅 [`UsageMetadata`](https://reference.langchain.com/python/langchain-core/messages/ai/UsageMetadata)。

#### 流式输出和块

在流式输出期间，你会收到 [`AIMessageChunk`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessageChunk) 对象，它们可以组合成完整的消息对象：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
chunks = []
full_message = None
for chunk in model.stream("Hi"):
    chunks.append(chunk)
    print(chunk.text)
    full_message = chunk if full_message is None else full_message + chunk
```

<Note>
  了解更多：

  * [从聊天模型流式输出 Token](/oss/python/langchain/models#stream)
  * [从智能体流式输出 Token 和/或步骤](/oss/python/langchain/streaming)
</Note>

***

### 工具消息

对于支持[工具调用](/oss/python/langchain/models#tool-calling)的模型，AI 消息可以包含工具调用。工具消息用于将单个工具执行的结果传回给模型。

[工具](/oss/python/langchain/tools)可以直接生成 [`ToolMessage`](https://reference.langchain.com/python/langchain-core/messages/tool/ToolMessage) 对象。以下展示一个简单示例。更多内容请阅读[工具指南](/oss/python/langchain/tools)。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import AIMessage
from langchain.messages import ToolMessage

# 模型发起工具调用后
# （此处，我们为简洁起见手动创建消息进行演示）
ai_message = AIMessage(
    content=[],
    tool_calls=[{
        "name": "get_weather",
        "args": {"location": "San Francisco"},
        "id": "call_123"
    }]
)

# 执行工具并创建结果消息
weather_result = "Sunny, 72°F"
tool_message = ToolMessage(
    content=weather_result,
    tool_call_id="call_123"  # 必须与调用 ID 匹配
)

# 继续对话
messages = [
    HumanMessage("What's the weather in San Francisco?"),
    ai_message,  # 模型的工具调用
    tool_message,  # 工具执行结果
]
response = model.invoke(messages)  # 模型处理结果
```

<Accordion title="属性">
  <ParamField path="content" type="string" required>
    工具调用的字符串化输出。
  </ParamField>

  <ParamField path="tool_call_id" type="string" required>
    此消息响应的工具调用 ID。必须与 [`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 中工具调用的 ID 匹配。
  </ParamField>

  <ParamField path="name" type="string" required>
    被调用的工具名称。
  </ParamField>

  <ParamField path="artifact" type="dict">
    不发送给模型但可以通过编程方式访问的附加数据。
  </ParamField>
</Accordion>

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

  <Accordion title="示例：使用 artifact 存储检索元数据">
    例如，[检索](/oss/python/langchain/retrieval)工具可以从文档中检索一段文字供模型参考。消息 `content` 包含模型将引用的文本，而 `artifact` 可以包含应用程序可以使用的文档标识符或其他元数据（例如，用于渲染页面）。参见下面的示例：

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langchain.messages import ToolMessage

    # 发送给模型
    message_content = "It was the best of times, it was the worst of times."

    # Artifact 可供下游使用
    artifact = {"document_id": "doc_123", "page": 0}

    tool_message = ToolMessage(
        content=message_content,
        tool_call_id="call_123",
        name="search_books",
        artifact=artifact,
    )
    ```

    有关使用 LangChain 构建检索[智能体](/oss/python/langchain/agents)的端到端示例，请参阅 [RAG 教程](/oss/python/langchain/rag)。
  </Accordion>
</Note>

***

## 消息内容

你可以将消息的内容视为发送给模型的数据载荷。消息有一个 `content` 属性，它是松散类型的，支持字符串和无类型对象列表（例如字典）。这允许在 LangChain 聊天模型中直接支持提供商原生结构，如[多模态](#multimodal)内容和其他数据。

另外，LangChain 为文本、推理、引用、多模态数据、服务器端工具调用和其他消息内容提供了专用的内容类型。参见下面的[内容块](#standard-content-blocks)。

LangChain 聊天模型在 `content` 属性中接受消息内容。

它可以包含以下之一：

1. 字符串
2. 提供商原生格式的内容块列表
3. [LangChain 标准内容块](#standard-content-blocks)列表

参见下面使用[多模态](#multimodal)输入的示例：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import HumanMessage

# 字符串内容
human_message = HumanMessage("Hello, how are you?")

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

# 标准内容块列表
human_message = HumanMessage(content_blocks=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image", "url": "https://example.com/image.jpg"},
])
```

<Tip>
  在初始化消息时指定 `content_blocks` 仍然会填充消息的 `content`，但提供了一个类型安全的接口。
</Tip>

### 标准内容块

LangChain 提供了一种跨提供商工作的消息内容标准表示。

消息对象实现了一个 `content_blocks` 属性，它会惰性解析 `content` 属性为标准的、类型安全的表示。例如，从 [`ChatAnthropic`](/oss/python/integrations/chat/anthropic) 或 [`ChatOpenAI`](/oss/python/integrations/chat/openai) 生成的消息将包含各自提供商格式的 `thinking` 或 `reasoning` 块，但可以被惰性解析为一致的 [`ReasoningContentBlock`](#content-block-reference) 表示：

<Tabs>
  <Tab title="Anthropic">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langchain.messages import AIMessage

    message = AIMessage(
        content=[
            {"type": "thinking", "thinking": "...", "signature": "WaUjzkyp..."},
            {"type": "text", "text": "..."},
        ],
        response_metadata={"model_provider": "anthropic"}
    )
    message.content_blocks
    ```

    ```
    [{'type': 'reasoning',
      'reasoning': '...',
      'extras': {'signature': 'WaUjzkyp...'}},
     {'type': 'text', 'text': '...'}]
    ```
  </Tab>

  <Tab title="OpenAI">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langchain.messages import AIMessage

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

    ```
    [{'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 1'},
     {'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 2'},
     {'type': 'text', 'text': '...', 'id': 'msg_abc123'}]
    ```
  </Tab>
</Tabs>

请参阅[集成指南](/oss/python/integrations/providers/overview)以开始使用你选择的推理提供商。

<Note>
  **序列化标准内容**

  如果 LangChain 之外的应用程序需要访问标准内容块表示，你可以选择将内容块存储在消息内容中。

  为此，你可以将 `LC_OUTPUT_VERSION` 环境变量设置为 `v1`。或者，使用 `output_version="v1"` 初始化任何聊天模型：

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.chat_models import init_chat_model

  model = init_chat_model("gpt-5-nano", output_version="v1")
  ```
</Note>

### 多模态

**多模态**指的是处理不同形式数据的能力，如文本、音频、图像和视频。LangChain 包含这些数据的标准类型，可以跨提供商使用。

[聊天模型](/oss/python/langchain/models)可以接受多模态数据作为输入并将其作为输出生成。以下展示了包含多模态数据的输入消息的简短示例。

<Note>
  额外的键可以在内容块的顶层包含，也可以嵌套在 `"extras": {"key": value}` 中。

  [OpenAI](/oss/python/integrations/chat/openai) 和 [AWS Bedrock Converse](/oss/python/integrations/chat/bedrock) 等提供商需要 PDF 的文件名。有关具体信息，请参阅你选择的模型的[提供商页面](/oss/python/integrations/providers/overview)。
</Note>

<CodeGroup>
  ```python 图像输入 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 从 URL
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this image."},
          {"type": "image", "url": "https://example.com/path/to/image.jpg"},
      ]
  }

  # 从 base64 数据
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this image."},
          {
              "type": "image",
              "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
              "mime_type": "image/jpeg",
          },
      ]
  }

  # 从提供商管理的文件 ID
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this image."},
          {"type": "image", "file_id": "file-abc123"},
      ]
  }
  ```

  ```python PDF 文档输入 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 从 URL
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this document."},
          {"type": "file", "url": "https://example.com/path/to/document.pdf"},
      ]
  }

  # 从 base64 数据
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this document."},
          {
              "type": "file",
              "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
              "mime_type": "application/pdf",
          },
      ]
  }

  # 从提供商管理的文件 ID
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this document."},
          {"type": "file", "file_id": "file-abc123"},
      ]
  }
  ```

  ```python 音频输入 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 从 base64 数据
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this audio."},
          {
              "type": "audio",
              "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
              "mime_type": "audio/wav",
          },
      ]
  }

  # 从提供商管理的文件 ID
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this audio."},
          {"type": "audio", "file_id": "file-abc123"},
      ]
  }
  ```

  ```python 视频输入 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 从 base64 数据
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this video."},
          {
              "type": "video",
              "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
              "mime_type": "video/mp4",
          },
      ]
  }

  # 从提供商管理的文件 ID
  message = {
      "role": "user",
      "content": [
          {"type": "text", "text": "Describe the content of this video."},
          {"type": "video", "file_id": "file-abc123"},
      ]
  }
  ```
</CodeGroup>

<Warning>
  并非所有模型都支持所有文件类型。请查看模型提供商的[参考文档](https://reference.langchain.com/python/integrations/)了解支持的格式和大小限制。
</Warning>

### 内容块参考

内容块表示为（创建消息时或访问 `content_blocks` 属性时的）类型化字典列表。列表中的每个项目必须符合以下块类型之一：

<AccordionGroup>
  <Accordion title="核心" icon="cube">
    <AccordionGroup>
      <Accordion title="TextContentBlock" icon="typography">
        **用途：** 标准文本输出

        <ParamField body="type" type="string" required>
          始终为 `"text"`
        </ParamField>

        <ParamField body="text" type="string" required>
          文本内容
        </ParamField>

        <ParamField body="annotations" type="object[]">
          文本的注释列表
        </ParamField>

        <ParamField body="extras" type="object">
          附加的提供商特定数据
        </ParamField>

        **示例：**

        ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            "type": "text",
            "text": "Hello world",
            "annotations": []
        }
        ```
      </Accordion>

      <Accordion title="ReasoningContentBlock" icon="brain">
        **用途：** 模型推理步骤

        <ParamField body="type" type="string" required>
          始终为 `"reasoning"`
        </ParamField>

        <ParamField body="reasoning" type="string">
          推理内容
        </ParamField>

        <ParamField body="extras" type="object">
          附加的提供商特定数据
        </ParamField>

        **示例：**

        ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            "type": "reasoning",
            "reasoning": "The user is asking about...",
            "extras": {"signature": "abc123"},
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="多模态" icon="photo">
    <AccordionGroup>
      <Accordion title="ImageContentBlock" icon="photo">
        **用途：** 图像数据

        <ParamField body="type" type="string" required>始终为 `"image"`</ParamField>
        <ParamField body="url" type="string">指向图像位置的 URL。</ParamField>
        <ParamField body="base64" type="string">Base64 编码的图像数据。</ParamField>
        <ParamField body="id" type="string">此内容块的唯一标识符（由提供商或 LangChain 生成）。</ParamField>
        <ParamField body="mime_type" type="string">图像 [MIME 类型](https://www.iana.org/assignments/media-types/media-types.xhtml#image)（例如 `image/jpeg`、`image/png`）。base64 数据必需。</ParamField>
      </Accordion>

      <Accordion title="AudioContentBlock" icon="volume">
        **用途：** 音频数据

        <ParamField body="type" type="string" required>始终为 `"audio"`</ParamField>
        <ParamField body="url" type="string">指向音频位置的 URL。</ParamField>
        <ParamField body="base64" type="string">Base64 编码的音频数据。</ParamField>
        <ParamField body="id" type="string">此内容块的唯一标识符（由提供商或 LangChain 生成）。</ParamField>
        <ParamField body="mime_type" type="string">音频 [MIME 类型](https://www.iana.org/assignments/media-types/media-types.xhtml#audio)（例如 `audio/mpeg`、`audio/wav`）。base64 数据必需。</ParamField>
      </Accordion>

      <Accordion title="VideoContentBlock" icon="video">
        **用途：** 视频数据

        <ParamField body="type" type="string" required>始终为 `"video"`</ParamField>
        <ParamField body="url" type="string">指向视频位置的 URL。</ParamField>
        <ParamField body="base64" type="string">Base64 编码的视频数据。</ParamField>
        <ParamField body="id" type="string">此内容块的唯一标识符（由提供商或 LangChain 生成）。</ParamField>
        <ParamField body="mime_type" type="string">视频 [MIME 类型](https://www.iana.org/assignments/media-types/media-types.xhtml#video)（例如 `video/mp4`、`video/webm`）。base64 数据必需。</ParamField>
      </Accordion>

      <Accordion title="FileContentBlock" icon="file">
        **用途：** 通用文件（PDF 等）

        <ParamField body="type" type="string" required>始终为 `"file"`</ParamField>
        <ParamField body="url" type="string">指向文件位置的 URL。</ParamField>
        <ParamField body="base64" type="string">Base64 编码的文件数据。</ParamField>
        <ParamField body="id" type="string">此内容块的唯一标识符（由提供商或 LangChain 生成）。</ParamField>
        <ParamField body="mime_type" type="string">文件 [MIME 类型](https://www.iana.org/assignments/media-types/media-types.xhtml)（例如 `application/pdf`）。base64 数据必需。</ParamField>
      </Accordion>

      <Accordion title="PlainTextContentBlock" icon="align-left">
        **用途：** 文档文本（`.txt`、`.md`）

        <ParamField body="type" type="string" required>始终为 `"text-plain"`</ParamField>
        <ParamField body="text" type="string">文本内容</ParamField>
        <ParamField body="mime_type" type="string">文本的 [MIME 类型](https://www.iana.org/assignments/media-types/media-types.xhtml)（例如 `text/plain`、`text/markdown`）</ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="工具调用" icon="tool">
    <AccordionGroup>
      <Accordion title="ToolCall" icon="function">
        **用途：** 函数调用

        <ParamField body="type" type="string" required>始终为 `"tool_call"`</ParamField>
        <ParamField body="name" type="string" required>要调用的工具名称</ParamField>
        <ParamField body="args" type="object" required>传递给工具的参数</ParamField>
        <ParamField body="id" type="string" required>此工具调用的唯一标识符</ParamField>

        **示例：**

        ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            "type": "tool_call",
            "name": "search",
            "args": {"query": "weather"},
            "id": "call_123"
        }
        ```
      </Accordion>

      <Accordion title="ToolCallChunk" icon="puzzle">
        **用途：** 流式工具调用片段

        <ParamField body="type" type="string" required>始终为 `"tool_call_chunk"`</ParamField>
        <ParamField body="name" type="string">正在调用的工具名称</ParamField>
        <ParamField body="args" type="string">部分工具参数（可能是不完整的 JSON）</ParamField>
        <ParamField body="id" type="string">工具调用标识符</ParamField>
        <ParamField body="index" type="number | string">此块在流中的位置</ParamField>
      </Accordion>

      <Accordion title="InvalidToolCall" icon="alert-triangle">
        **用途：** 格式错误的调用，用于捕获 JSON 解析错误。

        <ParamField body="type" type="string" required>始终为 `"invalid_tool_call"`</ParamField>
        <ParamField body="name" type="string">未能调用的工具名称</ParamField>
        <ParamField body="args" type="object">传递给工具的参数</ParamField>
        <ParamField body="error" type="string">出错原因的描述</ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="服务器端工具执行" icon="server">
    <AccordionGroup>
      <Accordion title="ServerToolCall" icon="tool">
        **用途：** 在服务器端执行的工具调用。

        <ParamField body="type" type="string" required>始终为 `"server_tool_call"`</ParamField>
        <ParamField body="id" type="string" required>与工具调用关联的标识符。</ParamField>
        <ParamField body="name" type="string" required>要调用的工具名称。</ParamField>
        <ParamField body="args" type="string" required>部分工具参数（可能是不完整的 JSON）</ParamField>
      </Accordion>

      <Accordion title="ServerToolCallChunk" icon="puzzle">
        **用途：** 流式服务器端工具调用片段

        <ParamField body="type" type="string" required>始终为 `"server_tool_call_chunk"`</ParamField>
        <ParamField body="id" type="string">与工具调用关联的标识符。</ParamField>
        <ParamField body="name" type="string">正在调用的工具名称</ParamField>
        <ParamField body="args" type="string">部分工具参数（可能是不完整的 JSON）</ParamField>
        <ParamField body="index" type="number | string">此块在流中的位置</ParamField>
      </Accordion>

      <Accordion title="ServerToolResult" icon="package">
        **用途：** 搜索结果

        <ParamField body="type" type="string" required>始终为 `"server_tool_result"`</ParamField>
        <ParamField body="tool_call_id" type="string" required>对应服务器端工具调用的标识符。</ParamField>
        <ParamField body="id" type="string">与服务器端工具结果关联的标识符。</ParamField>
        <ParamField body="status" type="string" required>服务器端工具的执行状态。`"success"` 或 `"error"`。</ParamField>
        <ParamField body="output">已执行工具的输出。</ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="提供商特定块" icon="plug">
    <Accordion title="NonStandardContentBlock" icon="asterisk">
      **用途：** 提供商特定的逃生通道

      <ParamField body="type" type="string" required>始终为 `"non_standard"`</ParamField>
      <ParamField body="value" type="object" required>提供商特定的数据结构</ParamField>

      **用法：** 用于实验性或提供商独有的功能
    </Accordion>

    其他提供商特定的内容类型可在每个模型提供商的[参考文档](/oss/python/integrations/providers/overview)中找到。
  </Accordion>
</AccordionGroup>

<Tip>
  在 [API 参考](https://reference.langchain.com/python/langchain/messages)中查看规范类型定义。
</Tip>

<Info>
  内容块作为消息的新属性在 LangChain v1 中引入，用于标准化跨提供商的内容格式，同时保持与现有代码的向后兼容性。

  内容块不是 [`content`](https://reference.langchain.com/python/langchain-core/messages/base/BaseMessage) 属性的替代品，而是一个可用于以标准化格式访问消息内容的新属性。
</Info>

## 与聊天模型一起使用

[聊天模型](/oss/python/langchain/models)接受消息对象序列作为输入，并返回 [`AIMessage`](https://reference.langchain.com/python/langchain-core/messages/ai/AIMessage) 作为输出。交互通常是无状态的，因此简单的对话循环涉及使用不断增长的消息列表来调用模型。

参阅以下指南了解更多：

* [持久化和管理对话历史](/oss/python/langchain/short-term-memory)的内置功能
* 管理上下文窗口的策略，包括[修剪和摘要消息](/oss/python/langchain/short-term-memory#common-patterns)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/messages.mdx)或[提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>