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:

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.

from agentscope.message import Msg
import json

Create a Message

Message can be created by specifying the name, role, and content fields.

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}"')

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

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:

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:

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"),
    ],
)

Tip

For tools API, there are two additional blocks: ToolUseBlock and ToolResultBlock. Further reading refer to Tools.

Serialize

Message can be serialized to a string in JSON format.

serialized_msg = msg.to_dict()

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

<class 'dict'>
{
    "__module__": "agentscope.message.msg",
    "__name__": "Msg",
    "id": "a34b2739db8a406d99ca30485d157595",
    "name": "Jarvis",
    "role": "assistant",
    "content": "Hi! How can I help you?",
    "metadata": null,
    "timestamp": "2025-03-27 11:00:55"
}

Deserialize

Deserialize a message from a string in JSON format.

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}"')

id='a34b2739db8a406d99ca30485d157595' name='Jarvis' role='assistant' content='Hi! How can I help you?' metadata=None timestamp='2025-03-27 11:00:55'
The sender of the message: "Jarvis"
The role of the sender: "assistant"
The content of the message: "Hi! How can I help you?"