.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorial/quickstart_message.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_tutorial_quickstart_message.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorial_quickstart_message.py:


.. _message:

创建消息
====================

消息是 AgentScope 中的核心概念，用于支持多模态数据、工具 API、信息存储/交换和提示构建。

一个消息由四个字段组成：

- ``name``，
- ``role``，
- ``content``，以及
- ``metadata``

这些字段的类型和含义如下：

.. list-table:: 消息对象中的字段
    :header-rows: 1

    * - 字段
      - 类型
      - 描述
    * - name
      - ``str``
      - 消息发送者的名称/身份
    * - role
      - | ``Literal[``
        |     ``"system",``
        |     ``"assistant",``
        |     ``"user"``
        | ``]``
      - 消息发送者的角色，必须是 "system"、"assistant" 或 "user" 之一。
    * - content
      - ``str | list[ContentBlock]``
      - 消息包含的数据，可以是字符串或 block 的列表。
    * - metadata
      - ``dict[str, JSONSerializableObject] | None``
      - 包含额外元数据的字典，通常用于结构化输出。

.. tip:: - 在具有多个身份实体的应用程序中，``name`` 字段用于区分不同的身份。
 - 建议将 ``metadata`` 字段用于结构化输出，在 AgentScope 内置的模块中，``metadata`` 不会参与 LLM 的提示构建。

接下来，我们根据不同的场景分别介绍 ``content`` 字段中支持的不同数据结构（block）。

.. GENERATED FROM PYTHON SOURCE LINES 47-61

.. code-block:: Python


    from agentscope.message import (
        Msg,
        Base64Source,
        TextBlock,
        ThinkingBlock,
        ImageBlock,
        AudioBlock,
        VideoBlock,
        ToolUseBlock,
        ToolResultBlock,
    )
    import json








.. GENERATED FROM PYTHON SOURCE LINES 62-66

创建文本消息
-----------------------------
通过提供 ``name``、``role`` 和 ``content`` 字段来创建消息对象。


.. GENERATED FROM PYTHON SOURCE LINES 66-77

.. code-block:: Python


    msg = Msg(
        name="Jarvis",
        role="assistant",
        content="你好！我能怎么帮助你？",
    )

    print(f"发送者的名称: {msg.name}")
    print(f"发送者的角色: {msg.role}")
    print(f"消息的内容: {msg.content}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    发送者的名称: Jarvis
    发送者的角色: assistant
    消息的内容: 你好！我能怎么帮助你？




.. GENERATED FROM PYTHON SOURCE LINES 78-132

创建多模态消息
--------------------------------------
Message 类通过提供不同的 block 结构来支持多模态内容：

.. list-table:: AgentScope 中的多模态 block
    :header-rows: 1

    * - 类
      - 描述
      - 示例
    * - TextBlock
      - 纯文本数据
      - .. code-block:: python

            TextBlock(
               type="text",
               text="Hello, world!"
            )
    * - ImageBlock
      - 图像数据
      - .. code-block:: python

            ImageBlock(
               type="image",
               source=URLSource(
                   type="url",
                   url="https://example.com/image.jpg"
               )
            )
    * - AudioBlock
      - 音频数据
      - .. code-block:: python

            AudioBlock(
               type="audio",
               source=URLSource(
                   type="url",
                   url="https://example.com/audio.mp3"
               )
            )
    * - VideoBlock
      - 视频数据
      - .. code-block:: python

            VideoBlock(
               type="video",
               source=URLSource(
                   type="url",
                   url="https://example.com/video.mp4"
               )
            )

对于 ``ImageBlock``、``AudioBlock`` 和 ``VideoBlock``，还可以使用 base64 编码的字符串作为数据源（Source）：


.. GENERATED FROM PYTHON SOURCE LINES 132-168

.. code-block:: Python


    msg = Msg(
        name="Jarvis",
        role="assistant",
        content=[
            TextBlock(
                type="text",
                text="这是一个包含 base64 编码数据的多模态消息。",
            ),
            ImageBlock(
                type="image",
                source=Base64Source(
                    type="base64",
                    media_type="image/jpeg",
                    data="/9j/4AAQSkZ...",
                ),
            ),
            AudioBlock(
                type="audio",
                source=Base64Source(
                    type="base64",
                    media_type="audio/mpeg",
                    data="SUQzBAAAAA...",
                ),
            ),
            VideoBlock(
                type="video",
                source=Base64Source(
                    type="base64",
                    media_type="video/mp4",
                    data="AAAAIGZ0eX...",
                ),
            ),
        ],
    )








.. GENERATED FROM PYTHON SOURCE LINES 169-173

创建推理消息
--------------------------------------
``ThinkingBlock`` 用于支持推理模型，包含模型的思考过程。


.. GENERATED FROM PYTHON SOURCE LINES 173-189

.. code-block:: Python


    msg_thinking = Msg(
        name="Jarvis",
        role="assistant",
        content=[
            ThinkingBlock(
                type="thinking",
                thinking="我正在为 AgentScope 构建一个思考块的示例。",
            ),
            TextBlock(
                type="text",
                text="这是一个思考块的示例。",
            ),
        ],
    )








.. GENERATED FROM PYTHON SOURCE LINES 190-196

.. _tool-block:

创建工具使用/结果消息
--------------------------------------
``ToolUseBlock`` 和 ``ToolResultBlock`` 用于支持工具 API：


.. GENERATED FROM PYTHON SOURCE LINES 196-226

.. code-block:: Python


    msg_tool_call = Msg(
        name="Jarvis",
        role="assistant",
        content=[
            ToolUseBlock(
                type="tool_use",
                id="343",
                name="get_weather",
                input={
                    "location": "Beijing",
                },
            ),
        ],
    )

    msg_tool_res = Msg(
        name="system",
        role="system",
        content=[
            ToolResultBlock(
                type="tool_result",
                id="343",
                name="get_weather",
                output="北京的天气是晴天，温度为 25°C。",
            ),
        ],
    )









.. GENERATED FROM PYTHON SOURCE LINES 227-232

.. tip:: AgentScope 中，通常使用 ``role`` 为“system”的消息来记录工具函数的执行结果。有关 AgentScope 中工具的更多信息，请参考 :ref:`tool` 部分。

序列化和反序列化
------------------------------------------------
消息对象可以分别通过 ``to_dict`` 和 ``from_dict`` 方法进行序列化和反序列化。

.. GENERATED FROM PYTHON SOURCE LINES 232-238

.. code-block:: Python


    serialized_msg = msg.to_dict()

    print(type(serialized_msg))
    print(json.dumps(serialized_msg, indent=4, ensure_ascii=False))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <class 'dict'>
    {
        "id": "RW9QtrM7sVsrNrP7jXykWm",
        "name": "Jarvis",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "这是一个包含 base64 编码数据的多模态消息。"
            },
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/jpeg",
                    "data": "/9j/4AAQSkZ..."
                }
            },
            {
                "type": "audio",
                "source": {
                    "type": "base64",
                    "media_type": "audio/mpeg",
                    "data": "SUQzBAAAAA..."
                }
            },
            {
                "type": "video",
                "source": {
                    "type": "base64",
                    "media_type": "video/mp4",
                    "data": "AAAAIGZ0eX..."
                }
            }
        ],
        "metadata": null,
        "timestamp": "2025-08-27 03:47:11.741"
    }




.. GENERATED FROM PYTHON SOURCE LINES 239-240

从 JSON 格式的数据反序列化消息。

.. GENERATED FROM PYTHON SOURCE LINES 240-248

.. code-block:: Python


    new_msg = Msg.from_dict(serialized_msg)

    print(type(new_msg))
    print(f'消息的发送者: "{new_msg.name}"')
    print(f'发送者的角色: "{new_msg.role}"')
    print(f'消息的内容: "{json.dumps(new_msg.content, indent=4, ensure_ascii=False)}"')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <class 'agentscope.message._message_base.Msg'>
    消息的发送者: "Jarvis"
    发送者的角色: "assistant"
    消息的内容: "[
        {
            "type": "text",
            "text": "这是一个包含 base64 编码数据的多模态消息。"
        },
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/jpeg",
                "data": "/9j/4AAQSkZ..."
            }
        },
        {
            "type": "audio",
            "source": {
                "type": "base64",
                "media_type": "audio/mpeg",
                "data": "SUQzBAAAAA..."
            }
        },
        {
            "type": "video",
            "source": {
                "type": "base64",
                "media_type": "video/mp4",
                "data": "AAAAIGZ0eX..."
            }
        }
    ]"




.. GENERATED FROM PYTHON SOURCE LINES 249-268

属性函数
------------------------------------------------
为了便于使用 Msg 对象，AgentScope 提供了以下函数：

.. list-table:: Msg 对象的函数
  :header-rows: 1

  * - 函数
    - 参数
    - 描述
  * - ``get_text_content``
    -
    - 将所有 ``TextBlock`` 中的内容收集到单个字符串中（用 "\\n" 分隔）。
  * - ``get_content_blocks``
    - ``block_type``
    - 返回指定类型的内容块列表。如果未提供 ``block_type``，则以块格式返回全部内容。
  * - ``has_content_blocks``
    - ``block_type``
    - 检查消息是否具有指定类型的内容块。``str`` 内容会被视为 ``TextBlock`` 类型。


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.004 seconds)


.. _sphx_glr_download_tutorial_quickstart_message.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: quickstart_message.ipynb <quickstart_message.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: quickstart_message.py <quickstart_message.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: quickstart_message.zip <quickstart_message.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_