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

Toolkit

public class Toolkit

源码Source io/agentscope/core/tool/Toolkit.java:70–1282

工具包扫描 @工具注解方法，把 Java 方法转换成模型工具模式，并负责工具查找、分组、MCP 注册与权限元数据。位于 io.agentscope.core.tool 包。核心成员包括 registration、registerTool、registerAgentTool、getTool、getToolNames、registerSchema。

Toolkit manages the registration, retrieval, and execution of agent tools. This class acts as a facade, delegating specific responsibilities to specialized managers:

Managers:

ToolRegistry: Tool registration and lookup
ToolGroupManager: Tool group CRUD operations and active group management
ToolSchemaProvider: Tool schema generation with group filtering
McpClientManager: MCP client lifecycle and tool registration
MetaToolFactory: Creates meta tools for dynamic group control

Core Components:

ToolSchemaGenerator: Generates JSON schemas for tool parameters
ToolMethodInvoker: Handles method invocation and parameter conversion
ToolResultConverter: Converts method results to ToolResultBlock
ToolExecutor: Handles parallel/sequential tool execution with validation

Features:

Tool group management for dynamic tool activation
State management via StateModule interface (activeGroups persistence)
Meta tool for runtime tool group control (reset_equipped_tools)
MCP (Model Context Protocol) client support for external tool providers

核心精讲Deep dive

Toolkit：工具注册表Toolkit: the tool registry

Toolkit 扫描 @Tool 注解方法，把 Java 方法转换成模型工具 schema，并负责工具查找、分组、MCP 注册与权限元数据。

Toolkit scans @Tool-annotated methods, converts Java methods into model tool schemas, and handles lookup, grouping, MCP registration and permission metadata.

registerTool 扫描对象上的 @Tool 方法，@ToolParam 描述参数。registerTool scans @Tool methods on an object, with @ToolParam describing parameters.
registerSchema 用于手工注册已有 JSON Schema 的工具。registerSchema registers tools from existing JSON schemas.
registerMcpClient 把 MCP 工具批量纳入注册表，closeMcpClients 统一释放。registerMcpClient adds MCP tools in bulk, and closeMcpClients releases them together.

用注解注册工具Register tools with annotations

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;

public class ToolkitDemo {
    static final class WeatherTools {
        @Tool(name = "get_weather", description = "Return the current weather for a city.")
        public String getWeather(
                @ToolParam(name = "city", description = "City name, e.g. Hangzhou") String city) {
            return city + ": sunny, 24C";
        }
    }

    public static void main(String[] args) {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new WeatherTools());
        System.out.println(toolkit.getToolNames());
    }
}

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`ToolRegistration`	类class	工具注册，让智能体以受控方式调用外部能力。 Fluent builder for registering tools with optional configuration.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `Toolkit()`	创建空工具注册表。 Create a Toolkit with default configuration (parallel execution using Reactor).
`public` `Toolkit(ToolkitConfig config)`	创建空工具注册表。 Create a Toolkit with custom configuration.

方法摘要Method Summary

方法Method	说明Description
`public` `ToolRegistration registration()`	返回注册。 Create a fluent builder for registering tools with optional configuration.
`public void registerTool(Object toolObject)`	扫描并注册对象上的 @工具方法。 Register a tool object by scanning for methods annotated with @Tool.
`public void registerAgentTool(AgentTool tool)`	注册一个 AgentTool 实例。 Register an AgentTool instance directly.
`public` `AgentTool getTool(String name)`	按名称查找工具。 Retrieves a tool by its name.
`public` `AgentTool getTool(String name, ToolRequestConfig requestConfig)`	按名称查找工具。 Resolve a tool by name, composing a per-call `ToolRequestConfig` with the shared registry (never mutating either).
`public Set<String> getToolNames()`	获取 `getToolNames`。 Gets the names of all registered tools.
`public void registerSchema(ToolSchema schema)`	注册已有 JSON 模式的工具。 Register an external tool using only its schema definition.
`public void registerSchemas(List<ToolSchema> schemas)`	批量注册工具模式。 Register multiple external tools using their schema definitions.
`public boolean isExternalTool(String toolName)`	判断是否外部工具。 Check if a tool is an external tool (requires execution outside the framework).
`public boolean isExternalTool(String toolName,` `ToolRequestConfig requestConfig)`	判断是否外部工具。 Check whether `toolName` resolves to an external tool under a per-call `ToolRequestConfig`.
`public List<ToolSchema> getToolSchemas()`	返回模型可读的工具模式。 Get tool schemas as ToolSchema objects.
`public List<ToolSchema> getToolSchemas(Collection<String> activeGroups)`	返回模型可读的工具模式。 Get tool schemas filtered by an explicitly supplied set of active group names, independent of this toolkit's shared per-group activation flags.
`public List<ToolSchema> getToolSchemas(Collection<String> activeGroups, ToolRequestConfig requestConfig)`	返回模型可读的工具模式。 Stateless compose: the backend registry filtered by `activeGroups`, then a per-call `ToolRequestConfig` applied without mutating the shared registry or group manager.
`public void setChunkCallback(BiConsumer<ToolUseBlock, ToolResultBlock> callback)`	设置分块回调。 Set the chunk callback for streaming tool responses.
`public Mono<ToolResultBlock> callTool(ToolCallParam param)`	调用工具。 Execute a tool with the given parameters.
`public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext)`	调用工具。 Execute multiple tools asynchronously with agent-level context (internal use by ReActAgent).
`public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext, BiConsumer<ToolUseBlock, ToolResultBlock> internalChunkCallback)`	调用工具。 Execute multiple tools with request configuration from the runtime context and a per-call chunk callback.
`public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext, ToolRequestConfig requestConfig, BiConsumer<ToolUseBlock, ToolResultBlock> internalChunkCallback)`	调用工具。 Execute multiple tools with a per-call `ToolRequestConfig` and internal chunk callback, both threaded down to every single-tool execution.
`public Mono<Void> registerMcpClient(McpClientWrapper mcpClientWrapper)`	把 MCP 客户端提供的工具批量注册。 Registers an MCP client and all its tools.
`public Mono<Void> removeMcpClient(String mcpClientName)`	移除MCP 客户端。 Removes an MCP client and all its tools.
`public void closeMcpClients()`	关闭全部已注册的 MCP 客户端。 Releases clients registered by this toolkit.
`public void createToolGroup(String groupName, String description, boolean active)`	创建工具组。 Create a new tool group with specified activation status and default META scope.
`public void createToolGroup(String groupName, String description, boolean active,` `ToolGroupScope scope)`	创建工具组。 Create a new tool group with specified activation status and scope.
`public void createToolGroup(String groupName, String description)`	创建工具组。 Create a new tool group (active by default, META scope).
`public void createSkillToolGroup(String groupName, String description, boolean active, String activateOnSkill)`	创建技能工具组。 Create a `SkillToolGroup` bound to a specific skill.
`public List<String> findSkillToolGroupsByActivateOnSkill(String skillName)`	查找 `findSkillToolGroupsByActivateOnSkill`。 Find all `SkillToolGroup` instances whose `activateOnSkill` matches the given skill name.
`public void registerToolGroup(ToolGroup group)`	注册工具组。 Register a pre-built `ToolGroup` instance (including subclasses).
`public void addToolToGroup(String groupName, String toolName)`	添加工具到组。 Add an already-registered tool to an existing tool group.
`public void updateToolGroups(List<String> groupNames, boolean active)`	更新工具组。 Update the activation status of tool groups.
`public void removeTool(String toolName)`	移除工具。 Remove a tool by name from the toolkit.
`public boolean removeToolIfSame(String toolName,` `AgentTool expected)`	移除 `removeToolIfSame`。 Atomically remove a tool only if the registered instance is the expected one.
`public void removeToolGroups(List<String> groupNames)`	移除工具组。 Remove tool groups and all tools within them.
`public List<String> getActiveGroups()`	获取 `getActiveGroups`。 Get active tool group names.
`public void setActiveGroups(List<String> groups)`	设置 `setActiveGroups`。 Set the active tool groups.
`public` `ToolGroup getToolGroup(String groupName)`	获取工具组通过名称。 Get a tool group by name.
`public void registerMetaTool()`	注册元数据工具。 Register the meta tool that allows agents to dynamically manage tool groups.
`public void updateToolPresetParameters(String toolName, Map<String, Object> newPresetParameters)`	更新 `updateToolPresetParameters`。 Update preset parameters for a registered tool at runtime.
`public` `Toolkit copy()`	返回 `copy` 结果。 Creates a build-time isolation copy of this toolkit.

构造器详情Constructor Detail

Toolkit

public Toolkit()

初始化 Toolkit 实例。

Create a Toolkit with default configuration (parallel execution using Reactor).

源码Source io/agentscope/core/tool/Toolkit.java:88–90

Toolkit

public Toolkit(ToolkitConfig config)

创建工具包使用自定义配置。

Create a Toolkit with custom configuration.

参数Parameters

名称Name	类型Type	说明Description
`config`	ToolkitConfig	配置对象（类型 `ToolkitConfig`）。Toolkit configuration (if null, uses defaultConfig())

源码Source io/agentscope/core/tool/Toolkit.java:97–122

方法详情Method Detail

registration

public ToolRegistration registration()

返回注册。

Create a fluent builder for registering tools with optional configuration.

返回Returns ToolRegistration

一种新的ToolRegistration 构建器。A new ToolRegistration builder

源码Source io/agentscope/core/tool/Toolkit.java:151–153

registerTool

public void registerTool(Object toolObject)

注册工具。

参数Parameters

名称Name	类型Type	说明Description
`toolObject`	Object	包含 @工具方法的普通 Java 对象。the object containing tool methods

源码Source io/agentscope/core/tool/Toolkit.java:159–161

registerAgentTool

public void registerAgentTool(AgentTool tool)

注册智能体工具。

参数Parameters

名称Name	类型Type	说明Description
`tool`	AgentTool	AgentTool 到注册。the AgentTool to register

源码Source io/agentscope/core/tool/Toolkit.java:208–210

getTool

public AgentTool getTool(String name)

获取工具。

Retrieves a tool by its name.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	工具到检索的名称。The name of the tool to retrieve

返回Returns AgentTool

返回AgentTool。The AgentTool instance, or null if not found

源码Source io/agentscope/core/tool/Toolkit.java:256–258

getTool

public AgentTool getTool(String name, ToolRequestConfig requestConfig)

获取工具。

Resolve a tool by name, composing a per-call ToolRequestConfig with the shared registry (never mutating either).

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。tool name
`requestConfig`	ToolRequestConfig	请求配置（类型 `ToolRequestConfig`）。per-call request config (may be `null` → `ToolRequestConfig#NONE`)

返回Returns AgentTool

已解析工具,或`null`当不找到或隐藏。the resolved tool, or `null` when not found or hidden

源码Source io/agentscope/core/tool/Toolkit.java:271–274

getToolNames

public Set<String> getToolNames()

获取 getToolNames。

Gets the names of all registered tools.

返回Returns Set<String>

返回设置。A set of all tool names (never null, may be empty)

源码Source io/agentscope/core/tool/Toolkit.java:281–283

registerSchema

public void registerSchema(ToolSchema schema)

注册模式。

另见See also @see SchemaOnlyTool, @see #isExternalTool(String)

参数Parameters

名称Name	类型Type	说明Description
`schema`	ToolSchema	模式定义（类型 `ToolSchema`）。The tool schema containing name, description, and parameters

抛出Throws

NullPointerException 可能抛出 `NullPointerException`。if schema is null

源码Source io/agentscope/core/tool/Toolkit.java:315–317

registerSchemas

public void registerSchemas(List<ToolSchema> schemas)

注册模式。

另见See also @see #registerSchema(ToolSchema)

参数Parameters

名称Name	类型Type	说明Description
`schemas`	List<ToolSchema>	工具模式到注册的列出。List of tool schemas to register

抛出Throws

NullPointerException 可能抛出 `NullPointerException`。if schemas is null

源码Source io/agentscope/core/tool/Toolkit.java:326–330

isExternalTool

public boolean isExternalTool(String toolName)

判断是否外部工具。

Check if a tool is an external tool (requires execution outside the framework).

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	工具到检查的名称。The name of the tool to check

返回Returns boolean

返回布尔值，表示判断结果。true if the tool is an external tool, false otherwise

源码Source io/agentscope/core/tool/Toolkit.java:343–346

isExternalTool

public boolean isExternalTool(String toolName, ToolRequestConfig requestConfig)

判断是否外部工具。

Check whether toolName resolves to an external tool under a per-call ToolRequestConfig.

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	工具到检查的名称。The name of the tool to check
`requestConfig`	ToolRequestConfig	请求配置（类型 `ToolRequestConfig`）。per-call request config (may be `null` → shared registry only)

返回Returns boolean

返回布尔值，表示判断结果。true if the resolved tool is an external tool, false otherwise

源码Source io/agentscope/core/tool/Toolkit.java:359–362

getToolSchemas

public List<ToolSchema> getToolSchemas()

获取工具模式。

Get tool schemas as ToolSchema objects.

返回Returns List<ToolSchema>

模型可读的工具模式列表。List of ToolSchema objects

源码Source io/agentscope/core/tool/Toolkit.java:373–375

getToolSchemas

public List<ToolSchema> getToolSchemas(Collection<String> activeGroups)

获取工具模式。

Get tool schemas filtered by an explicitly supplied set of active group names, independent of this toolkit's shared per-group activation flags.

参数Parameters

名称Name	类型Type	说明Description
`activeGroups`	Collection<String>	active 组（类型 `Collection`）。the group names to treat as active for this resolution

返回Returns List<ToolSchema>

返回列出。List of ToolSchema objects visible for the supplied groups (plus all ungrouped tools)

源码Source io/agentscope/core/tool/Toolkit.java:389–391

getToolSchemas

public List<ToolSchema> getToolSchemas(Collection<String> activeGroups, ToolRequestConfig requestConfig)

获取工具模式。

Stateless compose: the backend registry filtered by activeGroups, then a per-call ToolRequestConfig applied without mutating the shared registry or group manager.

参数Parameters

名称Name	类型Type	说明Description
`activeGroups`	Collection<String>	active 组（类型 `Collection`）。the group names treated as active for this resolution
`requestConfig`	ToolRequestConfig	请求配置（类型 `ToolRequestConfig`）。per-call request config (may be `null` → `ToolRequestConfig#NONE`)

返回Returns List<ToolSchema>

返回列出。the composed tool schemas

源码Source io/agentscope/core/tool/Toolkit.java:410–436

setChunkCallback

public void setChunkCallback(BiConsumer<ToolUseBlock, ToolResultBlock> callback)

设置分块回调。

Set the chunk callback for streaming tool responses.

参数Parameters

名称Name	类型Type	说明Description
`callback`	BiConsumer<ToolUseBlock, ToolResultBlock>	回调函数（类型 `BiConsumer`）。Callback to invoke when tools emit chunks via ToolEmitter

源码Source io/agentscope/core/tool/Toolkit.java:531–533

callTool

public Mono<ToolResultBlock> callTool(ToolCallParam param)

调用工具。

Execute a tool with the given parameters.

参数Parameters

名称Name	类型Type	说明Description
`param`	ToolCallParam	参数（类型 `ToolCallParam`）。Tool call parameters containing execution information

返回Returns Mono<ToolResultBlock>

返回Mono。Mono containing execution result

源码Source io/agentscope/core/tool/Toolkit.java:559–561

callTools

public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext)

调用工具。

Execute multiple tools asynchronously with agent-level context (internal use by ReActAgent).

参数Parameters

名称Name	类型Type	说明Description
`toolCalls`	List<ToolUseBlock>	工具调用到执行的列出。List of tool calls to execute
`agentExecutionConfig`	ExecutionConfig	智能体执行配置（类型 `ExecutionConfig`）。Execution config from agent level (can be null)
`agent`	Agent	智能体（类型 `Agent`）。The agent making the calls (may be null)
`agentRuntimeContext`	RuntimeContext	智能体运行时上下文（类型 `RuntimeContext`）。The agent-level runtime context (may be null)

返回Returns Mono<List<ToolResultBlock>>

返回Mono>。Mono containing list of tool responses

源码Source io/agentscope/core/tool/Toolkit.java:580–586

callTools

public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext, BiConsumer<ToolUseBlock, ToolResultBlock> internalChunkCallback)

调用工具。

Execute multiple tools with request configuration from the runtime context and a per-call chunk callback.

参数Parameters

名称Name	类型Type	说明Description
`toolCalls`	List<ToolUseBlock>	工具调用（类型 `List`）。The tool calls.
`agentExecutionConfig`	ExecutionConfig	智能体执行配置（类型 `ExecutionConfig`）。The agent execution config.
`agent`	Agent	智能体（类型 `Agent`）。The agent.
`agentRuntimeContext`	RuntimeContext	智能体运行时上下文（类型 `RuntimeContext`）。The agent runtime context.
`internalChunkCallback`	BiConsumer<ToolUseBlock, ToolResultBlock>	内部分块回调（类型 `BiConsumer`）。per-call internal chunk callback (may be `null`)

返回Returns Mono<List<ToolResultBlock>>

返回Mono>。Returns mono.

源码Source io/agentscope/core/tool/Toolkit.java:593–608

callTools

public Mono<List<ToolResultBlock>> callTools(List<ToolUseBlock> toolCalls, ExecutionConfig agentExecutionConfig, Agent agent, RuntimeContext agentRuntimeContext, ToolRequestConfig requestConfig, BiConsumer<ToolUseBlock, ToolResultBlock> internalChunkCallback)

调用工具。

Execute multiple tools with a per-call ToolRequestConfig and internal chunk callback, both threaded down to every single-tool execution.

参数Parameters

名称Name	类型Type	说明Description
`toolCalls`	List<ToolUseBlock>	工具调用（类型 `List`）。The tool calls.
`agentExecutionConfig`	ExecutionConfig	智能体执行配置（类型 `ExecutionConfig`）。The agent execution config.
`agent`	Agent	智能体（类型 `Agent`）。The agent.
`agentRuntimeContext`	RuntimeContext	智能体运行时上下文（类型 `RuntimeContext`）。The agent runtime context.
`requestConfig`	ToolRequestConfig	请求配置（类型 `ToolRequestConfig`）。The request config.
`internalChunkCallback`	BiConsumer<ToolUseBlock, ToolResultBlock>	内部分块回调（类型 `BiConsumer`）。The internal chunk callback.

返回Returns Mono<List<ToolResultBlock>>

返回Mono>。Returns mono.

源码Source io/agentscope/core/tool/Toolkit.java:614–640

registerMcpClient

public Mono<Void> registerMcpClient(McpClientWrapper mcpClientWrapper)

注册MCP 客户端。

Registers an MCP client and all its tools.

参数Parameters

名称Name	类型Type	说明Description
`mcpClientWrapper`	McpClientWrapper	已初始化的 MCP 客户端。the MCP client wrapper

返回Returns Mono<Void>

返回Mono。Mono that completes when registration is finished

源码Source io/agentscope/core/tool/Toolkit.java:653–655

removeMcpClient

public Mono<Void> removeMcpClient(String mcpClientName)

移除MCP 客户端。

Removes an MCP client and all its tools.

参数Parameters

名称Name	类型Type	说明Description
`mcpClientName`	String	MCP 客户端到移除的名称。the name of the MCP client to remove

返回Returns Mono<Void>

返回Mono。Mono that completes when removal is finished

源码Source io/agentscope/core/tool/Toolkit.java:663–665

closeMcpClients

public void closeMcpClients()

关闭MCP 客户端。

Releases clients registered by this toolkit.

源码Source io/agentscope/core/tool/Toolkit.java:668–677

createToolGroup

public void createToolGroup(String groupName, String description, boolean active)

创建工具组。

Create a new tool group with specified activation status and default META scope.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	工具组的名称。Name of the tool group
`description`	String	描述（类型 `String`）。Description of the tool group
`active`	boolean	active（类型 `boolean`）。Whether the group should be active by default

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if group already exists

源码Source io/agentscope/core/tool/Toolkit.java:689–691

createToolGroup

public void createToolGroup(String groupName, String description, boolean active, ToolGroupScope scope)

创建工具组。

Create a new tool group with specified activation status and scope.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	工具组的名称。Name of the tool group
`description`	String	描述（类型 `String`）。Description of the tool group
`active`	boolean	active（类型 `boolean`）。Whether the group should be active by default
`scope`	ToolGroupScope	范围（类型 `ToolGroupScope`）。Whether the group is managed by the meta tool (`ToolGroupScope#META`) or by developer code (`ToolGroupScope#EXTERNAL`)

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if group already exists

源码Source io/agentscope/core/tool/Toolkit.java:703–706

createToolGroup

public void createToolGroup(String groupName, String description)

创建工具组。

Create a new tool group (active by default, META scope).

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	工具组的名称。Name of the tool group
`description`	String	描述（类型 `String`）。Description of the tool group

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if group already exists

源码Source io/agentscope/core/tool/Toolkit.java:715–717

createSkillToolGroup

public void createSkillToolGroup(String groupName, String description, boolean active, String activateOnSkill)

创建技能工具组。

Create a SkillToolGroup bound to a specific skill.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	工具组的名称。Name of the tool group
`description`	String	描述（类型 `String`）。Description of the tool group
`active`	boolean	active（类型 `boolean`）。Whether the group should be active by default
`activateOnSkill`	String	activate On 技能（类型 `String`）。The skill name that this group is bound to

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if group already exists

源码Source io/agentscope/core/tool/Toolkit.java:732–735

findSkillToolGroupsByActivateOnSkill

public List<String> findSkillToolGroupsByActivateOnSkill(String skillName)

查找 findSkillToolGroupsByActivateOnSkill。

Find all SkillToolGroup instances whose activateOnSkill matches the given skill name.

参数Parameters

名称Name	类型Type	说明Description
`skillName`	String	技能名称（类型 `String`）。The skill name to match against

返回Returns List<String>

返回列出。List of matching group names (never null, may be empty)

源码Source io/agentscope/core/tool/Toolkit.java:744–746

registerToolGroup

public void registerToolGroup(ToolGroup group)

注册工具组。

参数Parameters

名称Name	类型Type	说明Description
`group`	ToolGroup	工具组到注册。The tool group to register

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if a group with the same name already exists

源码Source io/agentscope/core/tool/Toolkit.java:757–759

addToolToGroup

public void addToolToGroup(String groupName, String toolName)

添加工具到组。

Add an already-registered tool to an existing tool group.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	组名称（类型 `String`）。Name of the existing tool group
`toolName`	String	已注册工具的名称。Name of the registered tool

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if the group or tool doesn't exist

源码Source io/agentscope/core/tool/Toolkit.java:771–777

updateToolGroups

public void updateToolGroups(List<String> groupNames, boolean active)

更新工具组。

Update the activation status of tool groups.

参数Parameters

名称Name	类型Type	说明Description
`groupNames`	List<String>	组 Names（类型 `List`）。List of tool group names to update
`active`	boolean	active（类型 `boolean`）。Whether to activate (true) or deactivate (false) the groups

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if any group doesn't exist

源码Source io/agentscope/core/tool/Toolkit.java:792–800

removeTool

public void removeTool(String toolName)

移除工具。

Remove a tool by name from the toolkit.

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	工具到移除的名称。Name of the tool to remove

源码Source io/agentscope/core/tool/Toolkit.java:807–813

removeToolIfSame

public boolean removeToolIfSame(String toolName, AgentTool expected)

移除 removeToolIfSame。

Atomically remove a tool only if the registered instance is the expected one.

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	工具到移除的名称。Name of the tool to remove
`expected`	AgentTool	expected（类型 `AgentTool`）。The expected AgentTool instance (identity comparison)

返回Returns boolean

返回布尔值，表示判断结果。true if the tool was removed, false if it was already replaced or absent

源码Source io/agentscope/core/tool/Toolkit.java:822–828

removeToolGroups

public void removeToolGroups(List<String> groupNames)

移除工具组。

Remove tool groups and all tools within them.

参数Parameters

名称Name	类型Type	说明Description
`groupNames`	List<String>	组 Names（类型 `List`）。List of tool group names to remove

源码Source io/agentscope/core/tool/Toolkit.java:838–847

getActiveGroups

public List<String> getActiveGroups()

获取 getActiveGroups。

Get active tool group names.

返回Returns List<String>

返回列出。List of active group names, never null but may be empty

源码Source io/agentscope/core/tool/Toolkit.java:861–863

setActiveGroups

public void setActiveGroups(List<String> groups)

设置 setActiveGroups。

Set the active tool groups.

参数Parameters

名称Name	类型Type	说明Description
`groups`	List<String>	组（类型 `List`）。List of group names to set as active

源码Source io/agentscope/core/tool/Toolkit.java:875–877

getToolGroup

public ToolGroup getToolGroup(String groupName)

获取工具组通过名称。

Get a tool group by name.

参数Parameters

名称Name	类型Type	说明Description
`groupName`	String	工具组的名称。Name of the tool group

返回Returns ToolGroup

返回工具组。ToolGroup or null if not found

源码Source io/agentscope/core/tool/Toolkit.java:885–887

registerMetaTool

public void registerMetaTool()

注册元数据工具。

源码Source io/agentscope/core/tool/Toolkit.java:897–905

updateToolPresetParameters

public void updateToolPresetParameters(String toolName, Map<String, Object> newPresetParameters)

更新 updateToolPresetParameters。

Update preset parameters for a registered tool at runtime.

参数Parameters

名称Name	类型Type	说明Description
`toolName`	String	工具到更新的名称。The name of the tool to update
`newPresetParameters`	Map<String, Object>	新建 Preset 参数（类型 `Map`）。The new preset parameters (null will be treated as empty map)

抛出Throws

IllegalArgumentException 当if 工具是不找到时抛出 `IllegalArgumentException`。if the tool is not found

源码Source io/agentscope/core/tool/Toolkit.java:918–926

copy

public Toolkit copy()

返回 copy 结果。

Creates a build-time isolation copy of this toolkit.

返回Returns Toolkit

返回工具包。A new Toolkit instance whose registry shares the same tool instances

源码Source io/agentscope/core/tool/Toolkit.java:946–971

嵌套类详情Nested Class Detail

ToolRegistration

public static class ToolRegistration

工具注册，让智能体以受控方式调用外部能力。位于 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.