类class agentscope.message

Msg

class Msg(BaseModel)

源码Source agentscope/message/_base.py:70–566

Msg 是智能体之间传递信息的统一载体。内容由 TextBlock、ThinkingBlock、ToolCallBlock、ToolResultBlock 等内容块组成，既表达纯文本，也表达多模态与工具调用。位于 agentscope.message 包。核心成员包括 validate_role_content、has_content_blocks、get_text_content、get_content_blocks、append_event、append_usage。

The message class in AgentScope, responsible for information storage and transmission among different agents. Declared in agentscope.message.

核心精讲Deep dive

Msg：统一消息模型Msg: the unified message model

Msg 是智能体之间传递信息的统一载体。内容由 TextBlock、ThinkingBlock、ToolCallBlock、ToolResultBlock 等内容块组成，既表达纯文本，也表达多模态与工具调用。

Msg is the unified carrier exchanged between agents. Its content is a list of blocks such as TextBlock, ThinkingBlock, ToolCallBlock and ToolResultBlock, covering plain text, multimodal data and tool interactions.

UserMsg、AssistantMsg、SystemMsg 是设置角色与名称的便捷构造函数。UserMsg, AssistantMsg and SystemMsg are convenience constructors that set role and name.
get_text_content 拼接所有文本块；has_content_blocks 判断是否包含某种块。get_text_content concatenates text blocks, while has_content_blocks checks for a specific block type.
usage、structured_output 与 metadata 携带用量、结构化结果和业务附加信息。usage, structured_output and metadata carry token usage, structured results and application metadata.

构造文本与多块消息Build text and multi-block messages

from agentscope.message import Msg, TextBlock, UserMsg

msg = UserMsg("user", "Summarize this contract.")
print(msg.role, msg.get_text_content())

rich = Msg(
    name="user",
    role="user",
    content=[
        TextBlock(type="text", text="What is in this image?"),
        # DataBlock 可承载图片、音频等二进制内容
    ],
)
print(rich.has_content_blocks("text"))

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	—
`content`	list[ContentBlock]	内容字段。	—
`role`	Literal['user', 'assistant', 'system']	角色字段。	—
`id`	str	标识字段。	`Field(default_factory=_generate_id)`
`metadata`	dict	元数据字段。	`Field(default_factory=dict)`
`created_at`	str	已创建 at字段。	`Field(default_factory=_generate_timestamp)`
`usage`	Usage \| None	用量字段。	`Field(default=None)`
`finished_at`	str \| None	`finished_at` 字段。	`Field(default=None)`
`finished_reason`	ReplyFinishedReason \| None	`finished_reason` 字段。	`Field(default=None)`
`structured_output`	dict \| None	结构化输出字段。	`Field(default=None)`
`error`	ErrorInfo \| None	错误字段。	`Field(default=None)`

方法摘要Method Summary

方法Method	说明Description
`def validate_role_content() -> Self`model_validator	校验角色与内容块组合是否合法。 Validate content blocks according to the role.
`def has_content_blocks(block_type: ContentBlockTypes \| list[ContentBlockTypes] \| None = None) -> bool`	判断消息是否包含指定类型的内容块。 Check if the message has content blocks of the given type.
`def get_text_content(separator: str = '\n') -> str \| None`	拼接所有文本块并返回纯文本；没有文本时返回 None。 Get the concatenated text from all TextBlocks.
`def get_content_blocks(block_type: Literal['text']) -> list[TextBlock]`overload	按类型筛选内容块，未指定类型时返回全部块。 Returns the content blocks.
`def get_content_blocks(block_type: ContentBlockTypes \| List[ContentBlockTypes] \| None = None) -> Sequence[ContentBlock]`	按类型筛选内容块，未指定类型时返回全部块。 Get content blocks, optionally filtered by type.
`def append_event(event: AgentEvent) -> Self`	把智能体事件追加到消息中，并同步用量与结束信息。 Update the message by applying a streaming event.
`def append_usage(usage:` `Usage) -> Self`	累加本次回复的 token 用量。 Accumulate the token usage of one model call into this message.

属性详情Attribute Detail

name

str

名称字段。声明为 str。

The name field.

源码Source agentscope/message/_base.py:78

content

list[ContentBlock]

内容字段。声明为 list[ContentBlock]。

The content field.

源码Source agentscope/message/_base.py:80

role

Literal['user', 'assistant', 'system']

角色字段。声明为 Literal['user', 'assistant', 'system']。

The role field.

源码Source agentscope/message/_base.py:82

id

str = Field(default_factory=_generate_id)

标识字段。声明为 str。

The id field.

源码Source agentscope/message/_base.py:84

metadata

dict = Field(default_factory=dict)

元数据字段。声明为 dict。

The metadata field.

源码Source agentscope/message/_base.py:92

created_at

str = Field(default_factory=_generate_timestamp)

已创建 at字段。声明为 str。

The created at field.

源码Source agentscope/message/_base.py:94

usage

Usage | None = Field(default=None)

用量字段。声明为 Usage | None。

The usage field.

源码Source agentscope/message/_base.py:96

finished_at

str | None = Field(default=None)

finished_at 字段。声明为 str | None。

The finished at field.

源码Source agentscope/message/_base.py:104

finished_reason

ReplyFinishedReason | None = Field(default=None)

finished_reason 字段。声明为 ReplyFinishedReason | None。

The finished reason field.

源码Source agentscope/message/_base.py:106

structured_output

dict | None = Field(default=None)

结构化输出字段。声明为 dict | None。

The structured output field.

源码Source agentscope/message/_base.py:109

error

ErrorInfo | None = Field(default=None)

错误字段。声明为 ErrorInfo | None。

The error field.

源码Source agentscope/message/_base.py:115

方法详情Method Detail

validate_role_content

def validate_role_content() -> Self

model_validator

校验角色内容。

Validate content blocks according to the role.

返回Returns Self

返回自身。Returns self.

源码Source agentscope/message/_base.py:120–129

has_content_blocks

def has_content_blocks(block_type: ContentBlockTypes | list[ContentBlockTypes] | None = None) -> bool

判断是否具有 has_content_blocks。

Check if the message has content blocks of the given type.

参数Parameters

名称Name	类型Type	说明Description
`block_type`默认default `None`	ContentBlockTypes \| list[ContentBlockTypes] \| None	块类型（类型 `ContentBlockTypes \| list[ContentBlockTypes] \| None`）。The type of the block to be checked. If `None`, all blocks will be checked. If a list is provided, it checks if there are blocks of any types in the list.

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/message/_base.py:131–153

get_text_content

def get_text_content(separator: str = '\n') -> str | None

获取消息中的纯文本内容。

Get the concatenated text from all TextBlocks.

参数Parameters

名称Name	类型Type	说明Description
`separator`默认default `'\n'`	str	separator（类型 `str`）。The separator.

返回Returns str | None

拼接后的文本；没有文本块时返回 None。Returns str none.

源码Source agentscope/message/_base.py:155–158

get_content_blocks

def get_content_blocks(block_type: Literal['text']) -> list[TextBlock]

overload

获取 get_content_blocks。

Returns the content blocks.

参数Parameters

名称Name	类型Type	说明Description
`block_type`	Literal['text']	块类型（类型 `Literal['text']`）。The block type.

返回Returns list[TextBlock]

返回TextBlock列表。Returns a list of text block.

源码Source agentscope/message/_base.py:161–165

get_content_blocks

def get_content_blocks(block_type: ContentBlockTypes | List[ContentBlockTypes] | None = None) -> Sequence[ContentBlock]

获取 get_content_blocks。

Returns the content blocks.

参数Parameters

名称Name	类型Type	说明Description
`block_type`默认default `None`	ContentBlockTypes \| List[ContentBlockTypes] \| None	块类型（类型 `ContentBlockTypes \| List[ContentBlockTypes] \| None`）。The type of the block to be extracted. If `None`, all blocks will be returned.

返回Returns Sequence[ContentBlock]

返回ContentBlock列表。`List[ContentBlock]`:

源码Source agentscope/message/_base.py:209–230

append_event

def append_event(event: AgentEvent) -> Self

追加事件。

Mutates self.content, self.finished_at, and self.usage: content blocks are appended/updated by block-level events, finished_at is stamped by REPLY_END, and usage is initialized then accumulated across each MODEL_CALL_END.

参数Parameters

名称Name	类型Type	说明Description
`event`	AgentEvent	事件（类型 `AgentEvent`）。The event to apply.

返回Returns Self

返回自身。Returns self.

源码Source agentscope/message/_base.py:243–545

append_usage

def append_usage(usage: Usage) -> Self

追加用量。

The message keeps a copy of usage, so the object handed over by the caller is never adopted and keeps its own value.

参数Parameters

名称Name	类型Type	说明Description
`usage`	Usage	用量（类型 `Usage`）。The token usage to be accumulated.

返回Returns Self

返回自身。Returns self.

源码Source agentscope/message/_base.py:547–566