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 (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

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

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: 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

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

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

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]]