fix: add tooluseblock start

[mengnankkkk]

AgentScope-Java Version

[The version of AgentScope-Java you are working on, e.g. 1.0.7, check your pom.xml dependency version or run mvn dependency:tree | grep agentscope-parent:pom(only mac/linux)]

Description

[Please describe the background, purpose, changes made, and how to test this PR]
qwen3max:

Behavior: ToolUseBlock is not returned during the streaming phase; it is returned all at once at the last moment.

Streaming Phase: No ToolCallStart. A replacement is sent when END is detected.

点击查看测试代码

/*
 * Copyright 2024-2026 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.agentscope.core.agui.adapter;

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agui.event.AguiEvent;
import io.agentscope.core.agui.model.AguiMessage;
import io.agentscope.core.agui.model.RunAgentInput;
import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
import io.agentscope.core.memory.InMemoryMemory;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import org.junit.jupiter.api.Test;


class AguiAgentAdapterRealModelIntegrationTest {

    private static final String API_KEY_ENV = "DASHSCOPE_API_KEY";
    private static final String MODEL_NAME = "qwen3-max"; // 使用 qwen3-max 测试 ToolUseBlock 延迟返回

    /**
     * 测试工具类：提供天气查询功能。
     */
    public static class WeatherTools {
        @Tool(name = "get_weather", description = "获取指定城市的天气信息")
        public Map<String, Object> getWeather(
                @ToolParam(name = "city", description = "城市名称", required = true) String city) {
            return Map.of(
                    "city", city,
                    "temperature", "25°C",
                    "condition", "晴天",
                    "humidity", "60%");
        }
    }

    /**
     * 测试工具类：提供多个工具。
     */
    public static class MultiTools {
        @Tool(name = "get_weather", description = "获取指定城市的天气信息")
        public Map<String, Object> getWeather(
                @ToolParam(name = "city", description = "城市名称", required = true) String city) {
            return Map.of("city", city, "temperature", "25°C");
        }

        @Tool(name = "get_time", description = "获取指定城市的当前时间")
        public Map<String, Object> getTime(
                @ToolParam(name = "city", description = "城市名称", required = true) String city) {
            return Map.of("city", city, "time", "14:30");
        }
    }

    /**
     * 测试工具类：会失败的工具。
     */
    public static class FailingTools {
        @Tool(name = "failing_tool", description = "一个会失败的测试工具")
        public String failingTool(
                @ToolParam(name = "input", description = "输入参数", required = true) String input) {
            throw new RuntimeException("工具执行失败：模拟错误");
        }
    }

    /**
     * 测试真实模型调用场景下的 ToolCallStart 补发逻辑。
     *
     * <p>场景：使用真实的 qwen3-max 模型，该模型可能在流式阶段不返回 ToolUseBlock，
     * 而是在最后一次性返回。适配器应该能够正确处理这种情况，补发 ToolCallStart 事件。
     */
    @Test
    void testRealModelToolCallStartBackfill() {
        // 获取 API key（优先从系统属性，然后从环境变量）
        String apiKey = System.getProperty(API_KEY_ENV, System.getenv(API_KEY_ENV));
        assertNotNull(apiKey, "需要设置 " + API_KEY_ENV + " 环境变量或系统属性");
        assertFalse(apiKey.isBlank(), API_KEY_ENV + " 不能为空");

        // 创建工具包并注册工具
        Toolkit toolkit = new Toolkit();
        toolkit.registration().tool(new WeatherTools()).apply();

        // 创建真实的 DashScope 模型
        DashScopeChatModel model =
                DashScopeChatModel.builder().apiKey(apiKey).modelName(MODEL_NAME).stream(true)
                        .formatter(new DashScopeChatFormatter())
                        .build();

        // 创建 ReActAgent
        ReActAgent agent =
                ReActAgent.builder()
                        .name("WeatherAgent")
                        .model(model)
                        .toolkit(toolkit)
                        .memory(new InMemoryMemory())
                        .maxIters(3) // 限制迭代次数，避免过多 API 调用
                        .build();

        // 创建 AGUI 适配器
        AguiAgentAdapter adapter = new AguiAgentAdapter(agent, AguiAdapterConfig.defaultConfig());

        // 准备输入：要求查询天气
        RunAgentInput input =
                RunAgentInput.builder()
                        .threadId("thread-real-1")
                        .runId("run-real-1")
                        .messages(List.of(AguiMessage.userMessage("msg-1", "请帮我查询北京的天气情况")))
                        .build();

        // 执行并收集事件（设置较长的超时时间）
        List<AguiEvent> events = adapter.run(input).collectList().block(Duration.ofSeconds(60));

        // 验证结果
        assertNotNull(events, "事件列表不应为空");
        assertFalse(events.isEmpty(), "应该有事件返回");

        System.out.println("\n========== 收到的事件序列 ==========");
        for (int i = 0; i < events.size(); i++) {
            AguiEvent event = events.get(i);
            System.out.println(i + ": " + event.getClass().getSimpleName() + " - " + event);
        }

        // 验证基本事件
        assertTrue(
                events.stream().anyMatch(e -> e instanceof AguiEvent.RunStarted),
                "应该有 RunStarted 事件");
        assertTrue(
                events.stream().anyMatch(e -> e instanceof AguiEvent.RunFinished),
                "应该有 RunFinished 事件");

        // 查找工具调用相关事件
        List<AguiEvent.ToolCallStart> toolStarts =
                events.stream()
                        .filter(e -> e instanceof AguiEvent.ToolCallStart)
                        .map(e -> (AguiEvent.ToolCallStart) e)
                        .toList();

        List<AguiEvent.ToolCallArgs> toolArgs =
                events.stream()
                        .filter(e -> e instanceof AguiEvent.ToolCallArgs)
                        .map(e -> (AguiEvent.ToolCallArgs) e)
                        .toList();

        List<AguiEvent.ToolCallEnd> toolEnds =
                events.stream()
                        .filter(e -> e instanceof AguiEvent.ToolCallEnd)
                        .map(e -> (AguiEvent.ToolCallEnd) e)
                        .toList();

        List<AguiEvent.ToolCallResult> toolResults =
                events.stream()
                        .filter(e -> e instanceof AguiEvent.ToolCallResult)
                        .map(e -> (AguiEvent.ToolCallResult) e)
                        .toList();

        // 验证工具调用事件
        if (!toolStarts.isEmpty()) {
            System.out.println("检测到工具调用");

            // 验证每个 ToolCallStart 都有对应的 ToolCallEnd
            for (AguiEvent.ToolCallStart start : toolStarts) {
                String toolCallId = start.toolCallId();
                System.out.println(
                        "  - ToolCallStart: id=" + toolCallId + ", name=" + start.toolCallName());

                boolean hasEnd =
                        toolEnds.stream().anyMatch(end -> end.toolCallId().equals(toolCallId));
                assertTrue(hasEnd, "ToolCallStart (id=" + toolCallId + ") 应该有对应的 ToolCallEnd");

                // 验证事件顺序：Start 应该在 End 之前
                int startIndex = events.indexOf(start);
                int endIndex =
                        events.indexOf(
                                toolEnds.stream()
                                        .filter(end -> end.toolCallId().equals(toolCallId))
                                        .findFirst()
                                        .orElse(null));
                assertTrue(
                        startIndex < endIndex,
                        "ToolCallStart 应该在 ToolCallEnd 之前 (start="
                                + startIndex
                                + ", end="
                                + endIndex
                                + ")");
            }

            // 验证 ToolCallArgs 事件
            if (!toolArgs.isEmpty()) {
                System.out.println("✓ 检测到工具参数事件");

                // 拼接所有 delta 以获取完整参数
                StringBuilder fullArgs = new StringBuilder();
                for (AguiEvent.ToolCallArgs args : toolArgs) {
                    System.out.println(
                            "  - ToolCallArgs: id="
                                    + args.toolCallId()
                                    + ", delta="
                                    + args.delta());
                    fullArgs.append(args.delta());
                }

                // 验证完整参数包含城市信息
                String fullArgsStr = fullArgs.toString();
                assertTrue(
                        fullArgsStr.contains("北京") || fullArgsStr.contains("city"),
                        "工具参数应该包含城市信息，实际参数：" + fullArgsStr);

                // 验证 ToolCallArgs 在 ToolCallStart 之后
                if (!toolArgs.isEmpty()) {
                    AguiEvent.ToolCallArgs firstArgs = toolArgs.get(0);
                    AguiEvent.ToolCallStart correspondingStart =
                            toolStarts.stream()
                                    .filter(s -> s.toolCallId().equals(firstArgs.toolCallId()))
                                    .findFirst()
                                    .orElse(null);

                    if (correspondingStart != null) {
                        int argsIndex = events.indexOf(firstArgs);
                        int startIndex = events.indexOf(correspondingStart);
                        assertTrue(argsIndex > startIndex, "ToolCallArgs 应该在 ToolCallStart 之后");
                    }
                }
            } else {
                System.out.println("注意：没有检测到 ToolCallArgs 事件");
            }

            // 验证工具结果
            if (!toolResults.isEmpty()) {
                System.out.println("检测到工具结果");
                for (AguiEvent.ToolCallResult result : toolResults) {
                    System.out.println(
                            "  - ToolCallResult: id="
                                    + result.toolCallId()
                                    + ", content="
                                    + result.content());
                    assertTrue(
                            result.content().contains("25°C")
                                    || result.content().contains("晴天")
                                    || result.content().contains("北京"),
                            "工具结果应该包含天气信息");
                }
            }

            System.out.println("\n测试通过：适配器正确处理了真实模型的工具调用");
        } else {

            // 即使没有工具调用，也验证基本流程正常
            assertTrue(
                    events.stream().anyMatch(e -> e instanceof AguiEvent.TextMessageContent),
                    "应该至少有文本消息内容");
        }
    }

    /**
     * 测试真实模型在多轮对话中的工具调用。
     *
     * <p>场景：测试在多轮对话中，适配器能否正确处理多次工具调用。
     */
    @Test
    void testRealModelMultipleToolCalls() {
        // 获取 API key（优先从系统属性，然后从环境变量）
        String apiKey = System.getProperty(API_KEY_ENV, System.getenv(API_KEY_ENV));
        assertNotNull(apiKey, "需要设置 " + API_KEY_ENV + " 环境变量或系统属性");

        // 创建工具包并注册多个工具
        Toolkit toolkit = new Toolkit();
        toolkit.registration().tool(new MultiTools()).apply();

        // 创建模型和 Agent
        DashScopeChatModel model =
                DashScopeChatModel.builder().apiKey(apiKey).modelName(MODEL_NAME).stream(true)
                        .formatter(new DashScopeChatFormatter())
                        .build();

        ReActAgent agent =
                ReActAgent.builder()
                        .name("MultiToolAgent")
                        .model(model)
                        .toolkit(toolkit)
                        .memory(new InMemoryMemory())
                        .maxIters(5)
                        .build();

        AguiAgentAdapter adapter = new AguiAgentAdapter(agent, AguiAdapterConfig.defaultConfig());

        // 准备输入：要求同时查询天气和时间
        RunAgentInput input =
                RunAgentInput.builder()
                        .threadId("thread-multi-1")
                        .runId("run-multi-1")
                        .messages(List.of(AguiMessage.userMessage("msg-1", "请告诉我上海的天气和当前时间")))
                        .build();

        // 执行并收集事件
        List<AguiEvent> events = adapter.run(input).collectList().block(Duration.ofSeconds(60));

        assertNotNull(events);
        assertFalse(events.isEmpty());

        System.out.println("总事件数: " + events.size());

        // 统计工具调用
        long toolStartCount =
                events.stream().filter(e -> e instanceof AguiEvent.ToolCallStart).count();
        long toolEndCount = events.stream().filter(e -> e instanceof AguiEvent.ToolCallEnd).count();
        long toolResultCount =
                events.stream().filter(e -> e instanceof AguiEvent.ToolCallResult).count();

        System.out.println("ToolCallStart 数量: " + toolStartCount);
        System.out.println("ToolCallEnd 数量: " + toolEndCount);
        System.out.println("ToolCallResult 数量: " + toolResultCount);

        if (toolStartCount > 0) {
            // 验证每个 Start 都有对应的 End
            assertTrue(toolStartCount == toolEndCount, "ToolCallStart 和 ToolCallEnd 数量应该相等");

            System.out.println("多工具调用测试通过");
        } else {
            System.out.println("模型没有调用工具");
        }

    }

    /**
     * 测试真实模型在工具调用失败时的处理。
     *
     * <p>场景：创建一个会抛出异常的工具，验证适配器能否正确处理工具执行失败的情况。
     */
    @Test
    void testRealModelToolCallFailure() {
        // 获取 API key（优先从系统属性，然后从环境变量）
        String apiKey = System.getProperty(API_KEY_ENV, System.getenv(API_KEY_ENV));
        assertNotNull(apiKey, "需要设置 " + API_KEY_ENV + " 环境变量或系统属性");

        // 创建工具包并注册会失败的工具
        Toolkit toolkit = new Toolkit();
        toolkit.registration().tool(new FailingTools()).apply();

        DashScopeChatModel model =
                DashScopeChatModel.builder().apiKey(apiKey).modelName(MODEL_NAME).stream(true)
                        .formatter(new DashScopeChatFormatter())
                        .build();

        ReActAgent agent =
                ReActAgent.builder()
                        .name("FailingToolAgent")
                        .model(model)
                        .toolkit(toolkit)
                        .memory(new InMemoryMemory())
                        .maxIters(2)
                        .build();

        AguiAgentAdapter adapter = new AguiAgentAdapter(agent, AguiAdapterConfig.defaultConfig());

        RunAgentInput input =
                RunAgentInput.builder()
                        .threadId("thread-fail-1")
                        .runId("run-fail-1")
                        .messages(List.of(AguiMessage.userMessage("msg-1", "请使用 failing_tool 工具")))
                        .build();

        List<AguiEvent> events = adapter.run(input).collectList().block(Duration.ofSeconds(60));

        assertNotNull(events);
        assertFalse(events.isEmpty());

        // 查找错误相关的事件
        boolean hasToolResult =
                events.stream().anyMatch(e -> e instanceof AguiEvent.ToolCallResult);

        if (hasToolResult) {
            AguiEvent.ToolCallResult result =
                    events.stream()
                            .filter(e -> e instanceof AguiEvent.ToolCallResult)
                            .map(e -> (AguiEvent.ToolCallResult) e)
                            .findFirst()
                            .orElse(null);

            assertNotNull(result);
            System.out.println("工具结果: " + result.content());

            // 验证错误信息被正确传递
            assertTrue(
                    result.content().contains("失败") || result.content().contains("错误"),
                    "工具结果应该包含错误信息");

            System.out.println("工具失败处理测试通过");
        } else {
            System.out.println("没有检测到工具调用结果");
        }

    }
}

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[cla-assistant]

All committers have signed the CLA.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[mengnankkkk]

[mengnankkkk]

releate #588

[Copilot]

Pull request overview

This PR fixes an issue with the qwen3-max model where ToolUseBlock events are returned all at once at the end of streaming instead of incrementally, causing ToolCallStart events to be missing. The fix implements a backfill mechanism that caches ToolUseBlocks when they arrive during REASONING events, then emits the missing ToolCallStart and ToolCallArgs events when ToolResultBlock is processed.

Changes:

• Added caching mechanism for ToolUseBlock instances to support delayed ToolCallStart event emission
• Implemented backfill logic that checks for missing ToolCallStart events when processing ToolResult events
• Added HashMap to store ToolUseBlock instances by tool call ID for later retrieval

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AlbumenJ]

Please resolve conflicts

[AlbumenJ]

There are still some conflicts