agentscope.formatter
The formatter module in agentscope.
class FormatterBase[source]
Bases: object
The base class for formatters.
abstract async format(\args, **kwargs*)[source]
Format the Msg objects to a list of dictionaries that satisfy the API requirements.
Parameters:
args (Any)
kwargs (Any)
Return type:
list[dict[str, Any]]
static assert_list_of_msgs(msgs)[source]
Assert that the input is a list of Msg objects.
Parameters:
msgs (list[Msg]) – A list of Msg objects to be validated.
Return type:
None
static convert_tool_result_to_string(output)[source]
Turn the tool result list into a textual output to be compatible with the LLM API that doesn’t support multimodal data.
Parameters:
output (str | List[TextBlock | ImageBlock | AudioBlock]) – The output of the tool response, including text and multimodal data like images and audio.
Returns:
A string representation of the tool result, with text blocks concatenated and multimodal data represented by file paths or URLs.
Return type:
str
class TruncatedFormatterBase[source]
Bases: FormatterBase, ABC
Base class for truncated formatters, which formats input messages into required formats with tokens under a specified limit.
__init__(token_counter=None, max_tokens=None)[source]
Initialize the TruncatedFormatterBase.
Parameters:
token_counter (TokenCounterBase | None, optional) – A token counter instance used to count tokens in the messages. If not provided, the formatter will format the messages without considering token limits.
max_tokens (int | None, optional) – The maximum number of tokens allowed in the formatted messages. If not provided, the formatter will not truncate the messages.
Return type:
None
async format(msgs, \*kwargs*)[source]
Format the input messages into the required format. If token counter and max token limit are provided, the messages will be truncated to fit the limit.
Parameters:
msgs (list[Msg]) – The input messages to be formatted.
kwargs (Any)
Returns:
The formatted messages in the required format.
Return type:
list[dict[str, Any]]
async _format(msgs)[source]
Format the input messages into the required format. This method should be implemented by the subclasses.
Parameters:
msgs (list**[Msg])
Return type:
list[dict[str, Any]]
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the LLM API.
Parameters:
msgs (list**[Msg])
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the LLM API.
Parameters:
msgs (list**[Msg])
is_first (bool)
Return type:
list[dict[str, Any]]
class DashScopeChatFormatter[source]
Bases: TruncatedFormatterBase
Formatter for DashScope messages.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = False
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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]
Format message objects into DashScope API format.
Parameters:
msgs (list[Msg]) – The list of message objects to format.
Returns:
The formatted messages as a list of dictionaries.
Return type:
list[dict[str, Any]]
class DashScopeMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
DashScope formatter for multi-agent conversations, where more than a user and an agent are involved.
Note
This formatter will combine previous messages (except tool calls/results) into a history section in the first system message with the conversation history prompt.
Note
For tool calls/results, they will be presented as separate messages as required by the DashScope API. Therefore, the tool calls/ results messages are expected to be placed at the end of the input messages.
Tip
Telling the assistant’s name in the system prompt is very important in multi-agent conversations. So that LLM can know who it is playing as.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the DashScope multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to use for the conversation history section.
token_counter (TokenCounterBase | None, optional) – The token counter used for truncation.
max_tokens (int | None, optional) – The maximum number of tokens allowed in the formatted messages. If None, no truncation will be applied.
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the DashScope API.
Parameters:
msgs (list[Msg]) – The list of messages containing tool calls/results to format.
Returns:
A list of dictionaries formatted for the DashScope API.
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into a user message with conversation history tags. For the first agent message, it will include the conversation history prompt.
Parameters:
msgs (list[Msg]) – A list of Msg objects to be formatted.
is_first (bool, defaults to True) – Whether this is the first agent message in the conversation. If True, the conversation history prompt will be included.
Returns:
A list of dictionaries formatted for the DashScope API.
Return type:
list[dict[str, Any]]
class OpenAIChatFormatter[source]
Bases: TruncatedFormatterBase
The class used to format message objects into the OpenAI API required format.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversation
support_vision: bool = True
Whether support vision models
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’>]
Supported message blocks for OpenAI API
async _format(msgs)[source]
Format message objects into OpenAI API required format.
Parameters:
msgs (list[Msg]) – The list of Msg objects to format.
Returns:
A list of dictionaries, where each dictionary has “name”, “role”, and “content” keys.
Return type:
list[dict[str, Any]]
class OpenAIMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
OpenAI formatter for multi-agent conversations, where more than a user and an agent are involved. .. tip:: This formatter is compatible with OpenAI API and OpenAI-compatible services like vLLM, Azure OpenAI, and others.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversation
support_vision: bool = True
Whether support vision models
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’>]
Supported message blocks for OpenAI API
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the OpenAI multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to use for the conversation history section.
token_counter (TokenCounterBase | None)
max_tokens (int | None)
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the OpenAI API.
Parameters:
msgs (list**[Msg])
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the OpenAI API.
Parameters:
msgs (list**[Msg])
is_first (bool)
Return type:
list[dict[str, Any]]
class AnthropicChatFormatter[source]
Bases: TruncatedFormatterBase
Formatter for Anthropic messages.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = False
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
async _format(msgs)[source]
Format message objects into Anthropic API format.
Parameters:
msgs (list[Msg]) – The list of message objects to format.
Returns:
The formatted messages as a list of dictionaries.
Return type:
list[dict[str, Any]]
Note
Anthropic suggests always passing all previous thinking blocks back to the API in subsequent calls to maintain reasoning continuity. For more details, please refer to Anthropic’s documentation.
class AnthropicMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
Anthropic formatter for multi-agent conversations, where more than a user and an agent are involved.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the DashScope multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to use for the conversation history section.
token_counter (TokenCounterBase | None)
max_tokens (int | None)
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the Anthropic API.
Parameters:
msgs (list**[Msg])
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the Anthropic API.
Parameters:
msgs (list**[Msg])
is_first (bool)
Return type:
list[dict[str, Any]]
class GeminiChatFormatter[source]
Bases: TruncatedFormatterBase
The formatter for Google Gemini API.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = False
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
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]
Format message objects into Gemini API required format.
Parameters:
msgs (list**[Msg])
Return type:
list[dict]
class GeminiMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
The multi-agent formatter for Google Gemini API, where more than a user and an agent are involved.
Note
This formatter will combine previous messages (except tool calls/results) into a history section in the first system message with the conversation history prompt.
Note
For tool calls/results, they will be presented as separate messages as required by the Gemini API. Therefore, the tool calls/ results messages are expected to be placed at the end of the input messages.
Tip
Telling the assistant’s name in the system prompt is very important in multi-agent conversations. So that LLM can know who it is playing as.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the Gemini multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to be used for the conversation history section.
token_counter (TokenCounterBase | None, optional) – The token counter used for truncation.
max_tokens (int | None, optional) – The maximum number of tokens allowed in the formatted messages. If None, no truncation will be applied.
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the Gemini API.
Parameters:
msgs (list[Msg]) – The list of messages containing tool calls/results to format.
Returns:
A list of dictionaries formatted for the Gemini API.
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the Gemini API.
Parameters:
msgs (list[Msg]) – A list of Msg objects to be formatted.
is_first (bool, defaults to True) – Whether this is the first agent message in the conversation. If True, the conversation history prompt will be included.
Returns:
A list of dictionaries formatted for the Gemini API.
Return type:
list[dict[str, Any]]
class OllamaChatFormatter[source]
Bases: TruncatedFormatterBase
Formatter for Ollama messages.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = False
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
async _format(msgs)[source]
Format message objects into Ollama API format.
Parameters:
msgs (list[Msg]) – The list of message objects to format.
Returns:
The formatted messages as a list of dictionaries.
Return type:
list[dict[str, Any]]
class OllamaMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
Ollama formatter for multi-agent conversations, where more than a user and an agent are involved.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversations
support_vision: bool = True
Whether support vision data
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’>]
The list of supported message blocks
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the Ollama multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to use for the conversation history section.
token_counter (TokenCounterBase | None, optional) – The token counter used for truncation.
max_tokens (int | None, optional) – The maximum number of tokens allowed in the formatted messages. If None, no truncation will be applied.
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the Ollama API.
Parameters:
msgs (list[Msg]) – The list of messages containing tool calls/results to format.
Returns:
A list of dictionaries formatted for the Ollama API.
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the Ollama API.
Parameters:
msgs (list[Msg]) – A list of Msg objects to be formatted.
is_first (bool, defaults to True) – Whether this is the first agent message in the conversation. If True, the conversation history prompt will be included.
Returns:
A list of dictionaries formatted for the ollama API.
Return type:
list[dict[str, Any]]
class DeepSeekChatFormatter[source]
Bases: TruncatedFormatterBase
Formatter for DeepSeek messages.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = False
Whether support multi-agent conversations
support_vision: bool = False
Whether support vision data
supported_blocks: list[type] = [<class ‘agentscope.message._message_block.TextBlock’>, <class ‘agentscope.message._message_block.ToolUseBlock’>, <class ‘agentscope.message._message_block.ToolResultBlock’>]
The list of supported message blocks
async _format(msgs)[source]
Format message objects into DeepSeek API format.
Parameters:
msgs (list[Msg]) – The list of message objects to format.
Returns:
The formatted messages as a list of dictionaries.
Return type:
list[dict[str, Any]]
class DeepSeekMultiAgentFormatter[source]
Bases: TruncatedFormatterBase
DeepSeek formatter for multi-agent conversations, where more than a user and an agent are involved.
support_tools_api: bool = True
Whether support tools API
support_multiagent: bool = True
Whether support multi-agent conversations
support_vision: bool = False
Whether support vision data
supported_blocks: list[type] = [<class ‘agentscope.message._message_block.TextBlock’>, <class ‘agentscope.message._message_block.ToolUseBlock’>, <class ‘agentscope.message._message_block.ToolResultBlock’>]
The list of supported message blocks
__init__(conversation_history_prompt=’# Conversation History\nThe content between <history></history> tags contains your conversation history\n’, token_counter=None, max_tokens=None)[source]
Initialize the DeepSeek multi-agent formatter.
Parameters:
conversation_history_prompt (str) – The prompt to use for the conversation history section.
token_counter (TokenCounterBase | None, optional) – A token counter instance used to count tokens in the messages. If not provided, the formatter will format the messages without considering token limits.
max_tokens (int | None, optional) – The maximum number of tokens allowed in the formatted messages. If not provided, the formatter will not truncate the messages.
Return type:
None
async _format_tool_sequence(msgs)[source]
Given a sequence of tool call/result messages, format them into the required format for the DeepSeek API.
Parameters:
msgs (list[Msg]) – The list of messages containing tool calls/results to format.
Returns:
A list of dictionaries formatted for the DeepSeek API.
Return type:
list[dict[str, Any]]
async _format_agent_message(msgs, is_first=True)[source]
Given a sequence of messages without tool calls/results, format them into the required format for the DeepSeek API.
Parameters:
msgs (list[Msg]) – A list of Msg objects to be formatted.
is_first (bool, defaults to True) – Whether this is the first agent message in the conversation. If True, the conversation history prompt will be included.
Returns:
A list of dictionaries formatted for the DeepSeek API.
Return type:
list[dict[str, Any]]