refactor(SubAgent): Optimization

1. The `remove` method in the `SubAgentPendingStore` class now returns the removed object instead of void type.
2. Correspondingly, the places where this method is called in the `SubAgentContext` class have been updated, directly using the returned result for subsequent processing.
3. At the same time, some unnecessary method definitions, such as `clearToolResult`, have been cleaned up.
4. The relevant documentation and test cases have been updated to match the new API changes.
These changes have made the code more concise and easier to maintain.

Author: wuji1428

agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java

@@ -286,7 +286,7 @@ public void submitSubAgentResult(String subAgentToolId, ToolResultBlock pendingR
         if (!isEnableSubAgentHITL()) {
             throw new IllegalStateException(
                     "SubAgent HITL is not enabled. Please enable it via"
-                            + " builder.enableSubAgentHitl(true)");
+                            + " builder.enableSubAgentHITL(true)");
         }
 
         if (pendingResult == null) {
@@ -311,7 +311,7 @@ public void submitSubAgentResults(String subAgentToolId, List<ToolResultBlock> p
         if (!isEnableSubAgentHITL()) {
             throw new IllegalStateException(
                     "SubAgent HITL is not enabled. Please enable it via"
-                            + " builder.enableSubAgentHitl(true)");
+                            + " builder.enableSubAgentHITL(true)");
         }
 
         if (pendingResults == null || pendingResults.isEmpty()) {
@@ -1489,7 +1489,7 @@ public Builder subAgentContext(SubAgentContext subAgentContext) {
          * to handle sub-agent suspension and resumption. This allows sub-agents to be
          * suspended when they need user input and resumed when the user provides results.
          *
-         * @param enableSubAgentHITL true to enable sub-agent HITL support (default: true)
+         * @param enableSubAgentHITL true to enable sub-agent HITL support (default: false)
          * @return This builder instance for method chaining
          * @see SubAgentHook
          */

agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentContext.java

@@ -152,27 +152,10 @@ public Optional<String> getSessionId(String toolId) {
      * @return An Optional containing the pending context, or empty if none exist
      */
     public Optional<SubAgentPendingContext> consumePendingResult(String toolId) {
-        if (!pendingStore.contains(toolId)) {
+        if (toolId == null) {
             return Optional.empty();
         }
-        SubAgentPendingContext pending =
-                new SubAgentPendingContext(
-                        toolId,
-                        pendingStore.getSessionId(toolId),
-                        pendingStore.getPendingResults(toolId));
-        clearToolResult(toolId);
-        return Optional.of(pending);
-    }
-
-    /**
-     * Clears the pending context for a tool.
-     *
-     * <p>This removes both the session ID and all pending results for the tool.
-     *
-     * @param toolId The tool ID
-     */
-    public void clearToolResult(String toolId) {
-        pendingStore.remove(toolId);
+        return Optional.ofNullable(pendingStore.remove(toolId));
     }
 
     /**
@@ -304,7 +287,6 @@ public void saveTo(Session session, SessionKey sessionKey) {
      */
     @Override
     public void loadFrom(Session session, SessionKey sessionKey) {
-        this.pendingStore = null;
         session.get(sessionKey, "subagent_context", SubAgentPendingStore.class)
                 .ifPresent(state -> this.pendingStore = state);
     }

agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentHook.java

@@ -138,7 +138,6 @@ private Mono<PreActingEvent> handlePreActing(PreActingEvent event) {
         metadata.put(PREVIOUS_TOOL_RESULT, pendingResult.get());
         Map<String, Object> newInput = new HashMap<>(toolUse.getInput());
         newInput.put("session_id", pendingContext.get().sessionId());
-        context.clearToolResult(toolUse.getId());
 
         ToolUseBlock modifiedToolUse =
                 ToolUseBlock.builder()

agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentPendingStore.java

@@ -200,10 +200,11 @@ public void addResults(String toolId, List<ToolResultBlock> result) {
      *
      * @param toolId The tool ID
      */
-    public void remove(String toolId) {
+    public SubAgentPendingContext remove(String toolId) {
         if (toolId != null) {
-            toolIdToContext.remove(toolId);
+            return toolIdToContext.remove(toolId);
         }
+        return null;
     }
 
     /**

agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentContextTest.java

@@ -16,6 +16,7 @@
 package io.agentscope.core.tool.subagent;
 
 import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -269,20 +270,6 @@ void testClear() {
             assertFalse(context.getSessionId("tool-2").isPresent());
         }
 
-        @Test
-        @DisplayName("Should clear only pending results when specified")
-        void testClearPendingResults() {
-            context.setSessionId("tool-1", "session-1");
-            context.submitSubAgentResult("tool-1", createToolResultBlock("tool-1", "Result 1"));
-            context.setSessionId("tool-2", "session-2");
-
-            // Clear all pending results
-            context.clearToolResult("tool-1");
-
-            assertFalse(context.hasPendingResult("tool-1"));
-            assertTrue(context.getSessionId("tool-2").isPresent());
-        }
-
         @Test
         @DisplayName("Should maintain state after multiple operations")
         void testStateAfterMultipleOperations() {
@@ -699,10 +686,12 @@ void testLoadFromNonExistentSession() {
 
             // Should not throw exception
             SubAgentContext newContext = new SubAgentContext();
-            newContext.loadFrom(session, nonExistentKey);
+            SubAgentPendingStore oldStore = newContext.getPendingStore();
 
+            newContext.loadFrom(session, nonExistentKey);
+            SubAgentPendingStore newStore = newContext.getPendingStore();
             // Context should remain empty
-            assertNull(newContext.getPendingStore());
+            assertSame(oldStore, newStore);
         }
 
         @Test

agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentHITLTest.java

@@ -308,7 +308,7 @@ void testResumeFromPausedState() {
             registerSubAgent(mockSubAgent);
 
             MockModel mainModel =
-                    createSequentialToolModel("call_pausablesubagent", 2, "All done!");
+                    createSequentialToolModel("call_pausablesubagent", 1, "All done!");
             ReActAgent mainAgent = createHitlAgent(mainModel, context);
 
             Msg response1 = mainAgent.call(userMessage("Start task")).block(TEST_TIMEOUT);

docs/en/multi-agent/agent-as-tool.md

@@ -213,7 +213,7 @@ while (response.getGenerateReason() == GenerateReason.TOOL_SUSPENDED) {
                     .map(t -> ToolResultBlock.of(t.getId(), t.getName(),
                             TextBlock.builder().text("Operation cancelled").build()))
                     .toList();
-            mainAgent.submitSubAgentResult(resultBlock.getId(), cancelResults);
+            mainAgent.submitSubAgentResults(resultBlock.getId(), cancelResults);
         }
         response = mainAgent.call().block();
     }
@@ -238,4 +238,4 @@ System.out.println(response.getTextContent());
 **Resume methods**:
 - `mainAgent.call()` — Continue executing pending tools
 - `mainAgent.submitSubAgentResult(String, ToolResultBlock)` — Submit single tool result
-- `mainAgent.submitSubAgentResult(String, List<ToolResultBlock>)` — Submit multiple tool results
+- `mainAgent.submitSubAgentResults(String, List<ToolResultBlock>)` — Submit multiple tool results

docs/zh/multi-agent/agent-as-tool.md

@@ -213,7 +213,7 @@ while (response.getGenerateReason() == GenerateReason.TOOL_SUSPENDED) {
                     .map(t -> ToolResultBlock.of(t.getId(), t.getName(),
                             TextBlock.builder().text("操作已取消").build()))
                     .toList();
-            mainAgent.submitSubAgentResult(resultBlock.getId(), cancelResults);
+            mainAgent.submitSubAgentResults(resultBlock.getId(), cancelResults);
         }
         response = mainAgent.call().block();
     }
@@ -237,4 +237,4 @@ System.out.println(response.getTextContent());
 
 **恢复方法**：
 - `ReActAgent.submitSubAgentResult(String, ToolResultBlock)` — 提交单个工具结果
-- `ReActAgent.submitSubAgentResult(String, List<ToolResultBlock>)` — 批量提交工具结果
+- `ReActAgent.submitSubAgentResults(String, List<ToolResultBlock>)` — 批量提交工具结果