接口interface io.agentscope.core.formatter 2.x

Formatter

public interface Formatter<TReq, TResp, TParams>

源码Source io/agentscope/core/formatter/Formatter.java:55–160

格式化器把 Msg 列表与 GenerateOptions 转换为供应商请求，并把响应解析为 ChatResponse。applyTools 与 applyOptions 负责工具和采样参数的协议映射。位于 io.agentscope.core.formatter 包。核心成员包括 format、parseResponse、applyOptions、applyTools、applyToolChoice。

Formatter interface for converting between AgentScope and provider-specific formats. This is an internal interface used by Model implementations.

Formatters are responsible for: 1. Converting Msg objects to provider-specific request format 2. Converting provider-specific responses back to AgentScope ChatResponse 3. Applying generation options to provider-specific request builders 4. Applying tool schemas to provider-specific request builders

Each formatter is type-safe and handles the exact types expected by the provider's SDK.

Dependency: This interface requires the provider-specific extension module. For DashScope, add the following Maven dependency:

`<dependency>
<groupId>agentscope</groupId>
<artifactId>agentscope-extensions-model-dashscope</artifactId>
<version>${agentscope.version}</version>
</dependency>
`

核心精讲Deep dive

Formatter：请求与响应转换Formatter: request and response conversion

Formatter 把 Msg 列表与 GenerateOptions 转换为供应商请求，并把响应解析为 ChatResponse。applyTools 与 applyOptions 负责工具和采样参数的协议映射。

Formatter converts Msg lists and GenerateOptions into provider requests and parses responses into ChatResponse. applyTools and applyOptions map tools and sampling parameters onto the provider protocol.

format 生成请求消息列表，parseResponse 解析响应与工具调用。format produces request messages, while parseResponse parses responses and tool calls.
applyTools、applyToolChoice 与 applyOptions 处理协议差异。applyTools, applyToolChoice and applyOptions handle protocol differences.
每种模型扩展都提供自己的 ChatFormatter 与 MultiAgentFormatter。Every model extension provides its own ChatFormatter and MultiAgentFormatter.

为模型注入 formatterInject a formatter into a model

import io.agentscope.extensions.model.openai.OpenAIChatModel;
import io.agentscope.extensions.model.openai.formatter.OpenAIChatFormatter;

public class FormatterDemo {
    public static void main(String[] args) {
        OpenAIChatModel model = OpenAIChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4.1-mini")
                .formatter(new OpenAIChatFormatter())
                .build();
        System.out.println(model.getModelName());
    }
}

方法摘要Method Summary

方法Method	说明Description
`public List<TReq> format(List<Msg> msgs)`	把消息列表转换为供应商请求。 Format AgentScope messages to provider-specific request format.
`default public List<TReq> format(List<Msg> msgs, GenerateOptions options)` default	把消息列表转换为供应商请求。 Format AgentScope messages using request-scoped generation options.
`public` `ChatResponse parseResponse(TResp response, Instant startTime)`	把供应商响应解析为 ChatResponse。 Parse provider-specific response to AgentScope ChatResponse.
`public void applyOptions(TParams paramsBuilder,` `GenerateOptions options, GenerateOptions defaultOptions)`	把生成与采样参数写入请求。 Apply generation options to provider-specific request parameters.
`public void applyTools(TParams paramsBuilder, List<ToolSchema> tools)`	把工具模式写入请求参数。 Apply tool schemas to provider-specific request parameters.
`default public void applyTools(TParams paramsBuilder, List<ToolSchema> tools, String baseUrl, String modelName)` default	把工具模式写入请求参数。 Apply tool schemas to provider-specific request parameters with provider compatibility handling.
`default public void applyToolChoice(TParams paramsBuilder,` `ToolChoice toolChoice)` default	应用工具选项。 Apply tool choice configuration to provider-specific request parameters.
`default public void applyToolChoice(TParams paramsBuilder,` `ToolChoice toolChoice, String baseUrl, String modelName)` default	应用工具选项。 Apply tool choice configuration to provider-specific request parameters with provider detection.

方法详情Method Detail

format

public List<TReq> format(List<Msg> msgs)

设置格式。

Format AgentScope messages to provider-specific request format.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	AgentScope 消息的列出。List of AgentScope messages

返回Returns List<TReq>

返回列出。List of provider-specific request messages

源码Source io/agentscope/core/formatter/Formatter.java:63

format

default public List<TReq> format(List<Msg> msgs, GenerateOptions options)

default

执行格式相关操作。

Format AgentScope messages using request-scoped generation options.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	AgentScope 消息的列出。list of AgentScope messages
`options`	GenerateOptions	选项（类型 `GenerateOptions`）。request-scoped generation options; may be `null`

返回Returns List<TReq>

返回列出。list of provider-specific request messages

源码Source io/agentscope/core/formatter/Formatter.java:76–78

parseResponse

public ChatResponse parseResponse(TResp response, Instant startTime)

解析响应。

Parse provider-specific response to AgentScope ChatResponse.

参数Parameters

名称Name	类型Type	说明Description
`response`	TResp	响应（类型 `TResp`）。Provider-specific response object
`startTime`	Instant	启动时间（类型 `Instant`）。Request start time for calculating duration

返回Returns ChatResponse

返回ChatResponse。AgentScope ChatResponse

源码Source io/agentscope/core/formatter/Formatter.java:87

applyOptions

public void applyOptions(TParams paramsBuilder, GenerateOptions options, GenerateOptions defaultOptions)

应用选项。

Apply generation options to provider-specific request parameters.

参数Parameters

名称Name	类型Type	说明Description
`paramsBuilder`	TParams	参数构建器（类型 `TParams`）。Provider-specific request parameters builder
`options`	GenerateOptions	选项（类型 `GenerateOptions`）。Generation options to apply
`defaultOptions`	GenerateOptions	默认选项（类型 `GenerateOptions`）。Default options to use if options parameter is null

源码Source io/agentscope/core/formatter/Formatter.java:96–97

applyTools

public void applyTools(TParams paramsBuilder, List<ToolSchema> tools)

应用工具。

Apply tool schemas to provider-specific request parameters.

参数Parameters

名称Name	类型Type	说明Description
`paramsBuilder`	TParams	参数构建器（类型 `TParams`）。Provider-specific request parameters builder
`tools`	List<ToolSchema>	工具列表（类型 `List`）。List of tool schemas to apply (may be null or empty)

源码Source io/agentscope/core/formatter/Formatter.java:105

applyTools

default public void applyTools(TParams paramsBuilder, List<ToolSchema> tools, String baseUrl, String modelName)

default

应用工具。

Apply tool schemas to provider-specific request parameters with provider compatibility handling.

参数Parameters

名称Name	类型Type	说明Description
`paramsBuilder`	TParams	参数构建器（类型 `TParams`）。Provider-specific request parameters builder
`tools`	List<ToolSchema>	工具列表（类型 `List`）。Tool schemas to apply (may be null or empty)
`baseUrl`	String	基类 URL（类型 `String`）。API base URL for provider detection (null for default)
`modelName`	String	模型名称（类型 `String`）。Model name for provider detection fallback (null)

源码Source io/agentscope/core/formatter/Formatter.java:121–125

applyToolChoice

default public void applyToolChoice(TParams paramsBuilder, ToolChoice toolChoice)

default

应用工具选项。

Apply tool choice configuration to provider-specific request parameters.

参数Parameters

名称Name	类型Type	说明Description
`paramsBuilder`	TParams	参数构建器（类型 `TParams`）。Provider-specific request parameters builder
`toolChoice`	ToolChoice	工具选项（类型 `ToolChoice`）。Tool choice configuration (null means provider default)

源码Source io/agentscope/core/formatter/Formatter.java:136–139

applyToolChoice

default public void applyToolChoice(TParams paramsBuilder, ToolChoice toolChoice, String baseUrl, String modelName)

default

应用工具选项。

Apply tool choice configuration to provider-specific request parameters with provider detection.

参数Parameters

名称Name	类型Type	说明Description
`paramsBuilder`	TParams	参数构建器（类型 `TParams`）。Provider-specific request parameters builder
`toolChoice`	ToolChoice	工具选项（类型 `ToolChoice`）。Tool choice configuration (null means provider default)
`baseUrl`	String	基类 URL（类型 `String`）。API base URL for provider detection (null for default)
`modelName`	String	模型名称（类型 `String`）。Model name for provider detection fallback (null)

源码Source io/agentscope/core/formatter/Formatter.java:155–159