feat(tool): expose API to add registered tool to group

agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java

@@ -631,6 +631,24 @@ public void registerToolGroup(ToolGroup group) {
         groupManager.registerToolGroup(group);
     }
 
+    /**
+     * Add an already-registered tool to an existing tool group.
+     *
+     * <p>A tool may belong to multiple groups. Adding the same tool to the same group more than
+     * once has no additional effect.
+     *
+     * @param groupName Name of the existing tool group
+     * @param toolName Name of the registered tool
+     * @throws IllegalArgumentException if the group or tool doesn't exist
+     */
+    public void addToolToGroup(String groupName, String toolName) {
+        groupManager.validateGroupExists(groupName);
+        if (toolRegistry.getTool(toolName) == null) {
+            throw new IllegalArgumentException("Tool not found: " + toolName);
+        }
+        groupManager.addToolToGroup(groupName, toolName);
+    }
+
     /**
      * Update the activation status of tool groups.
      *

agentscope-core/src/test/java/io/agentscope/core/tool/ToolkitTest.java

@@ -518,7 +518,13 @@ void testToolAvailableWhenAssignedToMultipleGroups() {
         toolkit.createToolGroup("groupB", "Group B", false);
 
         toolkit.registration().tool(sampleTools).group("groupA").apply();
-        toolkit.registration().tool(sampleTools).group("groupB").apply();
+        AgentTool registeredTool = toolkit.getTool("add");
+        toolkit.addToolToGroup("groupB", "add");
+        toolkit.addToolToGroup("groupB", "add");
+
+        assertNotNull(registeredTool);
+        assertSame(registeredTool, toolkit.getTool("add"));
+        assertEquals(Set.of("add"), toolkit.getToolGroup("groupB").getTools());
 
         Map<String, Object> addInput = Map.of("a", 5, "b", 7);
         ToolUseBlock toolCall =
@@ -565,6 +571,26 @@ void testToolAvailableWhenAssignedToMultipleGroups() {
                 "Should fail when no groups are active: " + getResultText(resultWithNone));
     }
 
+    @Test
+    @DisplayName("Should reject adding an unknown group or tool")
+    void testAddToolToGroupValidation() {
+        toolkit.createToolGroup("existingGroup", "Existing group", false);
+        toolkit.registerAgentTool(namedAgentTool("registeredTool"));
+
+        IllegalArgumentException missingGroup =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> toolkit.addToolToGroup("missingGroup", "registeredTool"));
+        assertEquals("Tool group 'missingGroup' does not exist", missingGroup.getMessage());
+
+        IllegalArgumentException missingTool =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> toolkit.addToolToGroup("existingGroup", "missingTool"));
+        assertEquals("Tool not found: missingTool", missingTool.getMessage());
+        assertTrue(toolkit.getToolGroup("existingGroup").getTools().isEmpty());
+    }
+
     @Test
     @DisplayName("Should prevent execution after group deactivation")
     void testToolGroupDeactivationPreventsExecution() {