类class agentscope.formatter

FormatterBase

class FormatterBase(BaseModel)

源码Source agentscope/formatter/_formatter_base.py:20–231

FormatterBase 负责把 Msg 列表转换成供应商请求，并把供应商响应解析回统一的 ChatResponse。它隔离了不同模型在工具、多模态和角色编码上的差异。位于 agentscope.formatter 包。核心成员包括 format、assert_list_of_msgs、convert_tool_result_to_string、supported_input_media_types。

The base class for formatters. Declared in agentscope.formatter.

核心精讲Deep dive

FormatterBase：消息与协议转换FormatterBase: message and protocol conversion

FormatterBase 负责把 Msg 列表转换成供应商请求，并把供应商响应解析回统一的 ChatResponse。它隔离了不同模型在工具、多模态和角色编码上的差异。

FormatterBase converts a list of Msg objects into provider requests and parses provider responses back into ChatResponse. It isolates differences in tool, multimodal and role encoding across models.

format 是核心钩子；assert_list_of_msgs 负责输入校验。format is the core hook; assert_list_of_msgs validates the input.
convert_tool_result_to_string 统一工具结果的多模态表示。convert_tool_result_to_string normalizes multimodal tool results.
每个模型通常自带默认 formatter，也可以在构造时注入自定义实现。Each model ships a default formatter, and a custom implementation can be injected at construction time.

自定义纯文本 formatterA minimal plain-text formatter

from agentscope.formatter import FormatterBase
from agentscope.message import Msg


class PlainFormatter(FormatterBase):
    async def format(self, msgs: list[Msg], **kwargs: object) -> list[dict]:
        self.assert_list_of_msgs(msgs)
        return [
            {"role": msg.role, "content": msg.get_text_content()}
            for msg in msgs
        ]

属性摘要Property Summary

属性Property	说明Description
`supported_input_media_types`	读取 `supported_input_media_types` 属性。 Derive the accepted media-type patterns from :attr:`input_types` by excluding ``text/plain`` and ``application/x-thinking``.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`input_types`	list[str]	输入类型字段。	Field(default_factory=lambda: ['text/plain'], description="The supported input types, aligned with the model card's ``input_types`` field. Entries other than ``text/plain`` and ``application/x-thinking`` are treated as media-type patterns (glob-style, e.g. ``image/*``, ``audio/mp3``) that control which ``DataBlock``\\s are forwarded to the API.")

方法摘要Method Summary

方法Method	说明Description
`async def format(args: Any, *kwargs: Any) -> list[dict[str, Any]]`asyncabstractabstractmethod	把消息列表转换为供应商请求格式。 Format the Msg objects to a list of dictionaries that satisfy the API requirements.
`def assert_list_of_msgs(msgs: list[Msg]) -> None`	校验输入是否为 Msg 列表。 Assert that the input is a list of Msg objects.
`def convert_tool_result_to_string(output: str \| List[TextBlock \| DataBlock]) -> tuple[str, list[TextBlock \| DataBlock]]`	把工具结果转换成文本与剩余多模态块。 Turn the tool result list into a textual output to be compatible with the LLM API that doesn't support multimodal data in the tool result.

属性详情Attribute Detail

input_types

list[str] = Field(default_factory=lambda: ['text/plain'], description="The supported input types, aligned with the model card's ``input_types`` field. Entries other than ``text/plain`` and ``application/x-thinking`` are treated as media-type patterns (glob-style, e.g. ``image/*``, ``audio/mp3``) that control which ``DataBlock``\\s are forwarded to the API.")

输入类型字段。声明为 list[str]。

The supported input types, aligned with the model card's input_types field.

源码Source agentscope/formatter/_formatter_base.py:23

属性详情Property Detail

supported_input_media_types

def supported_input_media_types() -> list[str]

读取 supported_input_media_types 属性。

Derive the accepted media-type patterns from :attr:input_types by excluding text/plain and application/x-thinking.

返回Returns list[str]

返回str列表。Returns a list of str.

源码Source agentscope/formatter/_formatter_base.py:37–44

方法详情Method Detail

format

async def format(*args: Any, **kwargs: Any) -> list[dict[str, Any]]

asyncabstractabstractmethod

执行格式相关操作。

Format the Msg objects to a list of dictionaries that satisfy the API requirements.

参数Parameters

名称Name	类型Type	说明Description
`args`	Any	参数（类型 `Any`）。The args.
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns list[dict[str, Any]]

返回dict[str,任意]列表。Returns a list of dict str any.

源码Source agentscope/formatter/_formatter_base.py:47–49

assert_list_of_msgs

def assert_list_of_msgs(msgs: list[Msg]) -> None

设置该参数。

Assert that the input is a list of Msg objects.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	list[Msg]	消息列表（类型 `list[Msg]`）。A list of Msg objects to be validated.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/formatter/_formatter_base.py:52–66

convert_tool_result_to_string

def convert_tool_result_to_string(output: str | List[TextBlock | DataBlock]) -> tuple[str, list[TextBlock | DataBlock]]

转换 convert_tool_result_to_string。

For URL-based images, the URL is included in the list.

参数Parameters

名称Name	类型Type	说明Description
`output`	str \| List[TextBlock \| DataBlock]	输出（类型 `str \| List[TextBlock \| DataBlock]`）。The output of the tool response, including text and multimodal data like images and audio.

返回Returns tuple[str, list[TextBlock | DataBlock]]

返回str,列出[TextBlock|数据块]列表。`tuple[str, list[TextBlock | DataBlock]]`:

源码Source agentscope/formatter/_formatter_base.py:105–187