agentscope.formatters

The formatter modules for different models.

class AnthropicFormatter[source]

Bases: FormatterBase

The formatter for Anthropic models.

classmethod format_chat(*msgs: Msg | list[Msg] | None) → list[dict][source]

Format the messages in chat scenario, where only one user and one assistant are involved.

Parameters:: msgs (Union[Msg, list[Msg], None]) – The message(s) to be formatted. The None input will be ignored.

classmethod format_multi_agent(*msgs: Msg | list[Msg] | None) → list[dict][source]: Format the messages in multi-agent scenario, where multiple agents are involved.

classmethod format_tools_json_schemas(schemas: dict[str, dict]) → list[dict][source]

Format the JSON schemas of the tool functions to the format that Anthropic API expects. This function will take the parsed JSON schema from agentscope.service.ServiceToolkit as input and return the formatted JSON schema.

Note

An example of the input tool JSON schema

..code-block:: json

{

“bing_search”: {
“type”: “function”, “function”: {

“name”: “bing_search”, “description”: “Search the web using Bing.”, “parameters”: {

“type”: “object”, “properties”: {

“query”: {
“type”: “string”, “description”: “The search query.”,

}

}, “required”: [“query”],

}

}

}

}

The formatted JSON schema will be like:

..code-block:: json

[

{
“name”: “bing_search”, “description”: “Search the web using Bing.”, “input_schema”: {

“type”: “object”, “properties”: {

“query”: {
“type”: “string”, “description”: “The search query.”,

}

}, “required”: [“query”],

}

}

]

Parameters:: schemas (dict[str, dict]) – The JSON schema of the tool functions, where the key is the function name, and the value is the schema.
Returns:: The formatted JSON schema.
Return type:: list[dict]

supported_model_regexes: list[str] = ['claude-3-5.*', 'claude-3-7.*']: The supported model regexes

class CommonFormatter[source]

Bases: FormatterBase

The formatter for common model APIs, e.g. ZhipuAI API, DashScope API, etc.

classmethod format_chat(*msgs: Msg | list[Msg] | None, require_alternative: bool = False, require_user_last: bool = False) → list[dict][source]

Format the messages for common LLMs in chat scenario, where only user and assistant are involved.

When require_alternative or require_user_last is set to True, but the input messages do not meet the requirement, we will use the strategy in format_multi_agent_for_common_models instead, which gather all messages into one system message(if provided) and one user message.

Parameters:

msgs (Union[Msg, list[Msg], None]) – The message(s) to be formatted. The None input will be ignored.
require_alternative (bool, optional) – If the model API requires the roles to be “user” and “model” alternatively.
require_user_last (bool, optional) – Whether the user message should be placed at the end. Defaults to False.

classmethod format_multi_agent(*msgs: Msg | list[Msg] | None) → list[dict][source]: Format the multi-agent messages, where more than two agents are involved.

classmethod is_supported_model(model_name: str) → bool[source]: Check if the model is supported by the formatter.

class DashScopeFormatter[source]

Bases: FormatterBase

The DashScope formatter, which is responsible for formatting messages, JSON schemas description of the tool functions.

classmethod format_chat(*msgs: Msg | list[Msg] | None) → list[dict][source]

Format the messages in chat scenario, where only one user and one assistant are involved.

The current format function supports:

[x] image
[x] audio
[x] text
[x] tool_use

classmethod format_multi_agent(*msgs: Msg | list[Msg] | None) → list[dict][source]: Format the messages in multi-agent scenario, where multiple agents are involved.

classmethod format_tools_json_schemas(schemas: dict[str, dict]) → list[dict][source]

Format the JSON schemas of the tool functions to the format that DashScope API expects. This function will take the parsed JSON schema from agentscope.service.ServiceToolkit as input and return the formatted JSON schema.

Note

An example of the input/output tool JSON schema

..code-block:: json

{

“bing_search”: {
“type”: “function”, “function”: {

“name”: “bing_search”, “description”: “Search the web using Bing.”, “parameters”: {

“type”: “object”, “properties”: {

“query”: {
“type”: “string”, “description”: “The search query.”,

}

}, “required”: [“query”],

}

}

}

}

Parameters:: schemas (dict[str, dict]) – The JSON schema of the tool functions.
Returns:: The formatted JSON schema.
Return type:: list[dict]

supported_model_regexes: list[str] = ['qwen-.*']: The supported model regexes

class FormatterBase[source]

Bases: ABC

The base class for formatters.

static check_and_flat_messages(*msgs: Msg | list[Msg] | None) → list[Msg][source]: Check the input messages.

classmethod format_auto(msgs: Msg | list[Msg]) → list[dict][source]

This function will decide which format function to use between format_chat and format_multi_agent based on the roles and names in the input messages.

If only “user” and “assistant” (or “system”) roles are present and

only two names are present, then format_chat will be used.

If more than two names are involved, then format_multi_agent will

be used.

abstract classmethod format_chat(*args: Any, **kwargs: Any) → list[dict][source]: Format the messages in chat scenario, where only one user and one assistant are involved.

abstract classmethod format_multi_agent(*args: Any, **kwargs: Any) → list[dict][source]: Format the messages in multi-agent scenario, where multiple agents are involved.

classmethod format_tools_json_schemas(schemas: dict[str, dict]) → list[dict][source]: Format the JSON schemas of the tool functions to the format that API provider expects.

classmethod is_supported_model(model_name: str) → bool[source]: Check if the provided model_name is supported by the formatter.

supported_model_regexes: list[str]: The supported model regexes

class GeminiFormatter[source]

Bases: FormatterBase

The formatter for Gemini models.

classmethod format_chat(*msgs: Msg | list[Msg] | None) → list[dict][source]: Format the messages in chat scenario, where only a user and an assistant is involved (maybe with system in the beginning).

classmethod format_multi_agent(*msgs: Msg | list[Msg] | None) → list[dict][source]

Format the messages in multi-agent scenario, where multiple agents are involved.

Requirements of Gemini generate API: 1. In Gemini generate_content API, the role field must be either “user” or “model” (In our test, “assistant” also works). 2. If the role of the last message is “model”, the gemini model will treat it as a continuation task.

The above information is updated to 2025/03/14. More information about the Gemini generate_content API can be found in https://googleapis.github.io/python-genai/#

Based on the above considerations, we decide to combine all messages into a single user message. This is a simple and straightforward strategy, if you have any better ideas, pull request and discussion are welcome in our GitHub repository https://github.com/agentscope/agentscope!

supported_model_regexes: list[str] = ['gemini-.*']: The supported model regexes

class OpenAIFormatter[source]

Bases: FormatterBase

The formatter for OpenAI models, which is responsible for formatting messages, JSON schemas description of the tool functions.

classmethod format_chat(*msgs: Msg | list[Msg] | None) → list[dict][source]

Format the messages in chat scenario, where only one user and one assistant are involved.

For OpenAI models, the name field can be used to distinguish different agents (even with the same role as “assistant”). So we simply reuse the format_multi_agent here.

classmethod format_multi_agent(*msgs: Msg | list[Msg] | None) → list[dict][source]

Format the messages in multi-agent scenario, where multiple agents are involved.

For OpenAI models, the name field can be used to distinguish different agents (even with the same role as “assistant”).

classmethod format_tools_json_schemas(schemas: dict[str, dict]) → list[dict][source]

Format the JSON schemas of the tool functions to the format that OpenAI API expects. This function will take the parsed JSON schema from agentscope.service.ServiceToolkit as input and return the formatted JSON schema.

Note

An example of the input tool JSON schema

..code-block:: json

{

“bing_search”: {
“type”: “function”, “function”: {

“name”: “bing_search”, “description”: “Search the web using Bing.”, “parameters”: {

“type”: “object”, “properties”: {

“query”: {
“type”: “string”, “description”: “The search query.”,

}

}, “required”: [“query”],

}

}

}

}

Parameters:: schemas (dict[str, dict]) – The JSON schema of the tool functions.
Returns:: The formatted JSON schema.
Return type:: list[dict]

supported_model_regexes: list[str] = ['gpt-.*', 'o1', 'o1-mini', 'o3-mini']: The supported model regexes