agentscope.formatter¶

agentscope中的格式化模块。

class FormatterBase[source]¶

基础：object

格式化器的基类。

abstract async format(*args, **kwargs)[source]¶

将 Msg 对象格式化为满足 API 要求的字典列表。

Parameters:

参数 (任意类型)
kwargs (任何)

Return type:

列表[字典[字符串, 任意类型]]

static assert_list_of_msgs(msgs)[source]¶

断言输入是一个Msg对象的列表。

Parameters:: msgs (list[Msg]) – 待验证的Msg对象列表。
Return type:: 无

static convert_tool_result_to_string(output)[source]¶

将工具结果列表转化为文本输出，以便与不支持多模态数据的LLM API兼容。

Parameters:: 输出 (str | List[TextBlock | ImageBlock | AudioBlock]) – 工具响应的输出内容，包含文本以及如图片和音频等多模态数据。
Returns:: 工具结果的字符串表示形式，其中文本块被连接，并以文件路径或URL表示多模态数据。
Return type:: 字符串

class TruncatedFormatterBase[source]¶

继承自：FormatterBase, ABC

截断格式器的基类，用于将输入消息按照指定限制下的令牌数量格式化

__init__(token_counter=None, max_tokens=None)[source]¶

初始化 TruncatedFormatterBase。

Parameters:

token_counter (TokenCounterBase | None, optional) – 用于统计消息中token数量的token计数器实例。如果未提供，格式化程序将在不考虑token限制的情况下对消息进行格式化。
max_tokens (int | None, optional) – 格式化消息中允许的最大令牌数。如果未提供，格式化器将不会截断消息。

Return type:

无

async format(msgs, **kwargs)[source]¶

将输入消息格式化为所需格式。如果提供了令牌计数器和最大令牌限制，消息将被截断以符合限制。

Parameters:

msgs (list[Msg]) – 需要被格式化的输入消息。
kwargs (任何)

Returns:

符合所需格式的格式化消息。

Return type:

list[dict[str, Any]]

async _format(msgs)[source]¶

将输入消息格式化为所需格式。此方法应由子类实现。

Parameters:: 消息列表 (列表[Msg])
Return type:: 列表[字典[字符串, 任意类型]]

async _format_tool_sequence(msgs)[source]¶

给定一系列工具调用/结果消息，将它们格式化为LLM API所需的格式。

Parameters:: msgs (列表[Msg])
Return type:: 列表[字典[字符串, 任意类型]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定不包含工具调用/结果的消息序列，将它们格式化为LLM API所需的格式。

Parameters:

消息 (列表[Msg])
is_first (bool) - 是否为首个

Return type:

列表[字典[字符串类型, 任意类型]]

class DashScopeChatFormatter[source]¶

基类: TruncatedFormatterBase

DashScope 消息格式化器.

support_tools_api: bool = True¶: 是否支持工具API

support_multiagent: bool = False¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶

async _format(msgs)[source]¶

将消息对象格式化为DashScope API格式。

Parameters:: msgs (list[Msg]) – 待格式化的消息对象列表。
Returns:: 格式化消息，作为字典列表。
Return type:: list[dict[str, Any]]

class DashScopeMultiAgentFormatter[source]¶

基类: TruncatedFormatterBase

适用于多智能体对话的DashScope格式化器，对话涉及多个用户和智能体。

注意

此格式化器会将之前的消息（除工具调用/结果外）与对话历史提示整合到一个初始系统消息的历史部分中。

注意

对于工具调用/结果，它们将根据DashScope API的要求以单独的消息形式呈现。因此，工具调用/结果消息预计会被放置在输入消息的末尾。

提示

在多智能体对话中，告知智能体名称在系统提示语中非常重要。这样大型语言模型就能知道它正在扮演谁的角色。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的报文块列表

__init__(conversation_history_prompt='# Conversation History\nThe content between <history></history> tags contains your conversation history\n', token_counter=None, max_tokens=None)[source]¶

初始化DashScope多智能体格式化器。

Parameters:

conversation_history_prompt (str) – 对话历史部分使用的提示词。
token_counter (TokenCounterBase | None, optional) – 用于截断处理的token计数器。
max_tokens (int | None, optional) – 格式化消息中允许的最大token数量。若为None，则不进行截断。

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一系列工具调用/结果消息，将它们格式化为DashScope API所需的格式。

Parameters:: 消息列表（list[Msg]）– 待格式化的包含工具调用/结果的消息列表。
Returns:: 为 DashScope API 格式化的字典列表。
Return type:: list[dict[str, Any]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定一个没有工具调用/结果的消息序列，将它们格式化为包含对话历史标记的用户消息。对于第一个智能体消息，它将包含对话历史提示。

Parameters:

msgs (list[Msg]) – 一个需要被格式化的 Msg 对象列表。
is_first (bool, 默认为 True) – 这是否为会话中的第一条智能体消息。如果是 True，则会包含会话历史提示。

Returns:

为DashScope API格式化的字典列表。

Return type:

list[dict[str, Any]]

class OpenAIChatFormatter[source]¶

基础类: TruncatedFormatterBase

用于将消息对象格式化成OpenAI API所需格式的类。

support_tools_api: bool = True¶: 是否支持工具API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉模型

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: OpenAI API支持的消息区块

async _format(msgs)[source]¶

将消息对象格式化为OpenAI API所需的格式。

Parameters:: msgs (list[Msg]) – 待格式化的Msg对象列表。
Returns:: 一个字典列表，其中每个字典包含 "name"、"role" 和 "content" 键。
Return type:: list[dict[str, Any]]

class OpenAIMultiAgentFormatter[source]¶

基类: TruncatedFormatterBase

OpenAI多智能体对话格式化器，涉及多个用户和智能体。 .. 提示:: 该格式化器兼容OpenAI API以及vLLM、Azure OpenAI等OpenAI兼容服务。

support_tools_api: bool = True¶: 是否支持工具API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉模型

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: OpenAI API 所支持的消息区块

初始化 OpenAI 多智能体格式化程序。

Parameters:

conversation_history_prompt (str) – 用于对话历史部分的提示词。
token_counter (TokenCounterBase | None)
max_tokens (int | None)

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一系列工具调用/结果消息，将它们格式化为OpenAI API所需的格式。

Parameters:: msgs (列表[Msg])
Return type:: 列表[字典[字符串类型, 任意类型]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定一个没有工具调用或结果的消息序列，将其格式化为OpenAI API所需的格式。

Parameters:

msgs (列表[Msg])
is_first (bool)

Return type:

列表[字典[字符串类型, 任意类型]]

class AnthropicChatFormatter[source]¶

基类: TruncatedFormatterBase

Anthropic 消息格式化器。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = False¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

async _format(msgs)[source]¶

将消息对象格式化为Anthropic API格式。

Parameters:: msgs (list[Msg]) – 待格式化的消息对象列表。
Returns:: 格式化消息，作为字典列表。
Return type:: list[dict[str, Any]]

注意

Anthropic 建议始终将所有先前的思维区块传递给后续调用的 API，以保持推理连续性。更多详细信息，请参考 Anthropic’s documentation。

class AnthropicMultiAgentFormatter[source]¶

基础类: TruncatedFormatterBase

Anthropic 针对多智能体对话的格式化工具，适用于涉及多个用户和智能体的场景。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的报文块列表

初始化DashScope多智能体格式化器。

Parameters:

conversation_history_prompt (str) – 用于对话历史部分的提示词。
token_counter (TokenCounterBase | None)
max_tokens (int | None)

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一个工具调用/结果消息序列，将其格式化为Anthropic API所需的格式。

Parameters:: 消息列表 (列表[Msg])
Return type:: 列表[字典[字符串类型, 任意类型]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定没有工具调用/结果的消息序列，将其格式化为Anthropic API要求的格式。

Parameters:

msgs (list[Msg]) - 消息列表 (列表[消息对象])
is_first (bool) - 是否为第一个

Return type:

列表[字典[字符串类型, 任意类型]]

class GeminiChatFormatter[source]¶

基础类: TruncatedFormatterBase

Google Gemini API的格式化器。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = False¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.VideoBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的报文块列表

supported_extensions: dict[str, list[str]] = {'audio': ['mp3', 'wav', 'aiff', 'aac', 'ogg', 'flac'], 'image': ['png', 'jpeg', 'webp', 'heic', 'heif'], 'video': ['mp4', 'mpeg', 'mov', 'avi', 'x-flv', 'mpg', 'webm', 'wmv', '3gpp']}¶

async _format(msgs)[source]¶

将消息对象格式化为Gemini API所需的格式。

Parameters:: 消息列表 (列表[Msg])
Return type:: 列表[字典]

class GeminiMultiAgentFormatter[source]¶

基础类: TruncatedFormatterBase

Google Gemini API的多智能体格式化工具，涉及不止一个用户和智能体。

注意

此格式化器会将之前的消息（除工具调用/结果外）与对话历史提示整合到一个初始系统消息的历史部分中。

注意

对于工具调用/结果，根据Gemini API的要求，它们将作为独立消息展示。因此，工具调用/结果消息预期被放置在输入消息的末尾。

提示

在多智能体对话中，告知智能体名称在系统提示语中非常重要。这样大型语言模型就能知道它正在扮演谁的角色。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.VideoBlock'>, <class 'agentscope.message._message_block.AudioBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

初始化 Gemini 多智能体格式化工具。

Parameters:

conversation_history_prompt (str) – 用于对话历史部分的提示词。
token_counter (TokenCounterBase | None, optional) – 用于截断的token计数器。
max_tokens (int | None, 可选) – 格式化消息中允许的最大标记数。如果为None，则不进行截断。

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一个工具调用/结果消息序列，将它们格式化为Gemini API所需的格式。

Parameters:: 消息列表（list[Msg]）– 待格式化的包含工具调用/结果的消息列表。
Returns:: 适用于Gemini API的字典列表格式。
Return type:: list[dict[str, Any]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定不包含工具调用/结果的消息序列，将其格式化为Gemini API所需的格式。

Parameters:

msgs (list[Msg]) – 待格式化的 Msg 对象列表。
is_first (bool, defaults to True) - 这是否为对话中的第一条智能体消息。如果为True，则会包含对话历史记录提示。

Returns:

适用于 Gemini API 的字典列表格式。

Return type:

list[dict[str, Any]]

class OllamaChatFormatter[source]¶

基础类: TruncatedFormatterBase

Ollama 消息的格式化工具。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = False¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

async _format(msgs)[source]¶

将消息对象格式化为 Ollama API 格式。

Parameters:: msgs (list[Msg]) – 待格式化的消息对象列表。
Returns:: 格式化消息，作为字典列表。
Return type:: list[dict[str, Any]]

class OllamaMultiAgentFormatter[source]¶

基础类: TruncatedFormatterBase

用于多智能体对话的Ollama格式化工具，适用于涉及多用户和多智能体的场景。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = True¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ImageBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

初始化 Ollama 多智能体格式化工具。

Parameters:

conversation_history_prompt (str) – 用于对话历史记录部分的提示符。
token_counter (TokenCounterBase | None, optional) – 用于截断的token计数器。
max_tokens (int | None, optional) – 格式化消息中允许的最大token数量。如果为None，则不进行截断。

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一组工具调用/结果消息序列，将它们格式化为Ollama API所需的格式。

Parameters:: 消息列表（list[Msg]）– 待格式化的包含工具调用/结果的消息列表。
Returns:: 为Ollama API格式化的字典列表。
Return type:: list[dict[str, Any]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定一个不包含工具调用/结果的消息序列，将其格式化为 Ollama API 所需的格式。

Parameters:

msgs (list[Msg]) – 要格式化的Msg对象列表。
is_first (bool, 默认为 True) – 这是否是会话中的首条智能体消息。如果为 True，将包含会话历史提示。

Returns:

一个为ollama API格式化的字典列表。

Return type:

list[dict[str, Any]]

class DeepSeekChatFormatter[source]¶

基础类: TruncatedFormatterBase

DeepSeek消息的格式化器。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = False¶: 是否支持多智能体对话

support_vision: bool = False¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

async _format(msgs)[source]¶

将消息对象格式化为DeepSeek API格式。

Parameters:: msgs (list[Msg]) – 待格式化的消息对象列表。
Returns:: 格式化消息，作为字典列表。
Return type:: list[dict[str, Any]]

class DeepSeekMultiAgentFormatter[source]¶

基础类: TruncatedFormatterBase

DeepSeek多智能体对话格式化工具，场景涉及多个用户和智能体。

support_tools_api: bool = True¶: 是否支持工具 API

support_multiagent: bool = True¶: 是否支持多智能体对话

support_vision: bool = False¶: 是否支持视觉数据

supported_blocks: list[type] = [<class 'agentscope.message._message_block.TextBlock'>, <class 'agentscope.message._message_block.ToolUseBlock'>, <class 'agentscope.message._message_block.ToolResultBlock'>]¶: 支持的消息区块列表

初始化 DeepSeek 多智能体格式化器。

Parameters:

conversation_history_prompt (str) – 用于对话历史记录部分的提示符。
token_counter (TokenCounterBase | None, 可选) – 一个用来计算消息中令牌数量的令牌计数器实例。如果未提供，格式化器将会在不考虑令牌限制的情况下格式化消息。
max_tokens (int | None, optional) – 格式化消息中允许的最大token数。若未提供，格式化程序将不会截断消息。

Return type:

无

async _format_tool_sequence(msgs)[source]¶

给定一系列工具调用/结果消息，将它们格式化为DeepSeek API所需的格式。

Parameters:: 消息列表（list[Msg]）– 待格式化的包含工具调用/结果的消息列表。
Returns:: 为DeepSeek API格式化后的字典列表。
Return type:: list[dict[str, Any]]

async _format_agent_message(msgs, is_first=True)[source]¶

给定一个不包含工具调用/结果的消息序列，将其格式化为DeepSeek API所需的格式。

Parameters:

msgs (list[Msg]) – 待格式化的Msg对象列表。
is_first (bool, defaults to True) – 这是否为会话中的首条智能体消息。如果为True，将包含对话历史记录提示。

Returns:

用于DeepSeek API的字典列表。

Return type:

list[dict[str, Any]]