fix(core): emit ExternalExecutionResultEvent when external tool results resume (#2605)

Author: jujn

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

@@ -33,6 +33,7 @@
 import io.agentscope.core.event.AllToolsDeniedEvent;
 import io.agentscope.core.event.ConfirmResult;
 import io.agentscope.core.event.ExceedMaxItersEvent;
+import io.agentscope.core.event.ExternalExecutionResultEvent;
 import io.agentscope.core.event.ModelCallEndEvent;
 import io.agentscope.core.event.ModelCallStartEvent;
 import io.agentscope.core.event.RequestStopEvent;
@@ -1720,12 +1721,7 @@ private Mono<Msg> doCallInner(List<Msg> msgs) {
             // ConfirmResults (via Msg.METADATA_CONFIRM_RESULTS) before we can proceed.
             List<ToolUseBlock> asking = askingToolCalls();
             if (!asking.isEmpty()) {
-                List<ConfirmResult> confirmResults = extractAndValidateConfirmResults(msgs, asking);
-                publishEvent(
-                        new UserConfirmResultEvent(
-                                resolvePendingConfirmRequestReplyId(), confirmResults));
-                applyConfirmResults(confirmResults);
-                clearPendingConfirmRequest();
+                validateAndAcceptConfirmResults(msgs, asking);
                 return resumeAgent();
             }
 
@@ -1793,15 +1789,15 @@ private List<ConfirmResult> extractConfirmResults(List<Msg> msgs) {
         }
 
         /**
-         * Validate the user-provided confirmation payload against the currently ASKING tool calls.
+         * Validate and accept a permission-HITL resume payload against the currently ASKING tool
+         * calls.
          *
          * <p>Permission HITL resumes with one or more confirmations for currently ASKING tool
          * calls. Confirmations may cover a subset of ASKING calls, but no result may reference a
-         * stale or unrelated tool call. Returning a copied list gives downstream event emission and
-         * state mutation the same trusted payload.
+         * stale or unrelated tool call. Once accepted, the normalized results are applied to agent
+         * state and the correlated resume event is emitted.
          */
-        private List<ConfirmResult> extractAndValidateConfirmResults(
-                List<Msg> msgs, List<ToolUseBlock> asking) {
+        private void validateAndAcceptConfirmResults(List<Msg> msgs, List<ToolUseBlock> asking) {
             List<ConfirmResult> results = extractConfirmResults(msgs);
             if (results.isEmpty()) {
                 String pendingSummary =
@@ -1864,57 +1860,53 @@ private List<ConfirmResult> extractAndValidateConfirmResults(
                 }
                 normalized.add(result);
             }
-            return normalized;
+
+            String replyId = resolvePendingRequestReplyId(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID);
+            if (!replyId.isEmpty()) {
+                publishEvent(new UserConfirmResultEvent(replyId, normalized));
+                clearPendingRequestReplyId(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID);
+            }
+
+            applyConfirmResults(normalized);
         }
 
-        /**
-         * Resolve the reply id from the assistant message that originally paused for confirmation.
-         *
-         * <p>This keeps {@link UserConfirmResultEvent} correlated with the prior
-         * {@link RequireUserConfirmEvent}, even though the confirmation arrives in a later
-         * {@code agent.call(...)} invocation.
-         */
-        private String resolvePendingConfirmRequestReplyId() {
-            Msg confirmRequestMsg = findLastAssistantMsg();
-            if (confirmRequestMsg == null || confirmRequestMsg.getMetadata() == null) {
+        /** Resolve the reply id for the pending HITL request stored on the last assistant message. */
+        private String resolvePendingRequestReplyId(String metadataKey) {
+            Msg requestMsg = findLastAssistantMsg();
+            if (requestMsg == null || requestMsg.getMetadata() == null) {
                 return "";
             }
-            Object raw = confirmRequestMsg.getMetadata().get(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID);
+            Object raw = requestMsg.getMetadata().get(metadataKey);
             return raw instanceof String s ? s : "";
         }
 
         /**
-         * Persist the reply id for the pending confirmation request on the live assistant message.
+         * Persist the reply id for a pending HITL request on the live assistant message.
          *
-         * <p>The assistant message already owns the ASKING {@link ToolUseBlock}s, so storing the
-         * correlation metadata there lets the next call recover it from session state.
+         * <p>The assistant message owns the paused {@link ToolUseBlock}s, so storing the correlation
+         * metadata there lets the next call recover it from session state.
          */
-        private void persistPendingConfirmRequest(String replyId) {
+        private void persistPendingRequestReplyId(String metadataKey, String replyId) {
             Msg lastAssistant = findLastAssistantMsg();
             if (lastAssistant == null) {
                 return;
             }
             Map<String, Object> metadata = new HashMap<>(lastAssistant.getMetadata());
-            metadata.put(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID, replyId);
+            metadata.put(metadataKey, replyId);
             replaceLastAssistantMsg(lastAssistant.withMetadata(metadata));
         }
 
-        /**
-         * Remove confirmation-request correlation metadata after the resume payload is accepted.
-         *
-         * <p>Leaving it behind would make later agent turns appear to belong to an already-closed
-         * HITL request.
-         */
-        private void clearPendingConfirmRequest() {
+        /** Remove HITL correlation metadata after the resume payload is accepted. */
+        private void clearPendingRequestReplyId(String metadataKey) {
             Msg lastAssistant = findLastAssistantMsg();
             if (lastAssistant == null || lastAssistant.getMetadata() == null) {
                 return;
             }
-            if (!lastAssistant.getMetadata().containsKey(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID)) {
+            if (!lastAssistant.getMetadata().containsKey(metadataKey)) {
                 return;
             }
             Map<String, Object> metadata = new HashMap<>(lastAssistant.getMetadata());
-            metadata.remove(Msg.METADATA_CONFIRM_REQUEST_REPLY_ID);
+            metadata.remove(metadataKey);
             replaceLastAssistantMsg(lastAssistant.withMetadata(metadata));
         }
 
@@ -2234,7 +2226,12 @@ private void validateAndAddToolResults(List<Msg> msgs, Set<String> pendingIds) {
                                 + ", Pending: "
                                 + pendingIds);
             }
-
+            String replyId =
+                    resolvePendingRequestReplyId(Msg.METADATA_EXTERNAL_EXECUTION_REQUEST_REPLY_ID);
+            if (!replyId.isEmpty()) {
+                publishEvent(new ExternalExecutionResultEvent(replyId, results));
+                clearPendingRequestReplyId(Msg.METADATA_EXTERNAL_EXECUTION_REQUEST_REPLY_ID);
+            }
             state.contextMutable().addAll(msgs);
         }
 
@@ -2853,7 +2850,8 @@ Flux<AgentEvent> actingStream(
                                 // completion;
                                 // initialise it to empty since no successful execution happened.
                                 resultHolder.set(List.of());
-                                persistPendingConfirmRequest(replyId);
+                                persistPendingRequestReplyId(
+                                        Msg.METADATA_CONFIRM_REQUEST_REPLY_ID, replyId);
                                 return Flux.<AgentEvent>just(
                                         new RequireUserConfirmEvent(replyId, pending),
                                         new RequestStopEvent(
@@ -3046,6 +3044,10 @@ private Flux<AgentEvent> runToolBatch(
                                                                                                     results);
                                                                             if (!suspendedCalls
                                                                                     .isEmpty()) {
+                                                                                persistPendingRequestReplyId(
+                                                                                        Msg
+                                                                                                .METADATA_EXTERNAL_EXECUTION_REQUEST_REPLY_ID,
+                                                                                        replyId);
                                                                                 sink.next(
                                                                                         new RequireExternalExecutionEvent(
                                                                                                 replyId,

agentscope-core/src/main/java/io/agentscope/core/message/Msg.java

@@ -83,6 +83,14 @@ public class Msg implements State {
     public static final String METADATA_CONFIRM_REQUEST_REPLY_ID =
             "agentscope_confirm_request_reply_id";
 
+    /**
+     * Metadata key storing the {@code replyId} of the {@code RequireExternalExecutionEvent} that
+     * paused this assistant turn. Used to correlate the later
+     * {@code ExternalExecutionResultEvent}.
+     */
+    public static final String METADATA_EXTERNAL_EXECUTION_REQUEST_REPLY_ID =
+            "agentscope_external_execution_request_reply_id";
+
     /**
      * Metadata key (boolean) marking a message as <em>synthetic</em>: framework-injected rather
      * than authored by the user, the model, or a tool. Synthetic messages (e.g. the per-turn todo

agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentNewLoopReplyTest.java

@@ -22,8 +22,10 @@
 import io.agentscope.core.ReActAgent;
 import io.agentscope.core.event.AgentEndEvent;
 import io.agentscope.core.event.AgentEvent;
+import io.agentscope.core.event.AgentResultEvent;
 import io.agentscope.core.event.AgentStartEvent;
 import io.agentscope.core.event.ExceedMaxItersEvent;
+import io.agentscope.core.event.ExternalExecutionResultEvent;
 import io.agentscope.core.event.ModelCallEndEvent;
 import io.agentscope.core.event.ModelCallStartEvent;
 import io.agentscope.core.event.RequireExternalExecutionEvent;
@@ -312,6 +314,59 @@ void externalToolCallEmitsRequireExternalExecutionEvent() {
         assertEquals("external_api", event.getToolCalls().get(0).getName());
     }
 
+    @Test
+    void externalToolResultResumeEmitsExternalExecutionResultEvent() {
+        ChatModelBase model =
+                new ScriptedModel(
+                        List.of(
+                                () -> Flux.just(toolUseResponse("ext1", "external_api", "/users")),
+                                () -> Flux.just(textResponse("done"))));
+        ReActAgent agent =
+                ReActAgent.builder()
+                        .name("asst")
+                        .model(model)
+                        .toolkit(toolkitWithExternalSchema())
+                        .build();
+
+        List<AgentEvent> firstEvents = agent.streamEvents(List.of()).collectList().block();
+        assertNotNull(firstEvents);
+        int iRequireExternal = indexOf(firstEvents, RequireExternalExecutionEvent.class);
+        assertTrue(iRequireExternal >= 0, "RequireExternalExecutionEvent expected");
+
+        RequireExternalExecutionEvent requireEvent =
+                (RequireExternalExecutionEvent) firstEvents.get(iRequireExternal);
+        ToolResultBlock externalResult =
+                ToolResultBlock.builder()
+                        .id("ext1")
+                        .name("external_api")
+                        .output(TextBlock.builder().text("external result").build())
+                        .state(ToolResultState.SUCCESS)
+                        .build();
+        Msg resumeMsg = Msg.builder().role(MsgRole.TOOL).content(externalResult).build();
+
+        List<AgentEvent> resumedEvents =
+                agent.streamEvents(List.of(resumeMsg)).collectList().block();
+        assertNotNull(resumedEvents);
+
+        int iExternalResult = indexOf(resumedEvents, ExternalExecutionResultEvent.class);
+        int iModelStart = indexOf(resumedEvents, ModelCallStartEvent.class);
+        assertTrue(iExternalResult >= 0, "ExternalExecutionResultEvent expected");
+        assertTrue(
+                iModelStart > iExternalResult,
+                "ExternalExecutionResultEvent should be emitted before resumed reasoning");
+
+        ExternalExecutionResultEvent resultEvent =
+                (ExternalExecutionResultEvent) resumedEvents.get(iExternalResult);
+        assertEquals(requireEvent.getReplyId(), resultEvent.getReplyId());
+        assertEquals(1, resultEvent.getToolResults().size());
+        assertEquals("ext1", resultEvent.getToolResults().get(0).getId());
+
+        AgentResultEvent agentResult =
+                (AgentResultEvent)
+                        resumedEvents.get(indexOf(resumedEvents, AgentResultEvent.class));
+        assertEquals("done", agentResult.getResult().getTextContent());
+    }
+
     @Test
     void maxItersOverflowEmitsExceedMaxItersEvent() {
         Supplier<Flux<ChatResponse>> loop = () -> Flux.just(toolUseResponse("tc", "echo", "x"));

docs/v2/en/docs/building-blocks/agent.md

@@ -431,7 +431,7 @@ for (var tc : externalEvent.getToolCalls()) {
 }
 ```
 
-**3. Resume the agent** — feed the results back as the next `call`'s input message. The results are injected into the agent context and reasoning continues from where it paused. See `agentscope-examples/documentation/.../hitl/InterruptionExample.java` for a complete walkthrough.
+**3. Resume the agent** — feed the results back as the next `call`'s input message. After the results are validated, they are injected into the agent context and the agent emits `ExternalExecutionResultEvent`; its `getReplyId()` matches the earlier `RequireExternalExecutionEvent#getReplyId()`. Reasoning then continues from where it paused.
 
 :::{tip}
 Use `streamEvents` when building interactive UIs — it lets you detect pauses in real time and prompt the user immediately. Use `call` for programmatic flows that handle events automatically. Complete runnable examples: `agentscope-examples/documentation/.../hitl/PermissionHITLExample.java`.

docs/v2/en/docs/building-blocks/message-and-event.md

@@ -297,6 +297,11 @@ Events are grouped below; unless noted otherwise, every event also carries `getR
 
     **RequireExternalExecutionEvent** — agent pauses for external execution.
 
+    | Method | Type | Description |
+    |--------|------|-------------|
+    | `getReplyId()` | `String` | Reply message ID |
+    | `getToolCalls()` | `List<ToolUseBlock>` | Tool calls awaiting external execution |
+
     **UserConfirmResultEvent** — emitted when a later `call()` resumes a paused permission HITL request.
     It carries one or more `ConfirmResult`s, and its `replyId` matches the earlier `RequireUserConfirmEvent`.
 
@@ -305,7 +310,13 @@ Events are grouped below; unless noted otherwise, every event also carries `getR
     | `getReplyId()` | `String` | Reply ID of the correlated `RequireUserConfirmEvent` |
     | `getConfirmResults()` | `List<ConfirmResult>` | Confirmation results accepted for this resume |
 
-    **ExternalExecutionResultEvent** — external system returns execution results (input event); carries `List<ToolResultBlock>`.
+    **ExternalExecutionResultEvent** — emitted when a later `call()` resumes a paused external-execution request.
+    It carries one or more `ToolResultBlock`s, and its `replyId` matches the earlier `RequireExternalExecutionEvent`.
+
+    | Method | Type | Description |
+    |--------|------|-------------|
+    | `getReplyId()` | `String` | Reply ID of the correlated `RequireExternalExecutionEvent` |
+    | `getToolResults()` | `List<ToolResultBlock>` | External execution results accepted for this resume |
 
     **AllToolsDeniedEvent** — the user denied all tool calls from the most recent reasoning step via HITL confirmation. This event is emitted through the `onActing` middleware chain, allowing middlewares to emit a `RequestStopEvent` to stop the agent. If no middleware handles it, the agent continues to the next reasoning iteration (backward compatible).
 

docs/v2/en/docs/building-blocks/tool.md

@@ -173,7 +173,7 @@ public class WebSearchTool extends ToolBase {
 
 ### External execution tools
 
-External-execution tools delegate the actual work outside the agent runtime — typically to a human operator or an external system. The agent emits `RequireExternalExecutionEvent` and pauses until the result is fed back via `ExternalExecutionResultEvent`.
+External-execution tools delegate the actual work outside the agent runtime — typically to a human operator or an external system. The agent emits `RequireExternalExecutionEvent` and pauses. When the next call feeds back matching `ToolResultBlock`s, the agent emits `ExternalExecutionResultEvent` with the same `replyId` before continuing.
 
 This pattern is the foundation of [human-in-the-loop](./agent.md#human-in-the-loop) flows — some actions need human approval or human execution.
 

docs/v2/zh/docs/building-blocks/agent.md

@@ -431,7 +431,7 @@ for (var tc : externalEvent.getToolCalls()) {
 }
 ```
 
-**3. 恢复智能体** —— 将结果作为下一次 `call` 的输入消息回传。结果会被注入智能体上下文，推理从中断处继续。完整示例见 `agentscope-examples/documentation/.../hitl/InterruptionExample.java`。
+**3. 恢复智能体** —— 将结果作为下一次 `call` 的输入消息回传。结果校验通过后会被注入智能体上下文，agent 会先发出 `ExternalExecutionResultEvent`，其 `getReplyId()` 与之前的 `RequireExternalExecutionEvent#getReplyId()` 相同，然后从中断处继续推理。
 
 :::{tip}
 构建交互式 UI 时使用 `streamEvents`——它可以实时检测暂停事件并立即提示用户。以编程方式处理事件的自动化流程则使用 `call`。完整可运行示例见 `agentscope-examples/documentation/.../hitl/PermissionHITLExample.java`。

docs/v2/zh/docs/building-blocks/message-and-event.md

@@ -297,6 +297,11 @@ sequenceDiagram
 
     **RequireExternalExecutionEvent** — 智能体暂停等待外部执行。
 
+    | 方法 | 类型 | 描述 |
+    |------|------|------|
+    | `getReplyId()` | `String` | 回复消息 ID |
+    | `getToolCalls()` | `List<ToolUseBlock>` | 待外部执行的工具调用列表 |
+
     **UserConfirmResultEvent** — 用户提供确认结果。携带 `List<ConfirmResult>`。
      `replyId` 与最初暂停智能体的 `RequireUserConfirmEvent` 相同。
 
@@ -305,7 +310,13 @@ sequenceDiagram
     | `getReplyId()` | `String` | 关联的 `RequireUserConfirmEvent` 的回复 ID |
     | `getConfirmResults()` | `List<ConfirmResult>` | 本次恢复接受的确认结果 |
 
-    **ExternalExecutionResultEvent** — 外部系统提供执行结果（输入事件）。携带 `List<ToolResultBlock>`。
+    **ExternalExecutionResultEvent** — 后续 `call()` 恢复外部执行暂停时发出。
+    携带一个或多个 `ToolResultBlock`，且 `replyId` 与之前的 `RequireExternalExecutionEvent` 相同。
+
+    | 方法 | 类型 | 说明 |
+    |------|------|------|
+    | `getReplyId()` | `String` | 关联的 `RequireExternalExecutionEvent` 的回复 ID |
+    | `getToolResults()` | `List<ToolResultBlock>` | 本次恢复接受的外部执行结果 |
 
     **AllToolsDeniedEvent** — 用户通过 HITL 确认拒绝了最近一轮推理产出的全部工具调用。该事件通过 `onActing` middleware 链发出，middleware 可据此发出 `RequestStopEvent` 停止 agent。若无 middleware 处理，agent 默认继续下一轮推理（向后兼容）。
 

docs/v2/zh/docs/building-blocks/tool.md

@@ -173,7 +173,7 @@ public class WebSearchTool extends ToolBase {
 
 ### 定义外部执行 Tool
 
-外部执行 tool 把实际执行委派给 agent 运行时之外 —— 通常是人工操作员或外部系统。Agent 调用此类 tool 时会发出 `RequireExternalExecutionEvent` 并暂停，直到结果通过 `ExternalExecutionResultEvent` 回传。
+外部执行 tool 把实际执行委派给 agent 运行时之外 —— 通常是人工操作员或外部系统。Agent 调用此类 tool 时会发出 `RequireExternalExecutionEvent` 并暂停。下一次调用回传匹配的 `ToolResultBlock` 后，agent 会发出带有相同 `replyId` 的 `ExternalExecutionResultEvent`，然后继续执行。
 
 这种模式是 [human-in-the-loop](./agent.md) 工作流的基础 —— 某些动作需要人工确认或人工执行。