Create Message

Message is the core concept in AgentScope, used to support multimodal data, tools API, information storage/exchange and prompt construction.

A message consists of four fields:

• name,

• role,

• content, and

• metadata

The types and descriptions of these fields are as follows:

The fields in a message object

Field	Type	Description
name	str	The name/identity of the message sender
role	Literal[ "system", "assistant", "user" ]	The role of the message sender, which must be one of “system”, “assistant”, or “user”.
content	str | list[ContentBlock]	The data of the message, which can be a string or a list of blocks.
metadata	dict[str, JSONSerializableObject] | None	A dict containing additional metadata about the message, usually used for structured output.

Tip

• In application with multiple identities, the name field is used to distinguish between different identities.

• The metadata field is recommended for structured output, which won’t be included in the prompt construction.

Next, we introduce the supported blocks in the content field by their corresponding scenarios.

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

Creating Textual Message

Creating a message object by providing the name, role, and content fields.

msg = Msg(
    name="Jarvis",
    role="assistant",
    content="Hi! How can I help you?",
)

print(f"The name of the sender: {msg.name}")
print(f"The role of the sender: {msg.role}")
print(f"The content of the message: {msg.content}")

The name of the sender: Jarvis
The role of the sender: assistant
The content of the message: Hi! How can I help you?

Creating Multimodal Message

The message class supports multimodal content by providing different content blocks:

Multimodal content blocks in AgentScope

Class	Description	Example
TextBlock	Pure text data	TextBlock( type="text", text="Hello, world!" )
ImageBlock	The image data	ImageBlock( type="image", source=URLSource( type="url", url="https://example.com/image.jpg" ) )
AudioBlock	The audio data	AudioBlock( type="audio", source=URLSource( type="url", url="https://example.com/audio.mp3" ) )
VideoBlock	The video data	VideoBlock( type="video", source=URLSource( type="url", url="https://example.com/video.mp4" ) )

For ImageBlock, AudioBlock and VideoBlock, you can use either a base64 encoded string as the source:

msg = Msg(
    name="Jarvis",
    role="assistant",
    content=[
        TextBlock(
            type="text",
            text="This is a multimodal message with base64 encoded data.",
        ),
        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...",
            ),
        ),
    ],
)

Creating Thinking Message

The ThinkingBlock is to support reasoning models, containing the thinking process of the model.

msg_thinking = Msg(
    name="Jarvis",
    role="assistant",
    content=[
        ThinkingBlock(
            type="thinking",
            thinking="I'm building an example for thinking block in AgentScope.",
        ),
        TextBlock(
            type="text",
            text="This is an example for thinking block.",
        ),
    ],
)

Creating Tool Use/Result Message

The ToolUseBlock and ToolResultBlock are to support tools API:

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="The weather in Beijing is sunny with a temperature of 25°C.",
        ),
    ],
)

Tip

Refer to the Tool section for more information about tools API in AgentScope.

Serialization and Deserialization

Message object can be serialized and deserialized by to_dict and from_dict methods, respectively.

serialized_msg = msg.to_dict()

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

<class 'dict'>
{
    "id": "QoJYPkPKbqFR8BnpoyKPBo",
    "name": "Jarvis",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "This is a multimodal message with base64 encoded data."
        },
        {
            "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-15 09:49:54.579"
}

Deserialize a message from a string in JSON format.

new_msg = Msg.from_dict(serialized_msg)

print(type(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: "{json.dumps(new_msg.content, indent=4)}"')

<class 'agentscope.message._message_base.Msg'>
The sender of the message: "Jarvis"
The role of the sender: "assistant"
The content of the message: "[
    {
        "type": "text",
        "text": "This is a multimodal message with base64 encoded data."
    },
    {
        "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..."
        }
    }
]"

Property Functions

To ease the use of message object, AgentScope provides these functions:

Functions of the message object

Function	Parameters	Description
get_text_content	-	Gather content from all TextBlock in to a single string (separated by “\n”).
get_content_blocks	block_type	Return a list of content blocks of the specified type. If block_type not provided, return content in blocks format.
has_content_blocks	block_type	Check whether the message has content blocks of the specified type. The str content is considered as a TextBlock type.