.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "build_tutorial/message.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_build_tutorial_message.py: .. _message: Message ==================== Message is a specialized data structure for information exchange. In AgentScope, we use message to communicate among agents. A message consists of four fields: `name`, `role`, `content`, and `metadata`. The types and meanings of these fields are as follows: .. list-table:: :header-rows: 1 * - Field - Type - Description * - name - `str` - The name of the message sender * - role - `Literal["system", "assistant", "user"]` - The role of the message sender, which must be one of "system", "assistant", or "user". "system" is commonly used for system prompt or system messages (e.g., tool execution); "assistant" is usually LLM-empowered agents; "user" is for users. * - content - `Union[str, list[ContentBlock]]` - The specific content of the message, which can be a string or a list of `ContentBlock`. `ContentBlock` is a dictionary. * - metadata - `JSONSerializable` - Used to store structured data, which can be any serializable object, such as structured output of agents. .. tip:: In multi-agent systems, when the `role` field is "user" or "assistant", the `name` field can have different values to distinguish different identities. When the `role` field is "system", the `name` field is usually fixed, such as "system". .. tip:: When the data in the message is used for controlling the flow or structured output, it is recommended to use the `metadata` field. .. GENERATED FROM PYTHON SOURCE LINES 44-48 .. code-block:: Python from agentscope.message import Msg import json .. GENERATED FROM PYTHON SOURCE LINES 49-52 Create a Message ---------------- Message can be created by specifying the `name`, `role`, and `content` fields. .. GENERATED FROM PYTHON SOURCE LINES 52-64 .. code-block:: Python msg = Msg( name="Jarvis", role="assistant", content="Hi! How can I help you?", ) print(f'The sender of the message: "{msg.name}"') print(f'The role of the sender: "{msg.role}"') print(f'The content of the message: "{msg.content}"') .. rst-class:: sphx-glr-script-out .. code-block:: none The sender of the message: "Jarvis" The role of the sender: "assistant" The content of the message: "Hi! How can I help you?" .. GENERATED FROM PYTHON SOURCE LINES 65-96 Multimodal Message ------------------------- The `content` field also supports multimodal content, such as text, image, audio, and video. AgentScope uses the concept of block to represent the content of a message. A block is a dictionary containing the type and content of the message, and the specific supported types are as follows: .. list-table:: :header-rows: 1 * - Class - Description - Example * - TextBlock - Text block - `TextBlock(type="text", text="你好")` * - ImageBlock - Image block - `ImageBlock(type="image", url="https://example.com/image.jpg")` * - AudioBlock - Audio block - `AudioBlock(type="audio", url="https://example.com/audio.mp3")` * - VideoBlock - Video block - `VideoBlock(type="video", url="https://example.com/video.mp4")` * - FileBlock - File block - `FileBlock(type="file", url="https://example.com/file.zip")` The usage is as follows: .. GENERATED FROM PYTHON SOURCE LINES 96-121 .. code-block:: Python from agentscope.message import ( TextBlock, ImageBlock, AudioBlock, ) msg_image = Msg( name="Stank", role="user", content=[ TextBlock(type="text", text="Describe this image for me."), ImageBlock(type="image", url="https://example.com/image.jpg"), ], ) msg_audio = Msg( name="Stank", role="user", content=[ TextBlock(type="text", text="Listen to this audio."), AudioBlock(type="audio", url="https://example.com/audio.mp3"), ], ) .. GENERATED FROM PYTHON SOURCE LINES 122-128 .. tip:: For tools API, there are two additional blocks: `ToolUseBlock` and `ToolResultBlock`. Further reading refer to :ref:`tools`. Serialize ---------------- Message can be serialized to a string in JSON format. .. GENERATED FROM PYTHON SOURCE LINES 128-134 .. code-block:: Python serialized_msg = msg.to_dict() print(type(serialized_msg)) print(json.dumps(serialized_msg, indent=4)) .. rst-class:: sphx-glr-script-out .. code-block:: none { "__module__": "agentscope.message.msg", "__name__": "Msg", "id": "c136e5e83b4a4acf851e71069d8bf212", "name": "Jarvis", "role": "assistant", "content": "Hi! How can I help you?", "metadata": null, "timestamp": "2025-07-05 10:52:47" } .. GENERATED FROM PYTHON SOURCE LINES 135-138 Deserialize ---------------- Deserialize a message from a string in JSON format. .. GENERATED FROM PYTHON SOURCE LINES 138-145 .. code-block:: Python new_msg = Msg.from_dict(serialized_msg) print(new_msg) print(f'The sender of the message: "{new_msg.name}"') print(f'The role of the sender: "{new_msg.role}"') print(f'The content of the message: "{new_msg.content}"') .. rst-class:: sphx-glr-script-out .. code-block:: none id='c136e5e83b4a4acf851e71069d8bf212' name='Jarvis' role='assistant' content='Hi! How can I help you?' metadata=None timestamp='2025-07-05 10:52:47' The sender of the message: "Jarvis" The role of the sender: "assistant" The content of the message: "Hi! How can I help you?" .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.002 seconds) .. _sphx_glr_download_build_tutorial_message.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: message.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: message.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: message.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_