类class io.agentscope.core.tool 2.x

ToolRegistration

public static class ToolRegistration

源码Source io/agentscope/core/tool/Toolkit.java:981–1281

工具注册，让智能体以受控方式调用外部能力。位于 io.agentscope.core.tool 包。核心成员包括 tool、agentTool、mcpClient、subAgent、mcpToolNamePrefix、enableTools。

Fluent builder for registering tools with optional configuration.

This builder provides a clear, type-safe way to register tools with various options without method proliferation.

方法摘要Method Summary

方法Method	说明Description
`public` `ToolRegistration tool(Object toolObject)`	设置工具。 Set the tool object to register (scans for @Tool methods).
`public` `ToolRegistration agentTool(AgentTool agentTool)`	设置AgentTool 实例到注册。 Set the AgentTool instance to register.
`public` `ToolRegistration mcpClient(McpClientWrapper mcpClientWrapper)`	设置MCP 客户端到注册。 Set the MCP client to register.
`public` `ToolRegistration subAgent(SubAgentProvider<?> provider)`	设置子智能体。 Register a sub-agent as a tool with default configuration.
`public` `ToolRegistration subAgent(SubAgentProvider<?> provider, SubAgentConfig config)`	执行子智能体相关操作。 Register a sub-agent as a tool with custom configuration.
`public` `ToolRegistration mcpToolNamePrefix(String prefix)`	设置该参数。 Optional namespace for model-facing MCP tool names; wire names remain unchanged.
`public` `ToolRegistration enableTools(List<String> enableTools)`	启用工具。 Selects remote tool names; an absent or empty list enables all tools.
`public` `ToolRegistration disableTools(List<String> disableTools)`	设置列出的工具到禁用来自 MCP 客户端。 Set the list of tools to disable from the MCP client.
`public` `ToolRegistration propagateMeta(boolean propagateMeta)`	设置该参数。 Controls whether request metadata is propagated to the MCP server registered through this builder.
`public` `ToolRegistration propagateMeta(String toolName, boolean propagateMeta)`	执行 `propagateMeta` 方法。 Controls request metadata propagation for a single MCP tool of this client.
`public` `ToolRegistration group(String groupName)`	设置工具组名称。 Set the tool group name.
`public` `ToolRegistration presetParameters(Map<String, Map<String, Object>> presetParameters)`	设置该参数。 Set preset parameters that will be automatically injected during tool execution.
`public` `ToolRegistration extendedModel(ExtendedModel extendedModel)`	设置该参数。 Set the extended model for dynamic schema extension.
`public void apply()`	执行 `apply` 方法。 Apply the registration with all configured options.

方法详情Method Detail

tool

public ToolRegistration tool(Object toolObject)

设置工具。

Set the tool object to register (scans for @Tool methods).

参数Parameters

名称Name	类型Type	说明Description
`toolObject`	Object	工具对象（类型 `Object`）。Object containing @Tool annotated methods

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1007–1010

agentTool

public ToolRegistration agentTool(AgentTool agentTool)

设置AgentTool 实例到注册。

Set the AgentTool instance to register.

参数Parameters

名称Name	类型Type	说明Description
`agentTool`	AgentTool	AgentTool 实例。The AgentTool instance

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1018–1021

mcpClient

public ToolRegistration mcpClient(McpClientWrapper mcpClientWrapper)

设置MCP 客户端到注册。

Set the MCP client to register.

参数Parameters

名称Name	类型Type	说明Description
`mcpClientWrapper`	McpClientWrapper	MCP 客户端包装器。The MCP client wrapper

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1029–1032

subAgent

public ToolRegistration subAgent(SubAgentProvider<?> provider)

设置子智能体。

参数Parameters

名称Name	类型Type	说明Description
`provider`	SubAgentProvider<?>	提供者（类型 `SubAgentProvider`）。Factory for creating agent instances (called for each invocation)

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1054–1056

subAgent

public ToolRegistration subAgent(SubAgentProvider<?> provider, SubAgentConfig config)

执行子智能体相关操作。

另见See also @see SubAgentConfig, @see SubAgentConfig#defaults()

参数Parameters

名称Name	类型Type	说明Description
`provider`	SubAgentProvider<?>	提供者（类型 `SubAgentProvider`）。Factory for creating agent instances (called for each session)
`config`	SubAgentConfig	配置对象（类型 `SubAgentConfig`）。Configuration for the sub-agent tool, or null to use defaults (tool name derived from agent name, InMemoryAgentStateStore for state, events forwarded)

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1098–1102

mcpToolNamePrefix

public ToolRegistration mcpToolNamePrefix(String prefix)

设置该参数。

Optional namespace for model-facing MCP tool names; wire names remain unchanged.

参数Parameters

名称Name	类型Type	说明Description
`prefix`	String	prefix（类型 `String`）。The prefix.

返回Returns ToolRegistration

返回ToolRegistration。Returns tool registration.

源码Source io/agentscope/core/tool/Toolkit.java:1105–1108

enableTools

public ToolRegistration enableTools(List<String> enableTools)

启用工具。

Selects remote tool names; an absent or empty list enables all tools.

参数Parameters

名称Name	类型Type	说明Description
`enableTools`	List<String>	启用工具（类型 `List`）。The enable tools.

返回Returns ToolRegistration

返回ToolRegistration。Returns tool registration.

源码Source io/agentscope/core/tool/Toolkit.java:1111–1114

disableTools

public ToolRegistration disableTools(List<String> disableTools)

设置列出的工具到禁用来自 MCP 客户端。

Set the list of tools to disable from the MCP client.

参数Parameters

名称Name	类型Type	说明Description
`disableTools`	List<String>	禁用工具（类型 `List`）。List of tool names to disable

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1124–1127

propagateMeta

public ToolRegistration propagateMeta(boolean propagateMeta)

设置该参数。

Controls whether request metadata is propagated to the MCP server registered through this builder.

参数Parameters

名称Name	类型Type	说明Description
`propagateMeta`	boolean	propagate 元数据（类型 `boolean`）。true to propagate metadata, false to omit the `meta` field entirely from tool call requests

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1148–1151

propagateMeta

public ToolRegistration propagateMeta(String toolName, boolean propagateMeta)

执行 propagateMeta 方法。

Controls request metadata propagation for a single MCP tool of this client.

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	远程 MCP 工具名称。the remote MCP tool name
`propagateMeta`	boolean	propagate 元数据（类型 `boolean`）。true to allow metadata propagation for this tool, false to omit the `meta` field from this tool's requests

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if `toolName` is `null` or blank

源码Source io/agentscope/core/tool/Toolkit.java:1179–1185

group

public ToolRegistration group(String groupName)

设置工具组名称。

Set the tool group name.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	组名称（类型 `String`）。The group name (null for ungrouped)

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1193–1196

presetParameters

public ToolRegistration presetParameters(Map<String, Map<String, Object>> presetParameters)

设置该参数。

Set preset parameters that will be automatically injected during tool execution.

参数Parameters

名称Name	类型Type	说明Description
`presetParameters`	Map<String, Map<String, Object>>	preset 参数（类型 `Map >`）。Map from tool name to its preset parameters

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1214–1218

extendedModel

public ToolRegistration extendedModel(ExtendedModel extendedModel)

设置该参数。

Set the extended model for dynamic schema extension.

参数Parameters

名称Name	类型Type	说明Description
`extendedModel`	ExtendedModel	extended 模型（类型 `ExtendedModel`）。The extended model

返回Returns ToolRegistration

返回ToolRegistration。This builder for chaining

源码Source io/agentscope/core/tool/Toolkit.java:1226–1229

apply

public void apply()

执行 apply 方法。

Apply the registration with all configured options.

抛出Throws

IllegalStateException 可能抛出 `IllegalStateException`。if set multiple of: tool(), agentTool(), mcpClient(), or subAgent().

源码Source io/agentscope/core/tool/Toolkit.java:1237–1280