From 86c97fd9d82d7e4b7bfd077c48f3222402a045ec Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Sun, 11 Jan 2026 16:06:36 +0800 Subject: [PATCH 01/53] feat: support tool schema for completions chat api --- .../ChatCompletionsResponseBuilder.java | 9 +- .../converter/OpenAIToolConverter.java | 130 ++++++++ .../model/ChatCompletionsRequest.java | 17 + .../chat/completions/model/OpenAITool.java | 83 +++++ .../completions/model/OpenAIToolFunction.java | 96 ++++++ .../converter/OpenAIToolConverterTest.java | 296 ++++++++++++++++++ .../model/ChatCompletionsRequestTest.java | 64 ++++ .../ChatCompletionsWebAutoConfiguration.java | 18 +- .../chat/web/ChatCompletionsController.java | 31 +- .../web/ChatCompletionsControllerTest.java | 9 +- 10 files changed, 747 insertions(+), 6 deletions(-) create mode 100644 agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java create mode 100644 agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java create mode 100644 agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java create mode 100644 agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverterTest.java diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java index 0d2ac4701..0f3c89735 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java @@ -23,6 +23,7 @@ import io.agentscope.core.chat.completions.model.ChatMessage; import io.agentscope.core.chat.completions.model.ToolCall; import io.agentscope.core.message.ContentBlock; +import io.agentscope.core.message.GenerateReason; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; @@ -99,9 +100,13 @@ public ChatCompletionsResponse buildResponse( ChatMessage message = convertMsgToChatMessage(reply); choice.setMessage(message); - // Set finish_reason based on whether there are tool calls - if (message.getToolCalls() != null && !message.getToolCalls().isEmpty()) { + // Set finish_reason based on GenerateReason or tool calls + GenerateReason generateReason = reply != null ? reply.getGenerateReason() : null; + if (generateReason == GenerateReason.TOOL_SUSPENDED + || (message.getToolCalls() != null && !message.getToolCalls().isEmpty())) { choice.setFinishReason("tool_calls"); + } else if (generateReason == GenerateReason.MAX_ITERATIONS) { + choice.setFinishReason("length"); } else { choice.setFinishReason("stop"); } diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java new file mode 100644 index 000000000..fd8c8ef07 --- /dev/null +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java @@ -0,0 +1,130 @@ +/* + * 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.chat.completions.converter; + +import io.agentscope.core.chat.completions.model.OpenAITool; +import io.agentscope.core.chat.completions.model.OpenAIToolFunction; +import io.agentscope.core.model.ToolSchema; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * Converter for converting OpenAI tool format to AgentScope ToolSchema. + * + *

This converter handles the transformation from OpenAI's tool format (used in Chat Completions + * API requests) to AgentScope's internal ToolSchema format. Tools converted by this converter are + * intended to be registered as schema-only tools, which will trigger tool suspension when called. + */ +public class OpenAIToolConverter { + + private static final Logger log = LoggerFactory.getLogger(OpenAIToolConverter.class); + + /** + * Converts a list of OpenAI tools to AgentScope ToolSchemas. + * + *

Only tools with type "function" are converted. Other tool types are skipped with a warning. + * + * @param tools The list of OpenAI tools to convert (may be null or empty) + * @return A list of converted ToolSchema objects; returns an empty list if input is null or + * empty + */ + public List convertToToolSchemas(List tools) { + if (tools == null || tools.isEmpty()) { + return List.of(); + } + + List schemas = new ArrayList<>(); + + for (OpenAITool tool : tools) { + if (tool == null) { + log.warn("Skipping null tool in conversion"); + continue; + } + + // Only support function type tools for now + if (!"function".equals(tool.getType())) { + log.warn( + "Skipping tool with unsupported type: {}. Only 'function' type is" + + " supported", + tool.getType()); + continue; + } + + OpenAIToolFunction function = tool.getFunction(); + if (function == null) { + log.warn("Skipping tool with null function definition"); + continue; + } + + String name = function.getName(); + String description = function.getDescription(); + Map parameters = function.getParameters(); + + // Validate required fields + if (name == null || name.isBlank()) { + log.warn("Skipping tool with null or empty name"); + continue; + } + + if (description == null || description.isBlank()) { + log.warn("Skipping tool '{}' with null or empty description", name); + // Use empty string as fallback for description + description = ""; + } + + try { + ToolSchema.Builder schemaBuilder = + ToolSchema.builder().name(name).description(description); + + if (parameters != null) { + schemaBuilder.parameters(parameters); + } + + if (function.getStrict() != null) { + schemaBuilder.strict(function.getStrict()); + } + + ToolSchema schema = schemaBuilder.build(); + schemas.add(schema); + log.debug("Converted OpenAI tool to ToolSchema: {}", name); + + } catch (Exception e) { + log.error("Failed to convert tool '{}' to ToolSchema: {}", name, e.getMessage(), e); + } + } + + return schemas; + } + + /** + * Converts a single OpenAI tool to a ToolSchema. + * + * @param tool The OpenAI tool to convert + * @return The converted ToolSchema, or null if conversion fails + */ + public ToolSchema convertToToolSchema(OpenAITool tool) { + if (tool == null) { + return null; + } + + List schemas = convertToToolSchemas(List.of(tool)); + return schemas.isEmpty() ? null : schemas.get(0); + } +} + diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequest.java index e942ca663..77661dfdb 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequest.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequest.java @@ -71,6 +71,15 @@ public class ChatCompletionsRequest { /** Whether to stream responses via Server-Sent Events (SSE). Optional, defaults to false. */ private Boolean stream; + /** + * A list of tools the model may call. Currently, only functions are supported as a tool. + * + *

When tools are provided, they are registered as schema-only tools. When the agent decides + * to call a tool, execution is suspended and the tool call is returned to the client for + * external execution. + */ + private List tools; + public String getModel() { return model; } @@ -94,4 +103,12 @@ public Boolean getStream() { public void setStream(Boolean stream) { this.stream = stream; } + + public List getTools() { + return tools; + } + + public void setTools(List tools) { + this.tools = tools; + } } diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java new file mode 100644 index 000000000..560b3e8b7 --- /dev/null +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java @@ -0,0 +1,83 @@ +/* + * 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.chat.completions.model; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * OpenAI tool definition for Chat Completions API requests. + * + *

This class represents a tool that can be called by the model, following OpenAI's format. + * + *

Example: + * 

{@code
+ * {
+ *   "type": "function",
+ *   "function": {
+ *     "name": "get_weather",
+ *     "description": "Get the current weather",
+ *     "parameters": {
+ *       "type": "object",
+ *       "properties": {
+ *         "location": {"type": "string"}
+ *       },
+ *       "required": ["location"]
+ *     }
+ *   }
+ * }
+ * }
+ */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public class OpenAITool { + + /** Tool type, always "function" for now. */ + @JsonProperty("type") + private String type = "function"; + + /** The function definition. */ + @JsonProperty("function") + private OpenAIToolFunction function; + + /** Default constructor for deserialization. */ + public OpenAITool() {} + + /** + * Creates a new OpenAITool with the specified function. + * + * @param function The function definition + */ + public OpenAITool(OpenAIToolFunction function) { + this.function = function; + } + + public String getType() { + return type; + } + + public void setType(String type) { + this.type = type; + } + + public OpenAIToolFunction getFunction() { + return function; + } + + public void setFunction(OpenAIToolFunction function) { + this.function = function; + } +} + diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java new file mode 100644 index 000000000..da7537716 --- /dev/null +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java @@ -0,0 +1,96 @@ +/* + * 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.chat.completions.model; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; +import java.util.Map; + +/** + * OpenAI tool function definition for Chat Completions API requests. + * + *

This class represents the function definition in a tool, following OpenAI's format. + * + *

Example: + * 

{@code
+ * {
+ *   "name": "get_weather",
+ *   "description": "Get the current weather",
+ *   "parameters": {
+ *     "type": "object",
+ *     "properties": {
+ *       "location": {"type": "string"}
+ *     },
+ *     "required": ["location"]
+ *   }
+ * }
+ * }
+ */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public class OpenAIToolFunction { + + /** The name of the function. */ + @JsonProperty("name") + private String name; + + /** The description of the function. */ + @JsonProperty("description") + private String description; + + /** The JSON Schema for the function parameters. */ + @JsonProperty("parameters") + private Map parameters; + + /** Whether to enable strict mode for schema validation. */ + @JsonProperty("strict") + private Boolean strict; + + /** Default constructor for deserialization. */ + public OpenAIToolFunction() {} + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getDescription() { + return description; + } + + public void setDescription(String description) { + this.description = description; + } + + public Map getParameters() { + return parameters; + } + + public void setParameters(Map parameters) { + this.parameters = parameters; + } + + public Boolean getStrict() { + return strict; + } + + public void setStrict(Boolean strict) { + this.strict = strict; + } +} + diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverterTest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverterTest.java new file mode 100644 index 000000000..7756b120d --- /dev/null +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverterTest.java @@ -0,0 +1,296 @@ +/* + * 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.chat.completions.converter; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.agentscope.core.chat.completions.model.OpenAITool; +import io.agentscope.core.chat.completions.model.OpenAIToolFunction; +import io.agentscope.core.model.ToolSchema; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for {@link OpenAIToolConverter}. + */ +@DisplayName("OpenAIToolConverter Tests") +class OpenAIToolConverterTest { + + private OpenAIToolConverter converter; + + @BeforeEach + void setUp() { + converter = new OpenAIToolConverter(); + } + + @Nested + @DisplayName("Convert To ToolSchemas Tests") + class ConvertToToolSchemasTests { + + @Test + @DisplayName("Should convert valid function tool to ToolSchema") + void shouldConvertValidFunctionToolToToolSchema() { + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("get_weather"); + function.setDescription("Get weather for a location"); + function.setParameters( + Map.of( + "type", + "object", + "properties", + Map.of("location", Map.of("type", "string")))); + + OpenAITool tool = new OpenAITool(function); + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertEquals(1, schemas.size()); + ToolSchema schema = schemas.get(0); + assertEquals("get_weather", schema.getName()); + assertEquals("Get weather for a location", schema.getDescription()); + assertNotNull(schema.getParameters()); + } + + @Test + @DisplayName("Should return empty list for null input") + void shouldReturnEmptyListForNullInput() { + List schemas = converter.convertToToolSchemas(null); + + assertTrue(schemas.isEmpty()); + } + + @Test + @DisplayName("Should return empty list for empty input") + void shouldReturnEmptyListForEmptyInput() { + List schemas = converter.convertToToolSchemas(List.of()); + + assertTrue(schemas.isEmpty()); + } + + @Test + @DisplayName("Should skip null tools in list") + void shouldSkipNullToolsInList() { + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("valid_tool"); + function.setDescription("Valid"); + OpenAITool validTool = new OpenAITool(function); + + List tools = new ArrayList<>(); + tools.add(validTool); + tools.add(null); + + List schemas = converter.convertToToolSchemas(tools); + + assertEquals(1, schemas.size()); + assertEquals("valid_tool", schemas.get(0).getName()); + } + + @Test + @DisplayName("Should skip non-function type tools") + void shouldSkipNonFunctionTypeTools() { + OpenAITool tool = new OpenAITool(); + tool.setType("code_interpreter"); // Not supported + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertTrue(schemas.isEmpty()); + } + + @Test + @DisplayName("Should skip tools with null function") + void shouldSkipToolsWithNullFunction() { + OpenAITool tool = new OpenAITool(); + tool.setType("function"); + tool.setFunction(null); + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertTrue(schemas.isEmpty()); + } + + @Test + @DisplayName("Should skip tools with null or empty name") + void shouldSkipToolsWithNullOrEmptyName() { + OpenAIToolFunction function1 = new OpenAIToolFunction(); + function1.setName(null); + function1.setDescription("Test"); + OpenAITool tool1 = new OpenAITool(function1); + + OpenAIToolFunction function2 = new OpenAIToolFunction(); + function2.setName(""); + function2.setDescription("Test"); + OpenAITool tool2 = new OpenAITool(function2); + + OpenAIToolFunction function3 = new OpenAIToolFunction(); + function3.setName(" "); + function3.setDescription("Test"); + OpenAITool tool3 = new OpenAITool(function3); + + List schemas = converter.convertToToolSchemas(List.of(tool1, tool2, tool3)); + + assertTrue(schemas.isEmpty()); + } + + @Test + @DisplayName("Should use empty string for null or empty description") + void shouldUseEmptyStringForNullOrEmptyDescription() { + OpenAIToolFunction function1 = new OpenAIToolFunction(); + function1.setName("tool1"); + function1.setDescription(null); + OpenAITool tool1 = new OpenAITool(function1); + + OpenAIToolFunction function2 = new OpenAIToolFunction(); + function2.setName("tool2"); + function2.setDescription(""); + OpenAITool tool2 = new OpenAITool(function2); + + List schemas = converter.convertToToolSchemas(List.of(tool1, tool2)); + + assertEquals(2, schemas.size()); + assertEquals("", schemas.get(0).getDescription()); + assertEquals("", schemas.get(1).getDescription()); + } + + @Test + @DisplayName("Should handle tools with null parameters") + void shouldHandleToolsWithNullParameters() { + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("no_params"); + function.setDescription("No parameters"); + function.setParameters(null); + + OpenAITool tool = new OpenAITool(function); + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertEquals(1, schemas.size()); + // ToolSchema converts null parameters to empty map + assertNotNull(schemas.get(0).getParameters()); + assertTrue(schemas.get(0).getParameters().isEmpty()); + } + + @Test + @DisplayName("Should preserve strict parameter") + void shouldPreserveStrictParameter() { + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("strict_tool"); + function.setDescription("Strict tool"); + function.setStrict(true); + + OpenAITool tool = new OpenAITool(function); + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertEquals(1, schemas.size()); + assertTrue(schemas.get(0).getStrict()); + } + + @Test + @DisplayName("Should convert multiple tools") + void shouldConvertMultipleTools() { + OpenAIToolFunction function1 = new OpenAIToolFunction(); + function1.setName("tool1"); + function1.setDescription("Tool 1"); + OpenAITool tool1 = new OpenAITool(function1); + + OpenAIToolFunction function2 = new OpenAIToolFunction(); + function2.setName("tool2"); + function2.setDescription("Tool 2"); + OpenAITool tool2 = new OpenAITool(function2); + + List schemas = converter.convertToToolSchemas(List.of(tool1, tool2)); + + assertEquals(2, schemas.size()); + assertEquals("tool1", schemas.get(0).getName()); + assertEquals("tool2", schemas.get(1).getName()); + } + + @Test + @DisplayName("Should handle complex parameters") + void shouldHandleComplexParameters() { + Map properties = new HashMap<>(); + properties.put("location", Map.of("type", "string", "description", "City name")); + properties.put( + "unit", Map.of("type", "string", "enum", List.of("celsius", "fahrenheit"))); + + Map parameters = new HashMap<>(); + parameters.put("type", "object"); + parameters.put("properties", properties); + parameters.put("required", List.of("location")); + + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("get_weather"); + function.setDescription("Get weather"); + function.setParameters(parameters); + + OpenAITool tool = new OpenAITool(function); + + List schemas = converter.convertToToolSchemas(List.of(tool)); + + assertEquals(1, schemas.size()); + assertNotNull(schemas.get(0).getParameters()); + assertEquals(parameters, schemas.get(0).getParameters()); + } + } + + @Nested + @DisplayName("Convert To ToolSchema Tests") + class ConvertToToolSchemaTests { + + @Test + @DisplayName("Should convert single tool to ToolSchema") + void shouldConvertSingleToolToToolSchema() { + OpenAIToolFunction function = new OpenAIToolFunction(); + function.setName("single_tool"); + function.setDescription("Single tool"); + + OpenAITool tool = new OpenAITool(function); + + ToolSchema schema = converter.convertToToolSchema(tool); + + assertNotNull(schema); + assertEquals("single_tool", schema.getName()); + } + + @Test + @DisplayName("Should return null for null input") + void shouldReturnNullForNullInput() { + ToolSchema schema = converter.convertToToolSchema(null); + + assertNull(schema); + } + + @Test + @DisplayName("Should return null for invalid tool") + void shouldReturnNullForInvalidTool() { + OpenAITool tool = new OpenAITool(); + tool.setType("code_interpreter"); // Invalid type + + ToolSchema schema = converter.convertToToolSchema(tool); + + assertNull(schema); + } + } +} diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequestTest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequestTest.java index 15c8ab017..e614db10f 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequestTest.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequestTest.java @@ -173,6 +173,47 @@ void shouldHandleNullStream() { } } + @Nested + @DisplayName("Tools Tests") + class ToolsTests { + + @Test + @DisplayName("Should set and get tools") + void shouldSetAndGetTools() { + ChatCompletionsRequest request = new ChatCompletionsRequest(); + io.agentscope.core.chat.completions.model.OpenAIToolFunction function = + new io.agentscope.core.chat.completions.model.OpenAIToolFunction(); + function.setName("get_weather"); + function.setDescription("Get weather"); + io.agentscope.core.chat.completions.model.OpenAITool tool = + new io.agentscope.core.chat.completions.model.OpenAITool(function); + + request.setTools(List.of(tool)); + + assertNotNull(request.getTools()); + assertEquals(1, request.getTools().size()); + assertEquals("get_weather", request.getTools().get(0).getFunction().getName()); + } + + @Test + @DisplayName("Should handle null tools") + void shouldHandleNullTools() { + ChatCompletionsRequest request = new ChatCompletionsRequest(); + + assertNull(request.getTools()); + } + + @Test + @DisplayName("Should handle empty tools list") + void shouldHandleEmptyToolsList() { + ChatCompletionsRequest request = new ChatCompletionsRequest(); + request.setTools(new ArrayList<>()); + + assertNotNull(request.getTools()); + assertTrue(request.getTools().isEmpty()); + } + } + @Nested @DisplayName("Complete Request Tests") class CompleteRequestTests { @@ -192,5 +233,28 @@ void shouldBuildCompleteRequest() { assertEquals(2, request.getMessages().size()); assertFalse(request.getStream()); } + + @Test + @DisplayName("Should build complete request with tools") + void shouldBuildCompleteRequestWithTools() { + ChatCompletionsRequest request = new ChatCompletionsRequest(); + request.setModel("gpt-4"); + request.setMessages(List.of(new ChatMessage("user", "Hello"))); + request.setStream(false); + + io.agentscope.core.chat.completions.model.OpenAIToolFunction function = + new io.agentscope.core.chat.completions.model.OpenAIToolFunction(); + function.setName("get_weather"); + function.setDescription("Get weather"); + io.agentscope.core.chat.completions.model.OpenAITool tool = + new io.agentscope.core.chat.completions.model.OpenAITool(function); + request.setTools(List.of(tool)); + + assertEquals("gpt-4", request.getModel()); + assertEquals(1, request.getMessages().size()); + assertFalse(request.getStream()); + assertNotNull(request.getTools()); + assertEquals(1, request.getTools().size()); + } } } diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/config/ChatCompletionsWebAutoConfiguration.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/config/ChatCompletionsWebAutoConfiguration.java index d21d9f040..7c26bba66 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/config/ChatCompletionsWebAutoConfiguration.java +++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/config/ChatCompletionsWebAutoConfiguration.java @@ -18,6 +18,7 @@ import io.agentscope.core.ReActAgent; import io.agentscope.core.chat.completions.builder.ChatCompletionsResponseBuilder; import io.agentscope.core.chat.completions.converter.ChatMessageConverter; +import io.agentscope.core.chat.completions.converter.OpenAIToolConverter; import io.agentscope.core.chat.completions.streaming.ChatCompletionsStreamingAdapter; import io.agentscope.spring.boot.chat.service.ChatCompletionsStreamingService; import io.agentscope.spring.boot.chat.web.ChatCompletionsController; @@ -71,6 +72,17 @@ public ChatMessageConverter chatMessageConverter() { return new ChatMessageConverter(); } + /** + * Create the OpenAI tool converter bean. + * + * @return A new {@link OpenAIToolConverter} instance for converting OpenAI tools to ToolSchema + */ + @Bean + @ConditionalOnMissingBean + public OpenAIToolConverter openAIToolConverter() { + return new OpenAIToolConverter(); + } + /** * Create the response builder bean. * @@ -121,6 +133,7 @@ public ChatCompletionsStreamingService chatCompletionsStreamingService( * @param messageConverter Converter for HTTP DTOs to framework messages * @param responseBuilder Builder for response objects * @param streamingService Service for streaming responses + * @param toolConverter Converter for OpenAI tools to ToolSchema * @return The configured ChatCompletionsController bean */ @Bean @@ -129,8 +142,9 @@ public ChatCompletionsController chatCompletionsController( ObjectProvider agentProvider, ChatMessageConverter messageConverter, ChatCompletionsResponseBuilder responseBuilder, - ChatCompletionsStreamingService streamingService) { + ChatCompletionsStreamingService streamingService, + OpenAIToolConverter toolConverter) { return new ChatCompletionsController( - agentProvider, messageConverter, responseBuilder, streamingService); + agentProvider, messageConverter, responseBuilder, streamingService, toolConverter); } } diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/web/ChatCompletionsController.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/web/ChatCompletionsController.java index 711a8ddaa..d3bc85027 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/web/ChatCompletionsController.java +++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/web/ChatCompletionsController.java @@ -18,6 +18,7 @@ import io.agentscope.core.ReActAgent; import io.agentscope.core.chat.completions.builder.ChatCompletionsResponseBuilder; import io.agentscope.core.chat.completions.converter.ChatMessageConverter; +import io.agentscope.core.chat.completions.converter.OpenAIToolConverter; import io.agentscope.core.chat.completions.model.ChatCompletionsRequest; import io.agentscope.core.chat.completions.model.ChatCompletionsResponse; import io.agentscope.core.message.Msg; @@ -83,6 +84,7 @@ public class ChatCompletionsController { private final ChatMessageConverter messageConverter; private final ChatCompletionsResponseBuilder responseBuilder; private final ChatCompletionsStreamingService streamingService; + private final OpenAIToolConverter toolConverter; /** * Constructs a new ChatCompletionsController. @@ -91,16 +93,19 @@ public class ChatCompletionsController { * @param messageConverter Converter for HTTP DTOs to framework messages * @param responseBuilder Builder for response objects * @param streamingService Service for streaming responses + * @param toolConverter Converter for OpenAI tools to ToolSchema */ public ChatCompletionsController( ObjectProvider agentProvider, ChatMessageConverter messageConverter, ChatCompletionsResponseBuilder responseBuilder, - ChatCompletionsStreamingService streamingService) { + ChatCompletionsStreamingService streamingService, + OpenAIToolConverter toolConverter) { this.agentProvider = agentProvider; this.messageConverter = messageConverter; this.responseBuilder = responseBuilder; this.streamingService = streamingService; + this.toolConverter = toolConverter; } /** @@ -147,6 +152,18 @@ public Object createCompletion(@Valid @RequestBody ChatCompletionsRequest reques "Failed to create ReActAgent: agentProvider returned null")); } + // Register schema-only tools from request if provided + if (request.getTools() != null && !request.getTools().isEmpty()) { + var toolSchemas = toolConverter.convertToToolSchemas(request.getTools()); + if (!toolSchemas.isEmpty()) { + agent.getToolkit().registerSchemas(toolSchemas); + log.debug( + "Registered {} schema-only tools from request: requestId={}", + toolSchemas.size(), + requestId); + } + } + // Convert all messages from the request List messages = messageConverter.convertMessages(request.getMessages()); if (messages.isEmpty()) { @@ -230,6 +247,18 @@ public Flux> createCompletionStream( "Failed to create ReActAgent: agentProvider returned null")); } + // Register schema-only tools from request if provided + if (request.getTools() != null && !request.getTools().isEmpty()) { + var toolSchemas = toolConverter.convertToToolSchemas(request.getTools()); + if (!toolSchemas.isEmpty()) { + agent.getToolkit().registerSchemas(toolSchemas); + log.debug( + "Registered {} schema-only tools from request: requestId={}", + toolSchemas.size(), + requestId); + } + } + // Convert all messages from the request List messages = messageConverter.convertMessages(request.getMessages()); if (messages.isEmpty()) { diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/test/java/io/agentscope/spring/boot/chat/web/ChatCompletionsControllerTest.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/test/java/io/agentscope/spring/boot/chat/web/ChatCompletionsControllerTest.java index 93b20a786..d60b2d8cc 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/test/java/io/agentscope/spring/boot/chat/web/ChatCompletionsControllerTest.java +++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/test/java/io/agentscope/spring/boot/chat/web/ChatCompletionsControllerTest.java @@ -27,6 +27,7 @@ import io.agentscope.core.ReActAgent; import io.agentscope.core.chat.completions.builder.ChatCompletionsResponseBuilder; import io.agentscope.core.chat.completions.converter.ChatMessageConverter; +import io.agentscope.core.chat.completions.converter.OpenAIToolConverter; import io.agentscope.core.chat.completions.model.ChatCompletionsRequest; import io.agentscope.core.chat.completions.model.ChatCompletionsResponse; import io.agentscope.core.chat.completions.model.ChatMessage; @@ -61,6 +62,7 @@ class ChatCompletionsControllerTest { private ChatMessageConverter messageConverter; private ChatCompletionsResponseBuilder responseBuilder; private ChatCompletionsStreamingService streamingService; + private OpenAIToolConverter toolConverter; private ReActAgent mockAgent; @SuppressWarnings("unchecked") @@ -70,6 +72,7 @@ void setUp() { messageConverter = mock(ChatMessageConverter.class); responseBuilder = mock(ChatCompletionsResponseBuilder.class); streamingService = mock(ChatCompletionsStreamingService.class); + toolConverter = mock(OpenAIToolConverter.class); mockAgent = mock(ReActAgent.class); // Default: agentProvider returns mockAgent @@ -77,7 +80,11 @@ void setUp() { controller = new ChatCompletionsController( - agentProvider, messageConverter, responseBuilder, streamingService); + agentProvider, + messageConverter, + responseBuilder, + streamingService, + toolConverter); } @Nested From d369c91d669842b2284f2ef3c65b18cae39bd2d0 Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Sun, 11 Jan 2026 16:41:01 +0800 Subject: [PATCH 02/53] style: format code --- .../core/chat/completions/converter/OpenAIToolConverter.java | 1 - .../io/agentscope/core/chat/completions/model/OpenAITool.java | 1 - .../core/chat/completions/model/OpenAIToolFunction.java | 1 - 3 files changed, 3 deletions(-) diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java index fd8c8ef07..5f8013b8b 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java @@ -127,4 +127,3 @@ public ToolSchema convertToToolSchema(OpenAITool tool) { return schemas.isEmpty() ? null : schemas.get(0); } } - diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java index 560b3e8b7..1dd16b0cc 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAITool.java @@ -80,4 +80,3 @@ public void setFunction(OpenAIToolFunction function) { this.function = function; } } - diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java index da7537716..a0ac995c1 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/OpenAIToolFunction.java @@ -93,4 +93,3 @@ public void setStrict(Boolean strict) { this.strict = strict; } } - From c037f7f8bcaf38ed4d7912cf209f6249cf6dba5a Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Mon, 26 Jan 2026 00:18:12 +0800 Subject: [PATCH 03/53] fix: fix tool accumulate --- .../agent/accumulator/ReasoningContext.java | 37 +++++---- .../accumulator/ToolCallsAccumulator.java | 2 +- .../io/agentscope/core/tool/ToolExecutor.java | 27 +++--- .../accumulator/ReasoningContextTest.java | 48 +++++++++++ .../ChatCompletionsWebApplication.java | 83 +++++++++++++++++++ .../ChatCompletionsResponseBuilder.java | 20 ++++- .../model/ChatCompletionsChunk.java | 22 ++--- .../core/chat/completions/model/ToolCall.java | 44 +++++++++- .../ChatCompletionsStreamingAdapter.java | 24 +++++- .../model/ChatCompletionsChunkTest.java | 46 ++++++++++ .../chat/completions/model/ToolCallTest.java | 29 +++++++ .../ChatCompletionsStreamingAdapterTest.java | 32 +++---- 12 files changed, 356 insertions(+), 58 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java index d2cec4a9a..a898580f9 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java @@ -199,35 +199,38 @@ private Msg buildChunkMsg(ContentBlock block) { } /** - * Enrich a ToolUseBlock with the correct tool call ID. + * Enrich a ToolUseBlock with accumulated content from the accumulator. * *

For fragments (placeholder names like "__fragment__"), the original block may not have - * the correct ID. This method retrieves the ID from the accumulator and creates a new block - * with the correct ID, allowing users to properly concatenate chunks. + * the correct ID. This method assigns the current tool call ID if missing. * - * @param block The original ToolUseBlock - * @return A ToolUseBlock with the correct ID + *

IMPORTANT: For streaming responses, this returns the ORIGINAL fragment (delta), NOT the + * accumulated content. OpenAI's streaming API requires deltas, and clients accumulate them. + * + * @param block The original ToolUseBlock fragment + * @return The fragment with ID enriched if needed */ private ToolUseBlock enrichToolUseBlockWithId(ToolUseBlock block) { - // If the block already has an ID, return it as-is + // If block already has an ID, return as-is (it's a delta fragment) if (block.getId() != null && !block.getId().isEmpty()) { return block; } - // Get the current tool call ID from the accumulator + // For fragments without ID, assign the current tool call ID String currentId = toolCallsAcc.getCurrentToolCallId(); - if (currentId == null || currentId.isEmpty()) { - return block; + if (currentId != null && !currentId.isEmpty()) { + // Return a new block with the ID set, but keeping original content (delta) + return ToolUseBlock.builder() + .id(currentId) + .name(block.getName()) + .input(block.getInput()) + .content(block.getContent()) + .metadata(block.getMetadata()) + .build(); } - // Create a new block with the correct ID - return ToolUseBlock.builder() - .id(currentId) - .name(block.getName()) - .input(block.getInput()) - .content(block.getContent()) - .metadata(block.getMetadata()) - .build(); + // Fallback: return original block + return block; } /** diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java index 44bcedbcd..06b8a75c2 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java @@ -96,7 +96,7 @@ ToolUseBlock build() { if (parsed != null) { finalArgs.putAll(parsed); } - } catch (Exception ignored) { + } catch (Exception e) { // Parsing failed, keep empty args } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java index 9471d9a23..493fee784 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java @@ -145,17 +145,22 @@ private Mono executeCore(ToolCallParam param) { } } - // Validate input against schema - String validationError = - ToolValidator.validateInput(toolCall.getContent(), tool.getParameters()); - if (validationError != null) { - String errorMsg = - String.format( - "Parameter validation failed for tool '%s': %s\n" - + "Please correct the parameters and try again.", - toolCall.getName(), validationError); - logger.debug(errorMsg); - return Mono.just(ToolResultBlock.error(errorMsg)); + // Skip parameter validation for schema-only tools + // They will be executed externally, so validation should happen on the client side + boolean isSchemaOnlyTool = tool instanceof SchemaOnlyTool; + if (!isSchemaOnlyTool) { + // Validate input against schema for regular tools + String validationError = + ToolValidator.validateInput(toolCall.getContent(), tool.getParameters()); + if (validationError != null) { + String errorMsg = + String.format( + "Parameter validation failed for tool '%s': %s\n" + + "Please correct the parameters and try again.", + toolCall.getName(), validationError); + logger.debug(errorMsg); + return Mono.just(ToolResultBlock.error(errorMsg)); + } } // Merge context diff --git a/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java b/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java index 467b93949..de920b425 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java @@ -296,4 +296,52 @@ void testToolCallsDoNotBlockTextEmission() { // Verify text is accumulated correctly assertEquals("Let me check the weather for you.", context.getAccumulatedText()); } + + @Test + @DisplayName("Should emit delta fragments not accumulated content for streaming tool calls") + void testToolCallStreamingEmitsDeltaNotAccumulated() { + // First chunk - tool call start with partial arguments + ToolUseBlock toolUse1 = + ToolUseBlock.builder().id("call_1").name("search").content("{\"q").build(); + + // Second chunk - continuation (fragment without ID) + ToolUseBlock toolUse1Fragment1 = + ToolUseBlock.builder().name("__fragment__").content("uery\": \"").build(); + + // Third chunk - completion (fragment without ID) + ToolUseBlock toolUse1Fragment2 = + ToolUseBlock.builder().name("__fragment__").content("test\"}").build(); + + ChatResponse chunk1 = ChatResponse.builder().id("msg-1").content(List.of(toolUse1)).build(); + + ChatResponse chunk2 = + ChatResponse.builder().id("msg-1").content(List.of(toolUse1Fragment1)).build(); + + ChatResponse chunk3 = + ChatResponse.builder().id("msg-1").content(List.of(toolUse1Fragment2)).build(); + + List msgs1 = context.processChunk(chunk1); + List msgs2 = context.processChunk(chunk2); + List msgs3 = context.processChunk(chunk3); + + // All chunks should be emitted + assertEquals(1, msgs1.size()); + assertEquals(1, msgs2.size()); + assertEquals(1, msgs3.size()); + + // Verify emitted chunks contain delta content, not accumulated + ToolUseBlock emitted1 = msgs1.get(0).getFirstContentBlock(ToolUseBlock.class); + assertEquals("{\"q", emitted1.getContent()); + + ToolUseBlock emitted2 = msgs2.get(0).getFirstContentBlock(ToolUseBlock.class); + assertEquals("uery\": \"", emitted2.getContent()); + + ToolUseBlock emitted3 = msgs3.get(0).getFirstContentBlock(ToolUseBlock.class); + assertEquals("test\"}", emitted3.getContent()); + + // Verify accumulated tool call has complete content + ToolUseBlock accumulated = context.getAccumulatedToolCall("call_1"); + assertNotNull(accumulated); + assertEquals("{\"query\": \"test\"}", accumulated.getContent()); + } } diff --git a/agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java b/agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java index 82e392672..03455c7f5 100644 --- a/agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java +++ b/agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java @@ -97,6 +97,89 @@ private static void printStartupInfo() { """); System.out.println("\nNote: Accept: text/event-stream header is optional when stream=true"); System.out.println("==================================================="); + System.out.println("\nChat completion with Tool Schema (Tool Suspend).\n"); + System.out.println( + """ + curl -N -X POST http://localhost:8080/v1/chat/completions \\ + -H 'Content-Type: application/json' \\ + -d '{ + "model": "qwen3-max", + "stream": true, + "messages": [ + { "role": "user", "content": "What is the weather in Hangzhou?" } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get the current weather for a city", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "The city name" + } + }, + "required": ["city"] + } + } + } + ] + }' + """); + System.out.println("\nNote: Tools are registered as schema-only tools, triggering tool"); + System.out.println(" suspension. The response will include tool_calls with"); + System.out.println(" finish_reason='tool_calls'. Execute tools externally, then"); + System.out.println(" send tool results in the next request:"); + System.out.println( + """ + + curl -N -X POST http://localhost:8080/v1/chat/completions \\ + -H 'Content-Type: application/json' \\ + -d '{ + "model": "qwen3-max", + "stream": true, + "messages": [ + { "role": "user", "content": "What is the weather in Hangzhou?" }, + { + "role": "assistant", + "tool_calls": [{ + "id": "call_abc123", + "type": "function", + "function": { + "name": "get_weather", + "arguments": "{\\"city\\":\\"Hangzhou\\"}" + } + }] + }, + { + "role": "tool", + "tool_call_id": "call_abc123", + "name": "get_weather", + "content": "Sunny, 25°C" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get the current weather for a city", + "parameters": { + "type": "object", + "properties": { + "city": { "type": "string", "description": "The city name" } + }, + "required": ["city"] + } + } + } + ] + }' + """); + System.out.println("==================================================="); System.out.println( "\n⚠️ Important: stream=false with Accept: text/event-stream will return error"); System.out.println( diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java index 0f3c89735..77a495705 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java @@ -212,11 +212,29 @@ public String extractTextContent(Msg msg) { /** * Convert a ToolUseBlock to a ToolCall, serializing the input Map to JSON string. * + *

Prioritizes the content field (raw JSON string) over the input Map, as some providers + * like DashScope store arguments in the content field. + * * @param block The ToolUseBlock to convert * @return The OpenAI-compatible ToolCall */ private ToolCall convertToolUseBlockToToolCall(ToolUseBlock block) { - String argumentsJson = serializeMapToJson(block.getInput()); + // Prioritize content field (raw JSON string) over input map + // DashScope and some providers store arguments in content field + String argumentsJson; + String content = block.getContent(); + Map input = block.getInput(); + + if (content != null && !content.isEmpty()) { + argumentsJson = content; + } else if (input != null && !input.isEmpty()) { + // Only serialize input if it's not empty + argumentsJson = serializeMapToJson(input); + } else { + // Both content and input are empty - use empty object for non-streaming + argumentsJson = "{}"; + } + return new ToolCall(block.getId(), block.getName(), argumentsJson); } diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunk.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunk.java index ccdb158ae..6c8e187ad 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunk.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunk.java @@ -148,6 +148,10 @@ public static ChatCompletionsChunk toolCallChunk( * standard OpenAI streaming response (since OpenAI doesn't execute tools), AgentScope's * ReActAgent executes tools internally, so we expose the results in the stream. * + *

Important: In OpenAI's streaming API specification, delta.role can only be + * "assistant" or "user". The role "tool" is not supported in streaming responses. Therefore, + * tool results are formatted as assistant content with a prefix indicating the tool name. + * *

Example output: * * 

@@ -159,10 +163,8 @@ public static ChatCompletionsChunk toolCallChunk(
      *   "choices": [{
      *     "index": 0,
      *     "delta": {
-     *       "role": "tool",
-     *       "tool_call_id": "call_abc",
-     *       "name": "get_weather",
-     *       "content": "The weather is sunny..."
+     *       "role": "assistant",
+     *       "content": "[Tool: get_weather] The weather is sunny..."
      *     }
      *   }]
      * }
@@ -170,20 +172,20 @@ public static ChatCompletionsChunk toolCallChunk(
      *
      * @param id Request ID
      * @param model Model name
-     * @param toolCallId The ID of the tool call this result corresponds to
+     * @param toolCallId The ID of the tool call this result corresponds to (currently unused in streaming)
      * @param toolName The name of the tool that was executed
      * @param content The tool execution result content
-     * @return ChatCompletionsChunk with tool result
+     * @return ChatCompletionsChunk with tool result formatted as assistant content
      */
     public static ChatCompletionsChunk toolResultChunk(
             String id, String model, String toolCallId, String toolName, String content) {
         ChatCompletionsChunk chunk = new ChatCompletionsChunk(id, model);
 
         ChatMessage delta = new ChatMessage();
-        delta.setRole("tool");
-        delta.setToolCallId(toolCallId);
-        delta.setName(toolName);
-        delta.setContent(content);
+        delta.setRole("assistant");
+        // Format tool result as assistant content for streaming compatibility
+        // OpenAI streaming API does not support role: "tool" in delta
+        delta.setContent("[Tool: " + toolName + "] " + content);
 
         ChatChoice choice = new ChatChoice();
         choice.setIndex(0);
diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ToolCall.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ToolCall.java
index 80db55184..47636f4bd 100644
--- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ToolCall.java
+++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ToolCall.java
@@ -15,13 +15,15 @@
  */
 package io.agentscope.core.chat.completions.model;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+
 /**
  * Represents a tool call in OpenAI-compatible format.
  *
  * 
This DTO is used to serialize tool calls in the conversation context, allowing clients to
  * reconstruct the full conversation history including tool invocations.
  *
- * 
Example JSON:
+ * 
Example JSON (non-streaming):
  *
  * 
{@code
  * {
@@ -33,9 +35,26 @@
  *   }
  * }
  * }

+ *
+ * 
Example JSON (streaming with index):
+ *
+ * 
{@code
+ * {
+ *   "index": 0,
+ *   "id": "call_abc123",
+ *   "type": "function",
+ *   "function": {
+ *     "name": "get_weather",
+ *     "arguments": "{\"city\":\"Hangzhou\"}"
+ *   }
+ * }
+ * }

  */
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public class ToolCall {
 
+    private Integer index;
+
     private String id;
 
     private String type = "function";
@@ -58,6 +77,29 @@ public ToolCall(String id, String name, String arguments) {
         this.function = new FunctionCall(name, arguments);
     }
 
+    /**
+     * Creates a new tool call with index (for streaming).
+     *
+     * @param index Index in the tool_calls array
+     * @param id Unique identifier for this tool call
+     * @param name Function name
+     * @param arguments JSON string of function arguments
+     */
+    public ToolCall(Integer index, String id, String name, String arguments) {
+        this.index = index;
+        this.id = id;
+        this.type = "function";
+        this.function = new FunctionCall(name, arguments);
+    }
+
+    public Integer getIndex() {
+        return index;
+    }
+
+    public void setIndex(Integer index) {
+        this.index = index;
+    }
+
     public String getId() {
         return id;
     }
diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java
index 54c584b01..800de52ee 100644
--- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java
+++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java
@@ -196,13 +196,33 @@ private Flux convertEventToChunksInternal(
         // Extract tool calls (only for REASONING events from assistant)
         if (event.getType() == EventType.REASONING) {
             List toolCalls = new ArrayList<>();
+            int toolCallIndex = 0;
             for (ContentBlock block : contentBlocks) {
                 if (block instanceof ToolUseBlock) {
                     ToolUseBlock toolUseBlock = (ToolUseBlock) block;
-                    String argumentsJson = serializeMapToJson(toolUseBlock.getInput());
+                    // Prioritize content field (raw JSON string) over input map
+                    // DashScope and some providers store arguments in content field
+                    String argumentsJson;
+                    String content = toolUseBlock.getContent();
+                    Map input = toolUseBlock.getInput();
+
+                    if (content != null && !content.isEmpty()) {
+                        argumentsJson = content;
+                    } else if (input != null && !input.isEmpty()) {
+                        // Only serialize input if it's not empty
+                        argumentsJson = serializeMapToJson(input);
+                    } else {
+                        // Both content and input are empty - use empty string for streaming
+                        // This allows clients to accumulate subsequent chunks correctly
+                        argumentsJson = "";
+                    }
                     toolCalls.add(
                             new ToolCall(
-                                    toolUseBlock.getId(), toolUseBlock.getName(), argumentsJson));
+                                    toolCallIndex,
+                                    toolUseBlock.getId(),
+                                    toolUseBlock.getName(),
+                                    argumentsJson));
+                    toolCallIndex++;
                 }
             }
 
diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunkTest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunkTest.java
index 7b42fe065..4171245d7 100644
--- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunkTest.java
+++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunkTest.java
@@ -137,6 +137,52 @@ void shouldHandleMultipleToolCalls() {
         }
     }
 
+    @Nested
+    @DisplayName("Tool Result Chunk Tests")
+    class ToolResultChunkTests {
+
+        @Test
+        @DisplayName("Should create tool result chunk correctly")
+        void shouldCreateToolResultChunkCorrectly() {
+            ChatCompletionsChunk chunk =
+                    ChatCompletionsChunk.toolResultChunk(
+                            "req-123", "gpt-4", "call-1", "get_weather", "Sunny, 25°C");
+
+            assertEquals("req-123", chunk.getId());
+            assertEquals("gpt-4", chunk.getModel());
+            assertNotNull(chunk.getChoices());
+            assertEquals(1, chunk.getChoices().size());
+
+            ChatChoice choice = chunk.getChoices().get(0);
+            assertEquals(0, choice.getIndex());
+            assertNotNull(choice.getDelta());
+            assertEquals("assistant", choice.getDelta().getRole());
+            assertEquals("[Tool: get_weather] Sunny, 25°C", choice.getDelta().getContent());
+        }
+
+        @Test
+        @DisplayName("Should format tool result with tool name prefix")
+        void shouldFormatToolResultWithToolNamePrefix() {
+            ChatCompletionsChunk chunk =
+                    ChatCompletionsChunk.toolResultChunk(
+                            "req-123", "gpt-4", "call-1", "search", "Result content");
+
+            String content = chunk.getChoices().get(0).getDelta().getContent();
+            assertTrue(content.startsWith("[Tool: search] "));
+            assertTrue(content.contains("Result content"));
+        }
+
+        @Test
+        @DisplayName("Should handle empty tool result content")
+        void shouldHandleEmptyToolResultContent() {
+            ChatCompletionsChunk chunk =
+                    ChatCompletionsChunk.toolResultChunk(
+                            "req-123", "gpt-4", "call-1", "empty_tool", "");
+
+            assertEquals("[Tool: empty_tool] ", chunk.getChoices().get(0).getDelta().getContent());
+        }
+    }
+
     @Nested
     @DisplayName("Finish Chunk Tests")
     class FinishChunkTests {
diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ToolCallTest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ToolCallTest.java
index b5c732fe3..bc46416fd 100644
--- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ToolCallTest.java
+++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/model/ToolCallTest.java
@@ -52,10 +52,37 @@ void shouldCreateToolCallWithAllParameters() {
 
             assertEquals("call-123", toolCall.getId());
             assertEquals("function", toolCall.getType());
+            assertNull(toolCall.getIndex());
             assertNotNull(toolCall.getFunction());
             assertEquals("get_weather", toolCall.getFunction().getName());
             assertEquals("{\"city\":\"Hangzhou\"}", toolCall.getFunction().getArguments());
         }
+
+        @Test
+        @DisplayName("Should create tool call with index for streaming")
+        void shouldCreateToolCallWithIndexForStreaming() {
+            ToolCall toolCall =
+                    new ToolCall(0, "call-123", "get_weather", "{\"city\":\"Hangzhou\"}");
+
+            assertEquals(0, toolCall.getIndex());
+            assertEquals("call-123", toolCall.getId());
+            assertEquals("function", toolCall.getType());
+            assertNotNull(toolCall.getFunction());
+            assertEquals("get_weather", toolCall.getFunction().getName());
+            assertEquals("{\"city\":\"Hangzhou\"}", toolCall.getFunction().getArguments());
+        }
+
+        @Test
+        @DisplayName("Should create tool call with multiple indices")
+        void shouldCreateToolCallWithMultipleIndices() {
+            ToolCall toolCall1 = new ToolCall(0, "call-1", "tool1", "{}");
+            ToolCall toolCall2 = new ToolCall(1, "call-2", "tool2", "{}");
+            ToolCall toolCall3 = new ToolCall(2, "call-3", "tool3", "{}");
+
+            assertEquals(0, toolCall1.getIndex());
+            assertEquals(1, toolCall2.getIndex());
+            assertEquals(2, toolCall3.getIndex());
+        }
     }
 
     @Nested
@@ -104,10 +131,12 @@ void shouldSetAndGetAllProperties() {
 
             toolCall.setId("custom-id");
             toolCall.setType("custom-type");
+            toolCall.setIndex(5);
             toolCall.setFunction(new ToolCall.FunctionCall("func", "{}"));
 
             assertEquals("custom-id", toolCall.getId());
             assertEquals("custom-type", toolCall.getType());
+            assertEquals(5, toolCall.getIndex());
             assertNotNull(toolCall.getFunction());
             assertEquals("func", toolCall.getFunction().getName());
         }
diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapterTest.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapterTest.java
index 4f4e79214..3cac3976c 100644
--- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapterTest.java
+++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/test/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapterTest.java
@@ -295,16 +295,13 @@ void shouldExtractToolResultFromToolResultEvents() {
                             chunk -> {
                                 assertNotNull(chunk.getChoices());
                                 assertEquals(1, chunk.getChoices().size());
+                                // Tool results are now formatted as assistant content for streaming
+                                // compatibility
                                 assertEquals(
-                                        "tool", chunk.getChoices().get(0).getDelta().getRole());
+                                        "assistant",
+                                        chunk.getChoices().get(0).getDelta().getRole());
                                 assertEquals(
-                                        "call-123",
-                                        chunk.getChoices().get(0).getDelta().getToolCallId());
-                                assertEquals(
-                                        "get_weather",
-                                        chunk.getChoices().get(0).getDelta().getName());
-                                assertEquals(
-                                        "Sunny, 25°C",
+                                        "[Tool: get_weather] Sunny, 25°C",
                                         chunk.getChoices().get(0).getDelta().getContent());
                             })
                     .verifyComplete();
@@ -330,20 +327,23 @@ void shouldHandleMultipleToolResultsInSingleEvent() {
             StepVerifier.create(result)
                     .assertNext(
                             chunk -> {
+                                // Tool results are now formatted as assistant content with tool
+                                // name
+                                // prefix
                                 assertEquals(
-                                        "call-1",
-                                        chunk.getChoices().get(0).getDelta().getToolCallId());
+                                        "assistant",
+                                        chunk.getChoices().get(0).getDelta().getRole());
                                 assertEquals(
-                                        "Result A",
+                                        "[Tool: tool_a] Result A",
                                         chunk.getChoices().get(0).getDelta().getContent());
                             })
                     .assertNext(
                             chunk -> {
                                 assertEquals(
-                                        "call-2",
-                                        chunk.getChoices().get(0).getDelta().getToolCallId());
+                                        "assistant",
+                                        chunk.getChoices().get(0).getDelta().getRole());
                                 assertEquals(
-                                        "Result B",
+                                        "[Tool: tool_b] Result B",
                                         chunk.getChoices().get(0).getDelta().getContent());
                             })
                     .verifyComplete();
@@ -493,7 +493,9 @@ void shouldHandleEmptyToolInput() {
                                                 .get(0)
                                                 .getFunction()
                                                 .getArguments();
-                                assertEquals("{}", args);
+                                // For streaming, empty arguments should be empty string, not "{}"
+                                // This allows clients to accumulate subsequent chunks correctly
+                                assertEquals("", args);
                             })
                     .verifyComplete();
         }

From a6b9a4a13f880ab5f46ab66bd09e212f5fa6a25a Mon Sep 17 00:00:00 2001
From: Alexxigang <37231458+Alexxigang@users.noreply.github.com>
Date: Thu, 15 Jan 2026 09:34:57 +0800
Subject: [PATCH 04/53] fix(core): enable custom config for  mcpclientbuilder
 (#509)

---
 .../core/tool/mcp/McpClientBuilder.java       |  72 ++++++
 .../core/tool/mcp/McpClientBuilderTest.java   | 223 ++++++++++++++++++
 2 files changed, 295 insertions(+)

diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java b/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java
index 67097097b..077350b32 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java
@@ -28,6 +28,7 @@
 import java.net.URI;
 import java.net.URLDecoder;
 import java.net.URLEncoder;
+import java.net.http.HttpClient;
 import java.nio.charset.StandardCharsets;
 import java.time.Duration;
 import java.util.ArrayList;
@@ -35,6 +36,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Consumer;
 import java.util.stream.Collectors;
 import reactor.core.publisher.Mono;
 
@@ -136,6 +138,30 @@ public McpClientBuilder sseTransport(String url) {
         return this;
     }
 
+    /**
+     * Customizes the HTTP client for SSE transport (only applicable after calling sseTransport).
+     * This allows advanced HTTP client configuration like HTTP/2, custom timeouts, SSL settings, etc.
+     *
+     * 
Example usage for HTTP/2:
+     * 
{@code
+     * McpClientWrapper client = McpClientBuilder.create("mcp")
+     *     .sseTransport("https://example.com/sse")
+     *     .customizeSseClient(clientBuilder ->
+     *         clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2))
+     *     .buildAsync()
+     *     .block();
+     * }

+     *
+     * @param customizer consumer to customize the HttpClient.Builder
+     * @return this builder
+     */
+    public McpClientBuilder customizeSseClient(Consumer customizer) {
+        if (transportConfig instanceof SseTransportConfig) {
+            ((SseTransportConfig) transportConfig).customizeHttpClient(customizer);
+        }
+        return this;
+    }
+
     /**
      * Configures HTTP StreamableHTTP transport for stateless connections.
      *
@@ -147,6 +173,30 @@ public McpClientBuilder streamableHttpTransport(String url) {
         return this;
     }
 
+    /**
+     * Customizes the HTTP client for StreamableHTTP transport (only applicable after calling streamableHttpTransport).
+     * This allows advanced HTTP client configuration like HTTP/2, custom timeouts, SSL settings, etc.
+     *
+     * 
Example usage for HTTP/2:
+     * 
{@code
+     * McpClientWrapper client = McpClientBuilder.create("mcp")
+     *     .streamableHttpTransport("https://example.com/http")
+     *     .customizeStreamableHttpClient(clientBuilder ->
+     *         clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2))
+     *     .buildAsync()
+     *     .block();
+     * }

+     *
+     * @param customizer consumer to customize the HttpClient.Builder
+     * @return this builder
+     */
+    public McpClientBuilder customizeStreamableHttpClient(Consumer customizer) {
+        if (transportConfig instanceof StreamableHttpTransportConfig) {
+            ((StreamableHttpTransportConfig) transportConfig).customizeHttpClient(customizer);
+        }
+        return this;
+    }
+
     /**
      * Adds an HTTP header (only applicable for HTTP transports).
      *
@@ -434,6 +484,7 @@ protected String extractEndpoint() {
 
     private static class SseTransportConfig extends HttpTransportConfig {
         private HttpClientSseClientTransport.Builder clientTransportBuilder = null;
+        private Consumer httpClientCustomizer = null;
 
         public SseTransportConfig(String url) {
             super(url);
@@ -444,11 +495,21 @@ public void clientTransportBuilder(
             this.clientTransportBuilder = clientTransportBuilder;
         }
 
+        public void customizeHttpClient(Consumer customizer) {
+            this.httpClientCustomizer = customizer;
+        }
+
         @Override
         public McpClientTransport createTransport() {
             if (clientTransportBuilder == null) {
                 clientTransportBuilder = HttpClientSseClientTransport.builder(url);
             }
+
+            // Apply HTTP client customization if provided
+            if (httpClientCustomizer != null) {
+                clientTransportBuilder.customizeClient(httpClientCustomizer);
+            }
+
             clientTransportBuilder.sseEndpoint(extractEndpoint());
 
             if (!headers.isEmpty()) {
@@ -464,6 +525,7 @@ public McpClientTransport createTransport() {
 
     private static class StreamableHttpTransportConfig extends HttpTransportConfig {
         private HttpClientStreamableHttpTransport.Builder clientTransportBuilder = null;
+        private Consumer httpClientCustomizer = null;
 
         public StreamableHttpTransportConfig(String url) {
             super(url);
@@ -474,11 +536,21 @@ public void clientTransportBuilder(
             this.clientTransportBuilder = clientTransportBuilder;
         }
 
+        public void customizeHttpClient(Consumer customizer) {
+            this.httpClientCustomizer = customizer;
+        }
+
         @Override
         public McpClientTransport createTransport() {
             if (clientTransportBuilder == null) {
                 clientTransportBuilder = HttpClientStreamableHttpTransport.builder(url);
             }
+
+            // Apply HTTP client customization if provided
+            if (httpClientCustomizer != null) {
+                clientTransportBuilder.customizeClient(httpClientCustomizer);
+            }
+
             clientTransportBuilder.endpoint(extractEndpoint());
 
             if (!headers.isEmpty()) {
diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java
index dad0b37c7..c1adfe786 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java
@@ -962,4 +962,227 @@ void testExtractEndpoint_WithTrailingSlash() throws Exception {
         String endpoint = invokeExtractEndpoint(url);
         assertEquals("/api/", endpoint);
     }
+
+    // ==================== HTTP Client Customization Tests ====================
+
+    @Test
+    void testCustomizeSseClient_WithValidCustomizer() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("custom-sse-client")
+                        .sseTransport("https://mcp.example.com/sse")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    // Customize HTTP client (e.g., set HTTP/2, timeouts, etc.)
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+        assertEquals("custom-sse-client", wrapper.getName());
+    }
+
+    @Test
+    void testCustomizeSseClient_MultipleCustomizations() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("multi-custom-sse")
+                        .sseTransport("https://mcp.example.com/sse")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                })
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    // Second customization should also be applied
+                                    clientBuilder.followRedirects(
+                                            java.net.http.HttpClient.Redirect.NORMAL);
+                                })
+                        .header("Authorization", "Bearer token")
+                        .queryParam("tenant", "test");
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeSseClient_OnStdioTransport_ShouldBeIgnored() {
+        // Customizing SSE client on stdio transport should not cause errors (just ignored)
+        McpClientBuilder builder =
+                McpClientBuilder.create("stdio-client")
+                        .stdioTransport("python", "-m", "mcp_server_time")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeSseClient_OnStreamableHttpTransport_ShouldBeIgnored() {
+        // Customizing SSE client on streamable http transport should not cause errors (just
+        // ignored)
+        McpClientBuilder builder =
+                McpClientBuilder.create("http-client")
+                        .streamableHttpTransport("https://mcp.example.com/http")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeStreamableHttpClient_WithValidCustomizer() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("custom-http-client")
+                        .streamableHttpTransport("https://mcp.example.com/http")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    // Customize HTTP client
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(15));
+                                });
+
+        McpClientWrapper wrapper = builder.buildSync();
+        assertNotNull(wrapper);
+        assertEquals("custom-http-client", wrapper.getName());
+    }
+
+    @Test
+    void testCustomizeStreamableHttpClient_MultipleCustomizations() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("multi-custom-http")
+                        .streamableHttpTransport("https://mcp.example.com/http")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                })
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder.followRedirects(
+                                            java.net.http.HttpClient.Redirect.ALWAYS);
+                                })
+                        .header("X-API-Key", "secret")
+                        .queryParam("version", "v1");
+
+        McpClientWrapper wrapper = builder.buildSync();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeStreamableHttpClient_OnStdioTransport_ShouldBeIgnored() {
+        // Customizing streamable http client on stdio transport should not cause errors (just
+        // ignored)
+        McpClientBuilder builder =
+                McpClientBuilder.create("stdio-client")
+                        .stdioTransport("python", "server.py")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeStreamableHttpClient_OnSseTransport_ShouldBeIgnored() {
+        // Customizing streamable http client on SSE transport should not cause errors (just
+        // ignored)
+        McpClientBuilder builder =
+                McpClientBuilder.create("sse-client")
+                        .sseTransport("https://mcp.example.com/sse")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder.connectTimeout(Duration.ofSeconds(10));
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeSseClient_WithHttp2() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("http2-sse-client")
+                        .sseTransport("https://mcp.example.com/sse")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2);
+                                });
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCustomizeStreamableHttpClient_WithHttp2() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("http2-streamable-client")
+                        .streamableHttpTransport("https://mcp.example.com/http")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2);
+                                });
+
+        McpClientWrapper wrapper = builder.buildSync();
+        assertNotNull(wrapper);
+    }
+
+    @Test
+    void testCompleteConfiguration_WithClientCustomization() {
+        Map headers = new HashMap<>();
+        headers.put("Authorization", "Bearer token123");
+        headers.put("X-Client-Version", "1.0.7");
+
+        Map queryParams = new HashMap<>();
+        queryParams.put("tenant", "acme");
+        queryParams.put("env", "production");
+
+        McpClientBuilder builder =
+                McpClientBuilder.create("fully-configured-client")
+                        .sseTransport("https://mcp.example.com/api/sse")
+                        .customizeSseClient(
+                                clientBuilder -> {
+                                    clientBuilder
+                                            .version(java.net.http.HttpClient.Version.HTTP_2)
+                                            .connectTimeout(Duration.ofSeconds(10))
+                                            .followRedirects(
+                                                    java.net.http.HttpClient.Redirect.NORMAL);
+                                })
+                        .headers(headers)
+                        .queryParams(queryParams)
+                        .timeout(Duration.ofSeconds(120))
+                        .initializationTimeout(Duration.ofSeconds(45));
+
+        McpClientWrapper wrapper = builder.buildAsync().block();
+        assertNotNull(wrapper);
+        assertEquals("fully-configured-client", wrapper.getName());
+    }
+
+    @Test
+    void testFluentApi_AllFeaturesCombined() {
+        McpClientBuilder builder =
+                McpClientBuilder.create("all-features-client")
+                        .streamableHttpTransport("https://mcp.higress.ai/mcp/http?base=param")
+                        .customizeStreamableHttpClient(
+                                clientBuilder -> {
+                                    clientBuilder
+                                            .connectTimeout(Duration.ofSeconds(15))
+                                            .version(java.net.http.HttpClient.Version.HTTP_1_1);
+                                })
+                        .header("Authorization", "Bearer secret-token")
+                        .header("X-Request-ID", "req-12345")
+                        .queryParam("tenant", "my-tenant")
+                        .queryParam("version", "v2")
+                        .timeout(Duration.ofMinutes(3))
+                        .initializationTimeout(Duration.ofSeconds(60));
+
+        McpClientWrapper wrapper = builder.buildSync();
+        assertNotNull(wrapper);
+        assertEquals("all-features-client", wrapper.getName());
+        assertFalse(wrapper.isInitialized());
+    }
 }

From 200477267e8bae649f05af2a3f8464acdf65dd8d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:14:24 +0800
Subject: [PATCH 05/53] chore(deps): bump org.postgresql:postgresql from 42.7.4
 to 42.7.8 (#567)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bumps [org.postgresql:postgresql](https://github.com/pgjdbc/pgjdbc) from
42.7.4 to 42.7.8.


Release notes

Sourced from org.postgresql:postgresql's
releases.




v42.7.8


Notable changes:


    

  • Releases are signed with a new PGP key which is generated at GitHub
Actions and stored only there @​vlsi (#3701)
    • 



Changes



🐛 Bug Fixes


    

  • fix: avoid IllegalStateException: Timer already cancelled when
StatementCancelTimerTask.run throws a runtime error @​vlsi (#3778)
    • 

  • fix: avoid NullPointerException when cancelling a query if cancel
key is not known yet @​vlsi (#3780)
    • 

  • fix: unable to open replication connection to servers < 12 @​vlsi (#3678)
    • 



🧰 Maintenance


    

  • chore: fix published project name @​vlsi (#3809)
    • 

  • chore: update publish to Central Portal task name after bumping nmcp
@​vlsi (#3808)
    • 

  • fix(deps): update com.gradleup.nmcp to 1.1.0 @​vlsi (#3807)
    • 

  • Revert "fix: Update release plugin config to use .set(...) for
props and inject nexus creds via gradle props" @​vlsi (#3803)
    • 

  • chore: group com.gradleup.nmcp version updates @​vlsi (#3805)
    • 

  • chore: use bump org.apache.bcel:bcel test dependency in
testCompileClasspath as well @​vlsi (#3775)
    • 

  • Fix typo in PGReplicationStream.java @​atorik (#3758)
    • 

  • chore: remove JDK versions from the key workflow names @​vlsi (#3759)
    • 

  • chore: add GitHub Actions workflow for generating release PGP key @​vlsi (#3701)
    • 

  • chore: replace StandardCharsets with Charsets to simplify code @​vlsi (#3751)
    • 

  • chore: migrate publish workflow to Central Portal publishing via
com.gradleup.nmcp @​vlsi (#3686)
    • 

  • chore: adjust the default branch name for ossf scorecard scan @​vlsi (#3697)
    • 

  • chore: add top-level read-only permissions for GitHub Actions when
missing @​vlsi (#3696)
    • 

  • chore: use config:best-practices preset for Renovate @​vlsi (#3687)
    • 






... (truncated)





Changelog

Sourced from org.postgresql:postgresql's
changelog.




[42.7.8] (2025-09-18)


Added



Changed


    

  • perf: remove QUERY_ONESHOT flag when calling getMetaData [PR #3783](pgjdbc/pgjdbc#3783)
    • 

  • perf: use BufferedInputStream with
FileInputStream [PR #3750](pgjdbc/pgjdbc#3750)
    • 

  • perf: enable server-prepared statements for DatabaseMetaData
    • 



Fixed


    

  • fix: avoid NullPointerException when cancelling a query if cancel
key is not known yet
    • 

  • fix: Change "PST" timezone in TimestampTest to
"Pacific Standard Time" [PR #3774](pgjdbc/pgjdbc#3774)
    • 

  • fix: traverse the current dimension to get the correct pos in
PgArray#calcRemainingDataLength [PR #3746](pgjdbc/pgjdbc#3746)
    • 

  • fix: make sure getImportedExportedKeys returns columns in consistent
order
    • 

  • fix: Add "SELF_REFERENCING_COL_NAME" field to getTables'
ResultSetMetaData to fix NullPointerException [PR #3660](pgjdbc/pgjdbc#3660)
    • 

  • fix: unable to open replication connection to servers < 12
    • 

  • fix: avoid closing statement caused by driver's internal
ResultSet#close()
    • 

  • fix: return empty metadata for empty catalog names as it was
before
    • 

  • fix: Incorrect class comparison in PGXmlFactoryFactory
validation
    • 



[42.7.7] (2025-06-10)


Security


    

  • security: Client Allows Fallback to Insecure Authentication
Despite channelBinding=require configuration.
Fix channel binding required handling to reject non-SASL
authentication
Previously, when channel binding was set to "require", the
driver would silently ignore this
requirement for non-SASL authentication methods. This could lead to a
false sense of security
when channel binding was explicitly requested but not actually enforced.
The fix ensures that when
channel binding is set to "require", the driver will reject
connections that use
non-SASL authentication methods or when SASL authentication has not
completed properly.
See the Security
Advisory for more detail. Reported by George MacKerron
The following CVE-2025-49146
has been issued
    • 



Added


    

  • test: Added ChannelBindingRequiredTest to verify proper behavior of
channel binding settings
    • 



[42.7.6]


Features


    

  • fix: Enhanced DatabaseMetadata.getIndexInfo() method, added index
comment as REMARKS property [PR #3513](pgjdbc/pgjdbc#3513)
    • 



Performance Improvements


    

  • performance: Improve ResultSetMetadata.fetchFieldMetaData by using
IN row values instead of UNION ALL for improved query performance (later
reverted) [PR #3510](pgjdbc/pgjdbc#3510)
    • 

  • feat:Use a single simple query for all startup parameters, so
groupStartupParameters is no longer needed [PR #3613](pgjdbc/pgjdbc#3613)
    • 

  • 



Bug Fixes


Protocol & Connection Handling





... (truncated)





Commits

    

  • 9a5492d
chore: fix published project name
    • 

  • ca064f8
chore: update publish to Central Portal task name after bumping
nmcp
    • 

  • 3d97bb8
fix: avoid IllegalStateException: Timer already cancelled when
StatementCanc...
    • 

  • faa7dfc
test: move BaseTest4 to testkit module
    • 

  • dbf2847
fix(deps): update com.gradleup.nmcp to 1.1.0
    • 

  • 9245e26
Revert "fix: Update release plugin config to use .set(...) for
props and inje...
    • 

  • 8e833c3
chore: group com.gradleup.nmcp version updates
    • 

  • ec5a088
fix: Update release plugin config to use .set(...) for props and inject
nexus...
    • 

  • c03db58
update version to 42.7.8 (#3801)
    • 

  • 50ff169
change logs for version 42.7.8 (#3797)
    • 

  • Additional commits viewable in compare
view
    • 








[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=org.postgresql:postgresql&package-manager=maven&previous-version=42.7.4&new-version=42.7.8)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index eeb05f3be..c2bc897b7 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -83,7 +83,7 @@
         2.0.17
         1.16.2
         2.6.12
-        42.7.4
+        42.7.8
         0.1.6
         3.0.6
         5.5.1

From 036c919763d82e8a55be9dcb9843674a59f32226 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:14:39 +0800
Subject: [PATCH 06/53] chore(deps): bump com.aliyun:bailian20231229 from 2.6.2
 to 2.7.0 (#566)

Bumps
[com.aliyun:bailian20231229](https://github.com/aliyun/alibabacloud-java-sdk)
from 2.6.2 to 2.7.0.


Commits







[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.aliyun:bailian20231229&package-manager=maven&previous-version=2.6.2&new-version=2.7.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index c2bc897b7..52d84e322 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -76,7 +76,7 @@
         33.5.0-jre
         1.34.0
         2.22.5
-        2.6.2
+        2.7.0
         4.15.0
         2.11.1
         0.17.0

From 8da5b1ecaf951731db4f8800f83f60e061c2d9be Mon Sep 17 00:00:00 2001
From: Me1iodas 
Date: Thu, 15 Jan 2026 17:27:14 +0800
Subject: [PATCH 07/53] fix: Fix the observability of the callTool pipeline.
 (#576)

## AgentScope-Java Version

1.0.7

## Description

### Background
During tool calls in AgentScope-Java, observability tracing was found to
be broken, making it impossible to fully track the execution process of
tool invocations.

### Purpose
Fix the observability loss issue in the `callTool` method chain to
ensure the tool invocation process can be completely traced and
monitored.

## 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
---
 .../main/java/io/agentscope/core/tool/ToolExecutor.java  | 9 +++++++--
 .../src/main/java/io/agentscope/core/tool/Toolkit.java   | 6 +++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java
index 493fee784..baa7df872 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java
@@ -19,6 +19,7 @@
 import io.agentscope.core.message.ToolResultBlock;
 import io.agentscope.core.message.ToolUseBlock;
 import io.agentscope.core.model.ExecutionConfig;
+import io.agentscope.core.tracing.TracerRegistry;
 import io.agentscope.core.util.ExceptionUtils;
 import java.time.Duration;
 import java.util.HashMap;
@@ -56,6 +57,7 @@ class ToolExecutor {
 
     private static final Logger logger = LoggerFactory.getLogger(ToolExecutor.class);
 
+    private final Toolkit toolkit;
     private final ToolRegistry toolRegistry;
     private final ToolGroupManager groupManager;
     private final ToolkitConfig config;
@@ -67,22 +69,25 @@ class ToolExecutor {
      * Create a tool executor with Reactor Schedulers (recommended).
      */
     ToolExecutor(
+            Toolkit toolkit,
             ToolRegistry toolRegistry,
             ToolGroupManager groupManager,
             ToolkitConfig config,
             ToolMethodInvoker methodInvoker) {
-        this(toolRegistry, groupManager, config, methodInvoker, null);
+        this(toolkit, toolRegistry, groupManager, config, methodInvoker, null);
     }
 
     /**
      * Create a tool executor with custom executor service.
      */
     ToolExecutor(
+            Toolkit toolkit,
             ToolRegistry toolRegistry,
             ToolGroupManager groupManager,
             ToolkitConfig config,
             ToolMethodInvoker methodInvoker,
             ExecutorService executorService) {
+        this.toolkit = toolkit;
         this.toolRegistry = toolRegistry;
         this.groupManager = groupManager;
         this.config = config;
@@ -107,7 +112,7 @@ void setChunkCallback(BiConsumer callback) {
      * @return Mono containing execution result
      */
     Mono execute(ToolCallParam param) {
-        return executeCore(param);
+        return TracerRegistry.get().callTool(this.toolkit, param, () -> executeCore(param));
     }
 
     /**
diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java b/agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java
index 1a2216564..5d52f916f 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java
@@ -24,7 +24,6 @@
 import io.agentscope.core.tool.subagent.SubAgentConfig;
 import io.agentscope.core.tool.subagent.SubAgentProvider;
 import io.agentscope.core.tool.subagent.SubAgentTool;
-import io.agentscope.core.tracing.TracerRegistry;
 import java.lang.reflect.Method;
 import java.util.Collections;
 import java.util.List;
@@ -108,6 +107,7 @@ public Toolkit(ToolkitConfig config) {
         if (config != null && config.hasCustomExecutor()) {
             this.executor =
                     new ToolExecutor(
+                            this,
                             toolRegistry,
                             groupManager,
                             this.config,
@@ -115,7 +115,7 @@ public Toolkit(ToolkitConfig config) {
                             config.getExecutorService());
         } else {
             this.executor =
-                    new ToolExecutor(toolRegistry, groupManager, this.config, methodInvoker);
+                    new ToolExecutor(this, toolRegistry, groupManager, this.config, methodInvoker);
         }
     }
 
@@ -474,7 +474,7 @@ public void setChunkCallback(BiConsumer callback)
      * @return Mono containing execution result
      */
     public Mono callTool(ToolCallParam param) {
-        return TracerRegistry.get().callTool(this, param, () -> executor.execute(param));
+        return executor.execute(param);
     }
 
     /**

From 02cc98f9c2de28def58a89ecb48dd720cc50441e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 09:51:58 +0800
Subject: [PATCH 08/53] chore(deps-dev): bump com.google.genai:google-genai
 from 1.34.0 to 1.35.0 (#579)

Bumps
[com.google.genai:google-genai](https://github.com/googleapis/java-genai)
from 1.34.0 to 1.35.0.


Release notes

Sourced from com.google.genai:google-genai's
releases.




v1.35.0


1.35.0
(2026-01-14)


Features








Changelog

Sourced from com.google.genai:google-genai's
changelog.




1.35.0
(2026-01-14)


Features








Commits







[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.google.genai:google-genai&package-manager=maven&previous-version=1.34.0&new-version=1.35.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index 52d84e322..d3a4522d8 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -74,7 +74,7 @@
         5.21.0
         6.0.2
         33.5.0-jre
-        1.34.0
+        1.35.0
         2.22.5
         2.7.0
         4.15.0

From 7222c9d43763f69d60be77d288d88011389d22bf Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 09:52:19 +0800
Subject: [PATCH 09/53] chore(deps): bump org.postgresql:postgresql from 42.7.8
 to 42.7.9 (#580)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bumps [org.postgresql:postgresql](https://github.com/pgjdbc/pgjdbc) from
42.7.8 to 42.7.9.


Release notes

Sourced from org.postgresql:postgresql's
releases.




v42.7.9


Changes



🐛 Bug Fixes


    

  • fix: close temporary lob descriptors that are used internally in
PreparedStatement#setBlob @​vlsi (#3903)
    • 

  • fix: avoid memory leaks in Java <= 21 caused by
Thread.inheritedAccessControlContext @​vlsi (#3886)
    • 



📝 Documentation


    

  • doc: add the new PGP signing key to the official documentation @​vlsi (#3813)
    • 



🧰 Maintenance


    

  • chore: remove unused com.github.spotbugs Gradle plugin dependency @​vlsi (#3868)
    • 

  • chore: drop SpotBugs as we do not seem to use it @​vlsi (#3834)
    • 

  • chore: bump version to 42.7.9 after 42.7.8 release @​vlsi (#3810)
    • 



⬆️ Dependencies







... (truncated)





Changelog

Sourced from org.postgresql:postgresql's
changelog.




[42.7.9] (2026-01-14)


Added



Changed


    

  • perf: optimize PGInterval.getValue() by replacing String.format with
StringBuilder
    • 

  • doc: update property quoteReturningIdentifiers default value [PR #3847](pgjdbc/pgjdbc#3847)
    • 

  • security: Use a static method forName to load all user supplied
classes. Use the Class.forName 3 parameter method and do not initilize
it unless it is a subclass of the expected class
    • 



Fixed








Commits

    

  • 79b784e
Added changelogs for version 42.7.9 (#3908)
    • 

  • 1c00ffc
doc: add the new PGP signing key to the official documentation
    • 

  • f774000
chore(deps): update actions/create-github-app-token digest to
29824e6
    • 

  • 27daf3b
chore(deps): update actions/setup-java digest to c1e3236
    • 

  • 6eb01ff
chore(deps): update codecov/codecov-action digest to 671740a
    • 

  • dbf1e57
the classloader is nullable, and remove a space (#3907)
    • 

  • 6a20574
Merge commit from fork
    • 

  • c07721a
fix: incorrect pg_stat_replication.reply_time calculation (#3906)
    • 

  • 83023f3
fix: close temporary lob descriptors that are used internally in
PreparedStat...
    • 

  • 62c9805
fix: issue #3892,
PGXAConnection.prepare(Xid) should return XA_RDONLY if the ...
    • 

  • Additional commits viewable in compare
view
    • 








[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=org.postgresql:postgresql&package-manager=maven&previous-version=42.7.8&new-version=42.7.9)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index d3a4522d8..f7c61a057 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -83,7 +83,7 @@
         2.0.17
         1.16.2
         2.6.12
-        42.7.8
+        42.7.9
         0.1.6
         3.0.6
         5.5.1

From 908b8053dfa3c2448dca5ad76a9c060d6dd13f8e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 09:52:33 +0800
Subject: [PATCH 10/53] chore(deps): bump org.springframework:spring-webflux
 from 7.0.2 to 7.0.3 (#581)

Bumps
[org.springframework:spring-webflux](https://github.com/spring-projects/spring-framework)
from 7.0.2 to 7.0.3.


Release notes

Sourced from org.springframework:spring-webflux's
releases.




v7.0.3


:star: New Features


    

  • DisconnectedClientHelper should detect presence of
RestClientException and WebClientException separately #36141
    • 

  • Deprecate PagedListHolder and
PropertyComparator for removal #36139
    • 

  • Add DataAccessException and MessagingException to the excluded
outermost exceptions in DisconnectedClientHelper #36134
    • 

  • Support property placeholders in HTTP service registry #36126
    • 

  • Introduce Spring property to disable context pausing for tests #36117
    • 

  • Retain original requested bean class for SpringContainedBean #36116
    • 

  • Add task rejection support to SyncTaskExecutor's concurrency
throttle #36114
    • 

  • Precompute PropertyDescriptor array in
SimpleBeanInfoFactory #36112
    • 

  • Add option for @ConcurrencyLimit to throw rejection
exception #36109
    • 

  • Support HttpComponents 5.6 #36100
    • 

  • Fix double encoding in DefaultApiVersionInserter #36097
    • 

  • Optimize single-char wildcard path matching performance #36095
    • 

  • Allow WebFlux ApiVersionResolver to return a Mono #36084
    • 

  • Configure HttpMessageConverters as a list #36083
    • 

  • HTTP Interface with an @RequestBody Object method
parameter should use class of actual value #36078
    • 

  • Consistently declare @Nullable on parameter in
equals() implementations #36075
    • 

  • Support listener registration for @Transactional
triggered method rollbacks #36073
    • 

  • Introduce generalized MethodFailureEvent for use in
EventPublicationInterceptor #36072
    • 

  • Avoid duplicate flushes in StringHttpMessageConverter #36065
    • 

  • When no API version is provided, static resources fail to load #36059
    • 

  • When no API version is provided, /error requests also
fail. #36058
    • 

  • Declare TaskCallback return value as potentially
nullable #36057
    • 

  • Fix case-insensitive semantics for LinkedCaseInsensitiveMap entrySet
#36056
    • 

  • Update to NullAway 0.12.15 and fix new warnings #36054
    • 

  • Provide alternative to execute(Retryable) which avoids
RetryException in favor of rethrowing the last original
RuntimeException #36052
    • 

  • Avoid unnecessary pausing of application contexts in the TestContext
framework #36044
    • 

  • Simplify TransactionalOperator.executeAndAwait by removing Optional
#36039
    • 

  • Deprecated MockMvcClientHttpRequestFactory is required for tests
with HTTP service interface proxy #35989
    • 

  • Introduce Jackson XML codecs #35752
    • 

  • Support listener registration for @Retryable triggered
retry executions #35382
    • 



:lady_beetle: Bug Fixes


    

  • Fix SmartFactoryBean type matching for
ResolvableType.NONE #36123
    • 

  • AbstractMessageSendingTemplate ignores headers in
convertAndSend() variant #36120
    • 

  • JmsClient.sendAndReceive() fails if headers are
included #36118
    • 

  • PropertyDescriptorUtils does not reliably resolve
overloaded write methods #36113
    • 

  • Fix context class resolution for nested types in
AbstractJacksonHttpMessageConverter #36111
    • 

  • DefaultApiVersionInserter encodes already encoded URI
#36080
    • 

  • ConverterFactory nullness mismatch with Converter #36063
    • 

  • WiretapConnector leaks data buffers when response body not consumed
#36050
    • 

  • CompilationException should not use -1 for line or column numbers
when they are unknown #36041
    • 

  • org.springframework.core.test.tools.TestCompiler.Errors should
handle case where warnings are turned into errors #36037
    • 

  • UriComponentsBuilder loses the fragment when it consists of only a
single character #36029
    • 

  • Parameter names of the handler method are null in
HandlerInterceptor::preHandle during first invocation of an endpoint #36024
    • 

  • PropertyDescriptorUtils does not reliably resolve
read/write methods in type hierarchies with generics #36019
    • 

  • Illegal reflection use against Hibernate Validator 9 on module path
#36012
    • 






... (truncated)





Commits

    

  • 02cdd36
Release v7.0.3
    • 

  • 62fd09d
Polishing
    • 

  • 9df19de
Revise wording for PauseMode documentation
    • 

  • 01a57a7
Simplify DefaultContextCache implementation by using
entrySet().removeIf()
    • 

  • b5c2003
Fix variable name
    • 

  • 5f5da06
Upgrade to JUnit 6.0.2
    • 

  • 9f19b40
Exclude DataAccessException and MessagingException in
DisconnectedClientHelper
    • 

  • a784eb0
Improve DisconnectedClientHelper to better guard
ClassNotFoundException
    • 

  • fa40406
Avoid unnecessary pausing of application contexts for tests
    • 

  • 948af8b
Fix typo in Javadoc
    • 

  • Additional commits viewable in compare
view
    • 








[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=org.springframework:spring-webflux&package-manager=maven&previous-version=7.0.2&new-version=7.0.3)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index f7c61a057..58d9a3766 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -99,7 +99,7 @@
         7.2.0
         3.3.2
         2.5.2
-        7.0.2
+        7.0.3
         4.0.1
         3.1.1
         3.0.0

From 782cc2ee0c41a0917bc90d112af6df32d7422c5a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 09:52:48 +0800
Subject: [PATCH 11/53] chore(deps): bump com.aliyun:bailian20231229 from 2.7.0
 to 2.7.1 (#582)

Bumps
[com.aliyun:bailian20231229](https://github.com/aliyun/alibabacloud-java-sdk)
from 2.7.0 to 2.7.1.


Commits







[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.aliyun:bailian20231229&package-manager=maven&previous-version=2.7.0&new-version=2.7.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---



Dependabot commands and options



You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)





Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index 58d9a3766..a138575d0 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -76,7 +76,7 @@
         33.5.0-jre
         1.35.0
         2.22.5
-        2.7.0
+        2.7.1
         4.15.0
         2.11.1
         0.17.0

From ae88f1f2e2ec243e6e25f88e30023224420458bd Mon Sep 17 00:00:00 2001
From: "fish[3]" <745866137@qq.com>
Date: Fri, 16 Jan 2026 09:56:39 +0800
Subject: [PATCH 12/53] fix(example): Inconsistent groupManager in
 ReActAgent.Builder#build due to toolkit copying (#560)

---
 .../io/agentscope/examples/quickstart/ToolGroupExample.java   | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/ToolGroupExample.java b/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/ToolGroupExample.java
index 87068e7be..0c485ec16 100644
--- a/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/ToolGroupExample.java
+++ b/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/ToolGroupExample.java
@@ -45,9 +45,6 @@ public static void main(String[] args) throws Exception {
         // Configure tool groups
         Toolkit toolkit = configureToolGroups();
 
-        // Register meta-tool for autonomous tool group management
-        toolkit.registerMetaTool();
-
         System.out.println("\n=== Meta Tool Registered ===");
         System.out.println(
                 "The agent now has access to 'reset_equipped_tools' meta-tool to autonomously");
@@ -66,6 +63,7 @@ public static void main(String[] args) throws Exception {
                                         .formatter(new DashScopeChatFormatter())
                                         .build())
                         .toolkit(toolkit)
+                        .enableMetaTool(true)
                         .memory(new InMemoryMemory())
                         .build();
 

From cfadc9d2dadba14e2ab97ce0ec1f488f20477c05 Mon Sep 17 00:00:00 2001
From: Albumen Kevin 
Date: Fri, 16 Jan 2026 10:15:34 +0800
Subject: [PATCH 13/53] feat(hook): add summary phase hook support for
 ReActAgent (#577)

---
 .../java/io/agentscope/core/ReActAgent.java   | 171 +++++---
 .../agentscope/core/agent/StreamOptions.java  |  82 ++++
 .../agentscope/core/agent/StreamingHook.java  |  21 +
 .../io/agentscope/core/hook/HookEvent.java    |   2 +-
 .../agentscope/core/hook/HookEventType.java   |   9 +
 .../core/hook/PostSummaryEvent.java           | 103 +++++
 .../agentscope/core/hook/PreSummaryEvent.java | 143 +++++++
 .../core/hook/SummaryChunkEvent.java          | 106 +++++
 .../io/agentscope/core/hook/SummaryEvent.java |  83 ++++
 .../core/hook/SummaryEventTest.java           | 390 ++++++++++++++++++
 10 files changed, 1049 insertions(+), 61 deletions(-)
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/hook/PostSummaryEvent.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/hook/PreSummaryEvent.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/hook/SummaryChunkEvent.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/hook/SummaryEvent.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/hook/SummaryEventTest.java

diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java
index 9ff7076f3..bd5fe0562 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java
@@ -22,9 +22,12 @@
 import io.agentscope.core.hook.HookEvent;
 import io.agentscope.core.hook.PostActingEvent;
 import io.agentscope.core.hook.PostReasoningEvent;
+import io.agentscope.core.hook.PostSummaryEvent;
 import io.agentscope.core.hook.PreActingEvent;
 import io.agentscope.core.hook.PreReasoningEvent;
+import io.agentscope.core.hook.PreSummaryEvent;
 import io.agentscope.core.hook.ReasoningChunkEvent;
+import io.agentscope.core.hook.SummaryChunkEvent;
 import io.agentscope.core.interruption.InterruptContext;
 import io.agentscope.core.memory.InMemoryMemory;
 import io.agentscope.core.memory.LongTermMemory;
@@ -619,6 +622,50 @@ private Mono notifyPostActingHook(
     protected Mono summarizing() {
         log.debug("Maximum iterations reached. Generating summary...");
 
+        List messageList = prepareSummaryMessages();
+        GenerateOptions generateOptions = buildGenerateOptions();
+
+        return notifyPreSummaryHook(messageList, generateOptions)
+                .flatMap(
+                        preSummaryEvent -> {
+                            List effectiveMessages = preSummaryEvent.getInputMessages();
+                            GenerateOptions effectiveOptions =
+                                    preSummaryEvent.getEffectiveGenerateOptions();
+
+                            return streamAndAccumulateSummary(effectiveMessages, effectiveOptions)
+                                    .flatMap(
+                                            msg ->
+                                                    notifyPostSummaryHook(msg, effectiveOptions)
+                                                            .map(
+                                                                    postEvent -> {
+                                                                        Msg finalMsg =
+                                                                                postEvent
+                                                                                        .getSummaryMessage();
+                                                                        memory.addMessage(finalMsg);
+                                                                        return finalMsg;
+                                                                    }));
+                        })
+                .onErrorResume(this::handleSummaryError);
+    }
+
+    private Mono streamAndAccumulateSummary(
+            List messages, GenerateOptions generateOptions) {
+        return model.stream(messages, null, generateOptions)
+                .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk))
+                .reduce(
+                        new ReasoningContext(getName()),
+                        (ctx, chunk) -> {
+                            List streamedMessages = ctx.processChunk(chunk);
+                            for (Msg streamedMessage : streamedMessages) {
+                                notifySummaryChunk(streamedMessage, ctx, generateOptions)
+                                        .subscribe();
+                            }
+                            return ctx;
+                        })
+                .map(ReasoningContext::buildFinalMessage);
+    }
+
+    private List prepareSummaryMessages() {
         List messageList = prepareMessages();
         messageList.add(
                 Msg.builder()
@@ -632,67 +679,29 @@ protected Mono summarizing() {
                                                     + " summarizing the current situation.")
                                         .build())
                         .build());
+        return messageList;
+    }
 
-        return model.stream(messageList, null, buildGenerateOptions())
-                .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk))
-                .reduce(
-                        new ReasoningContext(getName()),
-                        (ctx, chunk) -> {
-                            ctx.processChunk(chunk);
-                            return ctx;
-                        })
-                .map(ReasoningContext::buildFinalMessage)
-                .flatMap(
-                        msg -> {
-                            if (msg != null) {
-                                memory.addMessage(msg);
-                                return Mono.just(msg);
-                            }
-                            Msg fallback =
-                                    Msg.builder()
-                                            .name(getName())
-                                            .role(MsgRole.ASSISTANT)
-                                            .content(
-                                                    TextBlock.builder()
-                                                            .text(
-                                                                    String.format(
-                                                                            "Maximum iterations"
-                                                                                + " (%d) reached."
-                                                                                + " Unable to"
-                                                                                + " generate"
-                                                                                + " summary.",
-                                                                            maxIters))
-                                                            .build())
-                                            .build();
-                            memory.addMessage(fallback);
-                            return Mono.just(fallback);
-                        })
-                .onErrorResume(
-                        error -> {
-                            if (error instanceof InterruptedException) {
-                                return Mono.error(error);
-                            }
-                            log.error("Error generating summary", error);
-                            Msg errorMsg =
-                                    Msg.builder()
-                                            .name(getName())
-                                            .role(MsgRole.ASSISTANT)
-                                            .content(
-                                                    TextBlock.builder()
-                                                            .text(
-                                                                    String.format(
-                                                                            "Maximum iterations"
-                                                                                + " (%d) reached."
-                                                                                + " Error"
-                                                                                + " generating"
-                                                                                + " summary: %s",
-                                                                            maxIters,
-                                                                            error.getMessage()))
-                                                            .build())
-                                            .build();
-                            memory.addMessage(errorMsg);
-                            return Mono.just(errorMsg);
-                        });
+    private Mono handleSummaryError(Throwable error) {
+        if (error instanceof InterruptedException) {
+            return Mono.error(error);
+        }
+        log.error("Error generating summary", error);
+        Msg errorMsg =
+                Msg.builder()
+                        .name(getName())
+                        .role(MsgRole.ASSISTANT)
+                        .content(
+                                TextBlock.builder()
+                                        .text(
+                                                String.format(
+                                                        "Maximum iterations (%d) reached."
+                                                                + " Error generating summary: %s",
+                                                        maxIters, error.getMessage()))
+                                        .build())
+                        .build();
+        memory.addMessage(errorMsg);
+        return Mono.just(errorMsg);
     }
 
     // ==================== Helper Methods ====================
@@ -829,6 +838,48 @@ private Mono notifyReasoningChunk(Msg chunkMsg, ReasoningContext context)
         return Mono.empty();
     }
 
+    // ==================== Summary Hook Notification Methods ====================
+
+    private Mono notifyPreSummaryHook(
+            List msgs, GenerateOptions generateOptions) {
+        return notifyHooks(
+                new PreSummaryEvent(
+                        this, model.getModelName(), generateOptions, msgs, maxIters, maxIters));
+    }
+
+    private Mono notifyPostSummaryHook(Msg msg, GenerateOptions generateOptions) {
+        return notifyHooks(new PostSummaryEvent(this, model.getModelName(), generateOptions, msg));
+    }
+
+    private Mono notifySummaryChunk(
+            Msg chunkMsg, ReasoningContext context, GenerateOptions generateOptions) {
+        ContentBlock content = chunkMsg.getFirstContentBlock();
+
+        ContentBlock accumulatedContent = null;
+        if (content instanceof TextBlock) {
+            accumulatedContent = TextBlock.builder().text(context.getAccumulatedText()).build();
+        } else if (content instanceof ThinkingBlock) {
+            accumulatedContent =
+                    ThinkingBlock.builder().thinking(context.getAccumulatedThinking()).build();
+        }
+
+        if (accumulatedContent != null) {
+            Msg accumulated =
+                    Msg.builder()
+                            .id(chunkMsg.getId())
+                            .name(chunkMsg.getName())
+                            .role(chunkMsg.getRole())
+                            .content(accumulatedContent)
+                            .build();
+            SummaryChunkEvent event =
+                    new SummaryChunkEvent(
+                            this, model.getModelName(), generateOptions, chunkMsg, accumulated);
+            return Flux.fromIterable(getSortedHooks()).flatMap(hook -> hook.onEvent(event)).then();
+        }
+
+        return Mono.empty();
+    }
+
     @Override
     protected Mono handleInterrupt(InterruptContext context, Msg... originalArgs) {
         String recoveryText = "I noticed that you have interrupted me. What can I do for you?";
diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/StreamOptions.java b/agentscope-core/src/main/java/io/agentscope/core/agent/StreamOptions.java
index 07f2a7d25..36a77db02 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/agent/StreamOptions.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/agent/StreamOptions.java
@@ -88,6 +88,22 @@ public class StreamOptions {
      */
     private final boolean includeActingChunk;
 
+    /**
+     * Whether to include the incremental chunks from summary generation during streaming.
+     * 

+     * If false, intermediate summary chunk emissions should be filtered out by the stream
+     * implementation.
+     */
+    private final boolean includeSummaryChunk;
+
+    /**
+     * Whether to include the final consolidated summary output in the response.
+     * 

+     * If false, final summary result emissions should be filtered out by the stream
+     * implementation.
+     */
+    private final boolean includeSummaryResult;
+
     /**
      * Private constructor called by the builder.
      *
@@ -99,6 +115,8 @@ private StreamOptions(Builder builder) {
         this.includeReasoningChunk = builder.includeReasoningChunk;
         this.includeReasoningResult = builder.includeReasoningResult;
         this.includeActingChunk = builder.includeActingChunk;
+        this.includeSummaryChunk = builder.includeSummaryChunk;
+        this.includeSummaryResult = builder.includeSummaryResult;
     }
 
     /**
@@ -175,6 +193,30 @@ public boolean isIncludeActingChunk() {
         return includeActingChunk;
     }
 
+    /**
+     * Whether summary chunk emissions should be included.
+     *
+     * 
Summary chunks are the incremental outputs from summary generation when max iterations
+     * is reached.

+     *
+     * @return true if summary chunks should be included
+     */
+    public boolean isIncludeSummaryChunk() {
+        return includeSummaryChunk;
+    }
+
+    /**
+     * Whether the final summary result should be included.
+     *
+     * 
The summary result is the final consolidated summary output when max iterations
+     * is reached.

+     *
+     * @return true if the final summary result should be included
+     */
+    public boolean isIncludeSummaryResult() {
+        return includeSummaryResult;
+    }
+
     /**
      * Check if a specific event type should be streamed.
      *
@@ -198,6 +240,16 @@ public boolean shouldIncludeReasoningEmission(boolean isChunk) {
         return isChunk ? includeReasoningChunk : includeReasoningResult;
     }
 
+    /**
+     * Convenience method for stream implementations to decide whether to emit a summary subtype.
+     *
+     * @param isChunk true if the summary emission is an incremental chunk, false if it is the final result
+     * @return true if this summary emission should be included
+     */
+    public boolean shouldIncludeSummaryEmission(boolean isChunk) {
+        return isChunk ? includeSummaryChunk : includeSummaryResult;
+    }
+
     /** Builder for {@link StreamOptions}. */
     public static class Builder {
         private Set eventTypes = EnumSet.of(EventType.ALL);
@@ -207,6 +259,8 @@ public static class Builder {
         private boolean includeReasoningChunk = true;
         private boolean includeReasoningResult = true;
         private boolean includeActingChunk = true;
+        private boolean includeSummaryChunk = true;
+        private boolean includeSummaryResult = true;
 
         /**
          * Set which event types to stream.
@@ -281,6 +335,34 @@ public Builder includeActingChunk(boolean includeActingChunk) {
             return this;
         }
 
+        /**
+         * Include or exclude summary chunk emissions.
+         *
+         * 
When {@link EventType#SUMMARY} is enabled, summary generation may emit intermediate
+         * chunks. Set to false to hide these and only receive the final summary result.

+         *
+         * @param includeSummaryChunk true to include chunk emissions, false to filter them out
+         * @return this builder
+         */
+        public Builder includeSummaryChunk(boolean includeSummaryChunk) {
+            this.includeSummaryChunk = includeSummaryChunk;
+            return this;
+        }
+
+        /**
+         * Include or exclude the final consolidated summary result emission.
+         *
+         * 
When {@link EventType#SUMMARY} is enabled, the final summary result is emitted after
+         * generation completes. Set to false to hide it.

+         *
+         * @param includeSummaryResult true to include the final summary result, false to filter it out
+         * @return this builder
+         */
+        public Builder includeSummaryResult(boolean includeSummaryResult) {
+            this.includeSummaryResult = includeSummaryResult;
+            return this;
+        }
+
         public StreamOptions build() {
             return new StreamOptions(this);
         }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/StreamingHook.java b/agentscope-core/src/main/java/io/agentscope/core/agent/StreamingHook.java
index 1577c840d..e632361da 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/agent/StreamingHook.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/agent/StreamingHook.java
@@ -20,7 +20,9 @@
 import io.agentscope.core.hook.HookEvent;
 import io.agentscope.core.hook.PostActingEvent;
 import io.agentscope.core.hook.PostReasoningEvent;
+import io.agentscope.core.hook.PostSummaryEvent;
 import io.agentscope.core.hook.ReasoningChunkEvent;
+import io.agentscope.core.hook.SummaryChunkEvent;
 import io.agentscope.core.message.ContentBlock;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.MsgRole;
@@ -95,6 +97,25 @@ public  Mono onEvent(T event) {
                 emitEvent(EventType.TOOL_RESULT, toolMsg, false);
             }
             return Mono.just(event);
+        } else if (event instanceof PostSummaryEvent) {
+            PostSummaryEvent e = (PostSummaryEvent) event;
+            // Summary generation completed
+            if (options.shouldStream(EventType.SUMMARY)
+                    && options.shouldIncludeSummaryEmission(false)) {
+                emitEvent(EventType.SUMMARY, e.getSummaryMessage(), true);
+            }
+            return Mono.just(event);
+        } else if (event instanceof SummaryChunkEvent) {
+            SummaryChunkEvent e = (SummaryChunkEvent) event;
+            // Intermediate summary chunk
+            if (options.shouldStream(EventType.SUMMARY)
+                    && options.shouldIncludeSummaryEmission(true)) {
+                // Use incremental or accumulated based on StreamOptions
+                Msg msgToEmit =
+                        options.isIncremental() ? e.getIncrementalChunk() : e.getAccumulated();
+                emitEvent(EventType.SUMMARY, msgToEmit, false);
+            }
+            return Mono.just(event);
         }
         return Mono.just(event);
     }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/HookEvent.java b/agentscope-core/src/main/java/io/agentscope/core/hook/HookEvent.java
index 0fcbc7114..c3f8c2974 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/hook/HookEvent.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/HookEvent.java
@@ -41,7 +41,7 @@
  * @see HookEventType
  */
 public abstract sealed class HookEvent
-        permits PreCallEvent, PostCallEvent, ReasoningEvent, ActingEvent, ErrorEvent {
+        permits PreCallEvent, PostCallEvent, ReasoningEvent, ActingEvent, SummaryEvent, ErrorEvent {
 
     private final HookEventType type;
     private final Agent agent;
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/HookEventType.java b/agentscope-core/src/main/java/io/agentscope/core/hook/HookEventType.java
index c01cad657..b466ea053 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/hook/HookEventType.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/HookEventType.java
@@ -49,6 +49,15 @@ public enum HookEventType {
     /** During tool execution streaming */
     ACTING_CHUNK,
 
+    /** Before summary generation (when max iterations reached) */
+    PRE_SUMMARY,
+
+    /** After summary generation completes */
+    POST_SUMMARY,
+
+    /** During summary streaming */
+    SUMMARY_CHUNK,
+
     /** When an error occurs */
     ERROR
 }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/PostSummaryEvent.java b/agentscope-core/src/main/java/io/agentscope/core/hook/PostSummaryEvent.java
new file mode 100644
index 000000000..a5edce767
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/PostSummaryEvent.java
@@ -0,0 +1,103 @@
+/*
+ * 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.hook;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.model.GenerateOptions;
+
+/**
+ * Event fired after summary generation completes.
+ *
+ * 
Modifiable: Yes - {@link #setSummaryMessage(Msg)}
+ *
+ * 
Context:
+ * 
    
+ *   
  • {@link #getAgent()} - The agent instance
    • 
+ *   
  • {@link #getMemory()} - Agent's memory
    • 
+ *   
  • {@link #getModelName()} - The model name
    • 
+ *   
  • {@link #getGenerateOptions()} - The generation options
    • 
+ *   
  • {@link #getSummaryMessage()} - The summary result (modifiable)
    • 
+ * 

+ *
+ * 
Note: This event is fired after the summary has been generated, allowing hooks
+ * to modify the final summary message before it's returned.
+ *
+ * 
Use Cases:
+ * 
    
+ *   
  • Filter or modify the summary content
    • 
+ *   
  • Add metadata to the summary message
    • 
+ *   
  • Log the summary result
    • 
+ *   
  • Request to stop the agent via {@link #stopAgent()}
    • 
+ * 

+ */
+public final class PostSummaryEvent extends SummaryEvent {
+
+    private Msg summaryMessage;
+    private boolean stopRequested = false;
+
+    /**
+     * Constructor for PostSummaryEvent.
+     *
+     * @param agent The agent instance (must not be null)
+     * @param modelName The model name (must not be null)
+     * @param generateOptions The generation options (may be null)
+     * @param summaryMessage The summary result message (may be null)
+     */
+    public PostSummaryEvent(
+            Agent agent, String modelName, GenerateOptions generateOptions, Msg summaryMessage) {
+        super(HookEventType.POST_SUMMARY, agent, modelName, generateOptions);
+        this.summaryMessage = summaryMessage;
+    }
+
+    /**
+     * Get the summary result message.
+     *
+     * @return The summary message, may be null
+     */
+    public Msg getSummaryMessage() {
+        return summaryMessage;
+    }
+
+    /**
+     * Modify the summary result message.
+     *
+     * @param summaryMessage The new summary message
+     */
+    public void setSummaryMessage(Msg summaryMessage) {
+        this.summaryMessage = summaryMessage;
+    }
+
+    /**
+     * Request to stop the agent after this summary phase.
+     *
+     * 
When called, the agent will return the summary message as the final result.
+     * This is primarily for consistency with other event types; since summary is typically
+     * the last phase, this mainly serves as a signal for logging or metrics purposes.
+     */
+    public void stopAgent() {
+        this.stopRequested = true;
+    }
+
+    /**
+     * Check if a stop has been requested.
+     *
+     * @return true if {@link #stopAgent()} has been called, false otherwise
+     */
+    public boolean isStopRequested() {
+        return stopRequested;
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/PreSummaryEvent.java b/agentscope-core/src/main/java/io/agentscope/core/hook/PreSummaryEvent.java
new file mode 100644
index 000000000..9cea0adf1
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/PreSummaryEvent.java
@@ -0,0 +1,143 @@
+/*
+ * 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.hook;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.model.GenerateOptions;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Event fired before summary generation when max iterations is reached.
+ *
+ * 
Modifiable: Yes - {@link #setInputMessages(List)}, {@link #setGenerateOptions(GenerateOptions)}
+ *
+ * 
Context:
+ * 
    
+ *   
  • {@link #getAgent()} - The agent instance
    • 
+ *   
  • {@link #getMemory()} - Agent's memory
    • 
+ *   
  • {@link #getModelName()} - The model name (e.g., "qwen-plus")
    • 
+ *   
  • {@link #getGenerateOptions()} - The generation options (temperature, etc.)
    • 
+ *   
  • {@link #getInputMessages()} - Messages to send to LLM for summary (modifiable)
    • 
+ *   
  • {@link #getMaxIterations()} - The maximum iterations configured for the agent
    • 
+ *   
  • {@link #getCurrentIteration()} - The current iteration count when summary triggered
    • 
+ * 

+ *
+ * 
Use Cases:
+ * 
    
+ *   
  • Inject additional context into the summary prompt
    • 
+ *   
  • Modify the summary system instructions
    • 
+ *   
  • Change generation parameters for summary
    • 
+ *   
  • Log summary generation input
    • 
+ * 

+ */
+public final class PreSummaryEvent extends SummaryEvent {
+
+    private List inputMessages;
+    private GenerateOptions overriddenGenerateOptions;
+    private final int maxIterations;
+    private final int currentIteration;
+
+    /**
+     * Constructor for PreSummaryEvent.
+     *
+     * @param agent The agent instance (must not be null)
+     * @param modelName The model name (must not be null)
+     * @param generateOptions The generation options (may be null)
+     * @param inputMessages The messages to send to LLM for summary (must not be null)
+     * @param maxIterations The maximum iterations configured for the agent
+     * @param currentIteration The current iteration count when summary triggered
+     * @throws NullPointerException if agent, modelName, or inputMessages is null
+     */
+    public PreSummaryEvent(
+            Agent agent,
+            String modelName,
+            GenerateOptions generateOptions,
+            List inputMessages,
+            int maxIterations,
+            int currentIteration) {
+        super(HookEventType.PRE_SUMMARY, agent, modelName, generateOptions);
+        this.inputMessages =
+                new ArrayList<>(
+                        Objects.requireNonNull(inputMessages, "inputMessages cannot be null"));
+        this.maxIterations = maxIterations;
+        this.currentIteration = currentIteration;
+    }
+
+    /**
+     * Get the messages that will be sent to LLM for summary generation.
+     *
+     * @return The input messages
+     */
+    public List getInputMessages() {
+        return inputMessages;
+    }
+
+    /**
+     * Modify the messages to send to LLM for summary.
+     *
+     * @param inputMessages The new message list (must not be null)
+     * @throws NullPointerException if inputMessages is null
+     */
+    public void setInputMessages(List inputMessages) {
+        this.inputMessages = Objects.requireNonNull(inputMessages, "inputMessages cannot be null");
+    }
+
+    /**
+     * Get the maximum iterations configured for the agent.
+     *
+     * @return The maximum iterations
+     */
+    public int getMaxIterations() {
+        return maxIterations;
+    }
+
+    /**
+     * Get the current iteration count when summary was triggered.
+     *
+     * @return The current iteration count
+     */
+    public int getCurrentIteration() {
+        return currentIteration;
+    }
+
+    /**
+     * Get the effective generation options.
+     *
+     * 
Returns the overridden options if set via {@link #setGenerateOptions(GenerateOptions)},
+     * otherwise returns the original options from the parent class.
+     *
+     * @return The effective generation options
+     */
+    public GenerateOptions getEffectiveGenerateOptions() {
+        return overriddenGenerateOptions != null
+                ? overriddenGenerateOptions
+                : super.getGenerateOptions();
+    }
+
+    /**
+     * Set custom generation options for this summary call.
+     *
+     * 
This allows hooks to override the default generation options.
+     *
+     * @param generateOptions The custom generation options
+     */
+    public void setGenerateOptions(GenerateOptions generateOptions) {
+        this.overriddenGenerateOptions = generateOptions;
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryChunkEvent.java b/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryChunkEvent.java
new file mode 100644
index 000000000..e38b3db41
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryChunkEvent.java
@@ -0,0 +1,106 @@
+/*
+ * 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.hook;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.model.GenerateOptions;
+import java.util.Objects;
+
+/**
+ * Event fired during summary streaming.
+ *
+ * 
Modifiable: No (notification-only)
+ *
+ * 
Context:
+ * 
    
+ *   
  • {@link #getAgent()} - The agent instance
    • 
+ *   
  • {@link #getMemory()} - Agent's memory
    • 
+ *   
  • {@link #getModelName()} - The model name
    • 
+ *   
  • {@link #getGenerateOptions()} - The generation options
    • 
+ *   
  • {@link #getIncrementalChunk()} - Only the new content in this chunk
    • 
+ *   
  • {@link #getAccumulated()} - The full accumulated message so far
    • 
+ * 

+ *
+ * 
Use Cases:
+ * 
    
+ *   
  • Use {@link #getIncrementalChunk()} for incremental display (append-only)
    • 
+ *   
  • Use {@link #getAccumulated()} for full context display (replace entire text)
    • 
+ *   
  • Display streaming summary output in real-time
    • 
+ *   
  • Monitor summary generation progress
    • 
+ *   
  • Log streaming content
    • 
+ * 

+ *
+ * 
Example:
+ * 
{@code
+ * case SummaryChunkEvent e -> {
+ *     // Incremental mode: print only new content
+ *     System.out.print(extractText(e.getIncrementalChunk()));
+ *
+ *     // OR Cumulative mode: update entire display
+ *     ui.setText(extractText(e.getAccumulated()));
+ *
+ *     yield Mono.just(e);
+ * }
+ * }

+ */
+public final class SummaryChunkEvent extends SummaryEvent {
+
+    private final Msg incrementalChunk;
+    private final Msg accumulated;
+
+    /**
+     * Constructor for SummaryChunkEvent.
+     *
+     * @param agent The agent instance (must not be null)
+     * @param modelName The model name (must not be null)
+     * @param generateOptions The generation options (may be null)
+     * @param incrementalChunk Only the new content generated in this streaming event (must not be
+     *     null)
+     * @param accumulated The full accumulated message containing all content generated so far (must
+     *     not be null)
+     * @throws NullPointerException if agent, modelName, incrementalChunk, or accumulated is null
+     */
+    public SummaryChunkEvent(
+            Agent agent,
+            String modelName,
+            GenerateOptions generateOptions,
+            Msg incrementalChunk,
+            Msg accumulated) {
+        super(HookEventType.SUMMARY_CHUNK, agent, modelName, generateOptions);
+        this.incrementalChunk =
+                Objects.requireNonNull(incrementalChunk, "incrementalChunk cannot be null");
+        this.accumulated = Objects.requireNonNull(accumulated, "accumulated cannot be null");
+    }
+
+    /**
+     * Get only the new content generated in this streaming event.
+     *
+     * @return The incremental chunk
+     */
+    public Msg getIncrementalChunk() {
+        return incrementalChunk;
+    }
+
+    /**
+     * Get the full accumulated message containing all content generated so far.
+     *
+     * @return The accumulated message
+     */
+    public Msg getAccumulated() {
+        return accumulated;
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryEvent.java b/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryEvent.java
new file mode 100644
index 000000000..f5196f586
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/hook/SummaryEvent.java
@@ -0,0 +1,83 @@
+/*
+ * 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.hook;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.model.GenerateOptions;
+import java.util.Objects;
+
+/**
+ * Base class for summary-related events.
+ *
+ * 
This sealed class provides common context for all summary events that occur
+ * when a ReActAgent reaches its maximum iterations and generates a summary:
+ * 
    
+ *   
  • {@link #getModelName()} - The model name (e.g., "qwen-plus", "gpt-4")
    • 
+ *   
  • {@link #getGenerateOptions()} - The generation options (temperature, etc.)
    • 
+ * 

+ *
+ * 
Subclasses represent different stages of the summary process:
+ * 
    
+ *   
  • {@link PreSummaryEvent} - Before summary generation
    • 
+ *   
  • {@link SummaryChunkEvent} - During streaming
    • 
+ *   
  • {@link PostSummaryEvent} - After summary generation completes
    • 
+ * 

+ *
+ * @see PreSummaryEvent
+ * @see SummaryChunkEvent
+ * @see PostSummaryEvent
+ */
+public abstract sealed class SummaryEvent extends HookEvent
+        permits PreSummaryEvent, SummaryChunkEvent, PostSummaryEvent {
+
+    private final String modelName;
+    private final GenerateOptions generateOptions;
+
+    /**
+     * Constructor for SummaryEvent.
+     *
+     * @param type The event type (must not be null)
+     * @param agent The agent instance (must not be null)
+     * @param modelName The model name (must not be null)
+     * @param generateOptions The generation options (may be null if using model defaults)
+     * @throws NullPointerException if type, agent, or modelName is null
+     */
+    protected SummaryEvent(
+            HookEventType type, Agent agent, String modelName, GenerateOptions generateOptions) {
+        super(type, agent);
+        this.modelName = Objects.requireNonNull(modelName, "modelName cannot be null");
+        this.generateOptions = generateOptions;
+    }
+
+    /**
+     * Get the model name.
+     *
+     * @return The model name (e.g., "qwen-plus", "gpt-4")
+     */
+    public final String getModelName() {
+        return modelName;
+    }
+
+    /**
+     * Get the generation options.
+     *
+     * @return The generation options (temperature, maxTokens, etc.), or null if using model
+     *     defaults
+     */
+    public final GenerateOptions getGenerateOptions() {
+        return generateOptions;
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/hook/SummaryEventTest.java b/agentscope-core/src/test/java/io/agentscope/core/hook/SummaryEventTest.java
new file mode 100644
index 000000000..9bc2132d3
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/hook/SummaryEventTest.java
@@ -0,0 +1,390 @@
+/*
+ * 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.hook;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.agent.AgentBase;
+import io.agentscope.core.interruption.InterruptContext;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.message.MsgRole;
+import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.model.GenerateOptions;
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Mono;
+
+/**
+ * Unit tests for SummaryEvent classes.
+ *
+ * 
Tests cover:
+ * 
    
+ *   
  • Event creation with valid data
    • 
+ *   
  • Null validation in constructors and setters
    • 
+ *   
  • Context access and modifier functionality
    • 
+ * 

+ */
+@DisplayName("SummaryEvent Tests")
+class SummaryEventTest {
+
+    private Agent testAgent;
+    private Msg testMessage;
+    private List testMessages;
+    private GenerateOptions generateOptions;
+
+    @BeforeEach
+    void setUp() {
+        testAgent =
+                new AgentBase("TestAgent") {
+                    @Override
+                    protected Mono doCall(List msgs) {
+                        return Mono.just(msgs.get(0));
+                    }
+
+                    @Override
+                    protected Mono doObserve(Msg msg) {
+                        return Mono.empty();
+                    }
+
+                    @Override
+                    protected Mono handleInterrupt(
+                            InterruptContext context, Msg... originalArgs) {
+                        return Mono.just(
+                                Msg.builder()
+                                        .name(getName())
+                                        .role(MsgRole.ASSISTANT)
+                                        .content(TextBlock.builder().text("Interrupted").build())
+                                        .build());
+                    }
+                };
+
+        testMessage =
+                Msg.builder()
+                        .name("User")
+                        .role(MsgRole.USER)
+                        .content(TextBlock.builder().text("Hello").build())
+                        .build();
+
+        testMessages = new ArrayList<>(List.of(testMessage));
+        generateOptions = GenerateOptions.builder().temperature(0.7).build();
+    }
+
+    @Nested
+    @DisplayName("PreSummaryEvent Tests")
+    class PreSummaryEventTests {
+
+        @Test
+        @DisplayName("Should create event with valid data")
+        void shouldCreateEventWithValidData() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+
+            assertEquals(HookEventType.PRE_SUMMARY, event.getType());
+            assertEquals(testAgent, event.getAgent());
+            assertEquals("qwen-plus", event.getModelName());
+            assertEquals(generateOptions, event.getGenerateOptions());
+            assertEquals(testMessages, event.getInputMessages());
+            assertEquals(10, event.getMaxIterations());
+            assertEquals(10, event.getCurrentIteration());
+            assertTrue(event.getTimestamp() > 0);
+        }
+
+        @Test
+        @DisplayName("Should allow modifying input messages")
+        void shouldAllowModifyingInputMessages() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+
+            Msg newMessage =
+                    Msg.builder()
+                            .name("System")
+                            .role(MsgRole.SYSTEM)
+                            .content(TextBlock.builder().text("New instruction").build())
+                            .build();
+            List newMessages = List.of(newMessage);
+            event.setInputMessages(newMessages);
+
+            assertEquals(newMessages, event.getInputMessages());
+        }
+
+        @Test
+        @DisplayName("Should allow overriding generate options")
+        void shouldAllowOverridingGenerateOptions() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+
+            GenerateOptions newOptions = GenerateOptions.builder().temperature(0.9).build();
+            event.setGenerateOptions(newOptions);
+
+            assertEquals(newOptions, event.getEffectiveGenerateOptions());
+        }
+
+        @Test
+        @DisplayName("Should return original options when not overridden")
+        void shouldReturnOriginalOptionsWhenNotOverridden() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+
+            assertEquals(generateOptions, event.getEffectiveGenerateOptions());
+        }
+
+        @Test
+        @DisplayName("Should throw NullPointerException when inputMessages is null")
+        void shouldThrowWhenInputMessagesNull() {
+            assertThrows(
+                    NullPointerException.class,
+                    () ->
+                            new PreSummaryEvent(
+                                    testAgent, "qwen-plus", generateOptions, null, 10, 10));
+        }
+
+        @Test
+        @DisplayName("Should throw NullPointerException when setting null inputMessages")
+        void shouldThrowWhenSettingNullInputMessages() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+
+            assertThrows(NullPointerException.class, () -> event.setInputMessages(null));
+        }
+    }
+
+    @Nested
+    @DisplayName("SummaryChunkEvent Tests")
+    class SummaryChunkEventTests {
+
+        @Test
+        @DisplayName("Should create event with valid data")
+        void shouldCreateEventWithValidData() {
+            Msg incrementalChunk =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("chunk").build())
+                            .build();
+            Msg accumulated =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("accumulated chunk").build())
+                            .build();
+
+            SummaryChunkEvent event =
+                    new SummaryChunkEvent(
+                            testAgent, "qwen-plus", generateOptions, incrementalChunk, accumulated);
+
+            assertEquals(HookEventType.SUMMARY_CHUNK, event.getType());
+            assertEquals(testAgent, event.getAgent());
+            assertEquals("qwen-plus", event.getModelName());
+            assertEquals(generateOptions, event.getGenerateOptions());
+            assertEquals(incrementalChunk, event.getIncrementalChunk());
+            assertEquals(accumulated, event.getAccumulated());
+        }
+
+        @Test
+        @DisplayName("Should throw NullPointerException when incrementalChunk is null")
+        void shouldThrowWhenIncrementalChunkNull() {
+            Msg accumulated =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("accumulated").build())
+                            .build();
+
+            assertThrows(
+                    NullPointerException.class,
+                    () ->
+                            new SummaryChunkEvent(
+                                    testAgent, "qwen-plus", generateOptions, null, accumulated));
+        }
+
+        @Test
+        @DisplayName("Should throw NullPointerException when accumulated is null")
+        void shouldThrowWhenAccumulatedNull() {
+            Msg incrementalChunk =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("chunk").build())
+                            .build();
+
+            assertThrows(
+                    NullPointerException.class,
+                    () ->
+                            new SummaryChunkEvent(
+                                    testAgent,
+                                    "qwen-plus",
+                                    generateOptions,
+                                    incrementalChunk,
+                                    null));
+        }
+    }
+
+    @Nested
+    @DisplayName("PostSummaryEvent Tests")
+    class PostSummaryEventTests {
+
+        @Test
+        @DisplayName("Should create event with valid data")
+        void shouldCreateEventWithValidData() {
+            Msg summaryMessage =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("Summary").build())
+                            .build();
+
+            PostSummaryEvent event =
+                    new PostSummaryEvent(testAgent, "qwen-plus", generateOptions, summaryMessage);
+
+            assertEquals(HookEventType.POST_SUMMARY, event.getType());
+            assertEquals(testAgent, event.getAgent());
+            assertEquals("qwen-plus", event.getModelName());
+            assertEquals(generateOptions, event.getGenerateOptions());
+            assertEquals(summaryMessage, event.getSummaryMessage());
+            assertFalse(event.isStopRequested());
+        }
+
+        @Test
+        @DisplayName("Should allow null summary message")
+        void shouldAllowNullSummaryMessage() {
+            PostSummaryEvent event =
+                    new PostSummaryEvent(testAgent, "qwen-plus", generateOptions, null);
+
+            assertNull(event.getSummaryMessage());
+        }
+
+        @Test
+        @DisplayName("Should allow modifying summary message")
+        void shouldAllowModifyingSummaryMessage() {
+            Msg originalMessage =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("Original").build())
+                            .build();
+
+            PostSummaryEvent event =
+                    new PostSummaryEvent(testAgent, "qwen-plus", generateOptions, originalMessage);
+
+            Msg newMessage =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("Modified").build())
+                            .build();
+            event.setSummaryMessage(newMessage);
+
+            assertEquals(newMessage, event.getSummaryMessage());
+        }
+
+        @Test
+        @DisplayName("Should support stopAgent functionality")
+        void shouldSupportStopAgentFunctionality() {
+            PostSummaryEvent event =
+                    new PostSummaryEvent(testAgent, "qwen-plus", generateOptions, testMessage);
+
+            assertFalse(event.isStopRequested());
+            event.stopAgent();
+            assertTrue(event.isStopRequested());
+        }
+    }
+
+    @Nested
+    @DisplayName("Common SummaryEvent Tests")
+    class CommonSummaryEventTests {
+
+        @Test
+        @DisplayName("Should throw NullPointerException when agent is null")
+        void shouldThrowWhenAgentNull() {
+            assertThrows(
+                    NullPointerException.class,
+                    () ->
+                            new PreSummaryEvent(
+                                    null, "qwen-plus", generateOptions, testMessages, 10, 10));
+        }
+
+        @Test
+        @DisplayName("Should throw NullPointerException when modelName is null")
+        void shouldThrowWhenModelNameNull() {
+            assertThrows(
+                    NullPointerException.class,
+                    () ->
+                            new PreSummaryEvent(
+                                    testAgent, null, generateOptions, testMessages, 10, 10));
+        }
+
+        @Test
+        @DisplayName("Should allow null generateOptions")
+        void shouldAllowNullGenerateOptions() {
+            PreSummaryEvent event =
+                    new PreSummaryEvent(testAgent, "qwen-plus", null, testMessages, 10, 10);
+
+            assertNull(event.getGenerateOptions());
+            assertNull(event.getEffectiveGenerateOptions());
+        }
+
+        @Test
+        @DisplayName("All summary events should have correct event types")
+        void allSummaryEventsShouldHaveCorrectEventTypes() {
+            PreSummaryEvent preSummary =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+            assertEquals(HookEventType.PRE_SUMMARY, preSummary.getType());
+
+            Msg msg =
+                    Msg.builder()
+                            .name("Assistant")
+                            .role(MsgRole.ASSISTANT)
+                            .content(TextBlock.builder().text("test").build())
+                            .build();
+
+            SummaryChunkEvent chunkEvent =
+                    new SummaryChunkEvent(testAgent, "qwen-plus", generateOptions, msg, msg);
+            assertEquals(HookEventType.SUMMARY_CHUNK, chunkEvent.getType());
+
+            PostSummaryEvent postSummary =
+                    new PostSummaryEvent(testAgent, "qwen-plus", generateOptions, msg);
+            assertEquals(HookEventType.POST_SUMMARY, postSummary.getType());
+        }
+
+        @Test
+        @DisplayName("Timestamp should be set automatically")
+        void timestampShouldBeSetAutomatically() {
+            long before = System.currentTimeMillis();
+            PreSummaryEvent event =
+                    new PreSummaryEvent(
+                            testAgent, "qwen-plus", generateOptions, testMessages, 10, 10);
+            long after = System.currentTimeMillis();
+
+            assertTrue(event.getTimestamp() >= before);
+            assertTrue(event.getTimestamp() <= after);
+        }
+    }
+}

From 4665f8c7191f8d4eabf5ff1caa1220bcc752da01 Mon Sep 17 00:00:00 2001
From: Albumen Kevin 
Date: Fri, 16 Jan 2026 10:26:05 +0800
Subject: [PATCH 14/53] feat: support websocket transport (#557)

---
 .../model/transport/HttpTransportConfig.java  |  25 +
 .../model/transport/JdkHttpTransport.java     |  78 ++-
 .../core/model/transport/OkHttpTransport.java |  72 +-
 .../core/model/transport/ProxyConfig.java     | 439 +++++++++++++
 .../core/model/transport/ProxyType.java       |  47 ++
 .../model/transport/WebSocketTransport.java   |  95 +++
 .../model/transport/websocket/CloseInfo.java  |  68 ++
 .../websocket/JdkWebSocketConnection.java     | 280 ++++++++
 .../websocket/JdkWebSocketTransport.java      | 276 ++++++++
 .../websocket/OkHttpWebSocketConnection.java  | 197 ++++++
 .../websocket/OkHttpWebSocketTransport.java   | 333 ++++++++++
 .../websocket/WebSocketConnection.java        | 151 +++++
 .../transport/websocket/WebSocketRequest.java | 139 ++++
 .../websocket/WebSocketTransportConfig.java   | 237 +++++++
 .../WebSocketTransportException.java          | 106 +++
 .../core/model/transport/ProxyConfigTest.java | 236 +++++++
 .../transport/websocket/CloseInfoTest.java    |  75 +++
 .../websocket/JdkWebSocketConnectionTest.java | 617 ++++++++++++++++++
 .../websocket/JdkWebSocketTransportTest.java  | 474 ++++++++++++++
 .../OkHttpWebSocketConnectionTest.java        | 207 ++++++
 .../OkHttpWebSocketTransportTest.java         | 511 +++++++++++++++
 .../websocket/WebSocketRequestTest.java       |  86 +++
 .../WebSocketTransportConfigTest.java         | 289 ++++++++
 .../WebSocketTransportExceptionTest.java      | 298 +++++++++
 24 files changed, 5330 insertions(+), 6 deletions(-)
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyConfig.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyType.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/WebSocketTransport.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/CloseInfo.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnection.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransport.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnection.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransport.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketConnection.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketRequest.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfig.java
 create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportException.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/ProxyConfigTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/CloseInfoTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnectionTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransportTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnectionTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransportTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketRequestTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfigTest.java
 create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportExceptionTest.java

diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/HttpTransportConfig.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/HttpTransportConfig.java
index 647483692..c30291dc2 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/transport/HttpTransportConfig.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/HttpTransportConfig.java
@@ -40,6 +40,7 @@ public class HttpTransportConfig {
     private final int maxIdleConnections;
     private final Duration keepAliveDuration;
     private final boolean ignoreSsl;
+    private final ProxyConfig proxyConfig;
 
     private HttpTransportConfig(Builder builder) {
         this.connectTimeout = builder.connectTimeout;
@@ -48,6 +49,7 @@ private HttpTransportConfig(Builder builder) {
         this.maxIdleConnections = builder.maxIdleConnections;
         this.keepAliveDuration = builder.keepAliveDuration;
         this.ignoreSsl = builder.ignoreSsl;
+        this.proxyConfig = builder.proxyConfig;
     }
 
     /**
@@ -108,6 +110,15 @@ public boolean isIgnoreSsl() {
         return ignoreSsl;
     }
 
+    /**
+     * Get the proxy configuration.
+     *
+     * @return the proxy configuration, or null if no proxy is configured
+     */
+    public ProxyConfig getProxyConfig() {
+        return proxyConfig;
+    }
+
     /**
      * Create a new builder for HttpTransportConfig.
      *
@@ -136,6 +147,7 @@ public static class Builder {
         private int maxIdleConnections = 5;
         private Duration keepAliveDuration = Duration.ofMinutes(5);
         private boolean ignoreSsl = false;
+        private ProxyConfig proxyConfig = null;
 
         /**
          * Set the connect timeout.
@@ -207,6 +219,19 @@ public Builder ignoreSsl(boolean ignoreSsl) {
             return this;
         }
 
+        /**
+         * Set the proxy configuration.
+         *
+         * 
Supports HTTP and SOCKS proxies. See {@link ProxyConfig} for details.
+         *
+         * @param proxyConfig the proxy configuration
+         * @return this builder
+         */
+        public Builder proxy(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            return this;
+        }
+
         /**
          * Build the HttpTransportConfig.
          *
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
index f65ef1638..e00b8d15d 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
@@ -19,6 +19,11 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.InputStreamReader;
+import java.net.InetSocketAddress;
+import java.net.PasswordAuthentication;
+import java.net.Proxy;
+import java.net.ProxySelector;
+import java.net.SocketAddress;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpClient.Redirect;
@@ -29,6 +34,8 @@
 import java.security.NoSuchAlgorithmException;
 import java.security.SecureRandom;
 import java.security.cert.X509Certificate;
+import java.util.Collections;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
@@ -114,14 +121,50 @@ private static HttpClient buildClient(HttpTransportConfig config) {
                 sslContext.init(
                         null, new TrustManager[] {new TrustAllManager()}, new SecureRandom());
                 builder.sslContext(sslContext);
-                log.warn(
-                        "SSL certificate verification is disabled. "
-                                + "This should only be used for testing.");
+                log.error(
+                        "SSL certificate verification has been disabled for this WebSocket client."
+                            + " This configuration must only be used for local development or"
+                            + " testing with self-signed certificates. Do not disable SSL"
+                            + " verification in production environments, as it exposes connections"
+                            + " to man-in-the-middle attacks.");
             } catch (NoSuchAlgorithmException | KeyManagementException e) {
                 throw new HttpTransportException("Failed to create insecure SSL context", e);
             }
         }
 
+        // Configure proxy
+        if (config.getProxyConfig() != null) {
+            ProxyConfig proxyConfig = config.getProxyConfig();
+
+            if (proxyConfig.getNonProxyHosts() != null
+                    && !proxyConfig.getNonProxyHosts().isEmpty()) {
+                builder.proxy(new NonProxyHostsSelector(proxyConfig));
+            } else {
+                builder.proxy(
+                        ProxySelector.of(
+                                new InetSocketAddress(
+                                        proxyConfig.getHost(), proxyConfig.getPort())));
+            }
+
+            // Note: JDK HttpClient does not support SOCKS5 authentication directly.
+            // For HTTP proxy authentication, use Authenticator.
+            if (proxyConfig.hasAuthentication() && proxyConfig.getType() == ProxyType.HTTP) {
+                final String username = proxyConfig.getUsername();
+                final String password = proxyConfig.getPassword();
+                builder.authenticator(
+                        new java.net.Authenticator() {
+                            @Override
+                            protected PasswordAuthentication getPasswordAuthentication() {
+                                if (getRequestorType() == RequestorType.PROXY) {
+                                    return new PasswordAuthentication(
+                                            username, password.toCharArray());
+                                }
+                                return null;
+                            }
+                        });
+            }
+        }
+
         return builder.build();
     }
 
@@ -424,4 +467,33 @@ public X509Certificate[] getAcceptedIssuers() {
             return new X509Certificate[0];
         }
     }
+
+    /**
+     * ProxySelector that respects non-proxy hosts configuration.
+     */
+    private static class NonProxyHostsSelector extends ProxySelector {
+        private final ProxyConfig proxyConfig;
+        private final List proxyList;
+
+        NonProxyHostsSelector(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            this.proxyList = Collections.singletonList(proxyConfig.toJavaProxy());
+        }
+
+        @Override
+        public List select(URI uri) {
+            if (uri == null || uri.getHost() == null) {
+                return proxyList;
+            }
+            if (proxyConfig.shouldBypass(uri.getHost())) {
+                return Collections.singletonList(Proxy.NO_PROXY);
+            }
+            return proxyList;
+        }
+
+        @Override
+        public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
+            log.warn("Proxy connection failed: uri={}, address={}", uri, sa, ioe);
+        }
+    }
 }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/OkHttpTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/OkHttpTransport.java
index 5e7afa5c8..2d3093116 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/transport/OkHttpTransport.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/OkHttpTransport.java
@@ -18,17 +18,24 @@
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStreamReader;
+import java.net.Proxy;
+import java.net.ProxySelector;
+import java.net.SocketAddress;
+import java.net.URI;
 import java.nio.charset.StandardCharsets;
 import java.security.KeyManagementException;
 import java.security.NoSuchAlgorithmException;
 import java.security.SecureRandom;
 import java.security.cert.X509Certificate;
+import java.util.Collections;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.TrustManager;
 import javax.net.ssl.X509TrustManager;
 import okhttp3.ConnectionPool;
+import okhttp3.Credentials;
 import okhttp3.MediaType;
 import okhttp3.OkHttpClient;
 import okhttp3.Request;
@@ -108,15 +115,45 @@ private OkHttpClient buildClient(HttpTransportConfig config) {
 
         // Configure SSL (optionally ignore certificate verification)
         if (config.isIgnoreSsl()) {
-            log.warn(
-                    "SSL certificate verification is disabled. This is not recommended for"
-                            + " production.");
+            log.error(
+                    "SSL certificate verification has been disabled for this WebSocket client. This"
+                        + " configuration must only be used for local development or testing with"
+                        + " self-signed certificates. Do not disable SSL verification in production"
+                        + " environments, as it exposes connections to man-in-the-middle attacks.");
             builder =
                     builder.sslSocketFactory(
                                     createTrustAllSslSocketFactory(), createTrustAllTrustManager())
                             .hostnameVerifier((hostname, session) -> true);
         }
 
+        // Configure proxy
+        if (config.getProxyConfig() != null) {
+            ProxyConfig proxyConfig = config.getProxyConfig();
+
+            if (proxyConfig.getNonProxyHosts() != null
+                    && !proxyConfig.getNonProxyHosts().isEmpty()) {
+                builder.proxySelector(new NonProxyHostsSelector(proxyConfig));
+            } else {
+                builder.proxy(proxyConfig.toJavaProxy());
+            }
+
+            if (proxyConfig.hasAuthentication()) {
+                final String username = proxyConfig.getUsername();
+                final String password = proxyConfig.getPassword();
+                builder.proxyAuthenticator(
+                        (route, response) -> {
+                            if (response.request().header("Proxy-Authorization") != null) {
+                                return null; // Avoid infinite retry
+                            }
+                            String credential = Credentials.basic(username, password);
+                            return response.request()
+                                    .newBuilder()
+                                    .header("Proxy-Authorization", credential)
+                                    .build();
+                        });
+            }
+        }
+
         return builder.build();
     }
 
@@ -425,4 +462,33 @@ public OkHttpTransport build() {
             return new OkHttpTransport(config);
         }
     }
+
+    /**
+     * ProxySelector that respects non-proxy hosts configuration.
+     */
+    private static class NonProxyHostsSelector extends ProxySelector {
+        private final ProxyConfig proxyConfig;
+        private final List proxyList;
+
+        NonProxyHostsSelector(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            this.proxyList = Collections.singletonList(proxyConfig.toJavaProxy());
+        }
+
+        @Override
+        public List select(URI uri) {
+            if (uri == null || uri.getHost() == null) {
+                return proxyList;
+            }
+            if (proxyConfig.shouldBypass(uri.getHost())) {
+                return Collections.singletonList(Proxy.NO_PROXY);
+            }
+            return proxyList;
+        }
+
+        @Override
+        public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
+            log.warn("Proxy connection failed: uri={}, address={}", uri, sa, ioe);
+        }
+    }
 }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyConfig.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyConfig.java
new file mode 100644
index 000000000..e41d04809
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyConfig.java
@@ -0,0 +1,439 @@
+/*
+ * 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.model.transport;
+
+import java.net.InetSocketAddress;
+import java.net.Proxy;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Configuration for HTTP and SOCKS proxy.
+ *
+ * 
This class provides a unified configuration for both HTTP and SOCKS proxies,
+ * supporting optional authentication and bypass rules.
+ *
+ * 
Usage examples:
+ *
+ * 
{@code
+ * // Simple HTTP proxy
+ * ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080);
+ *
+ * // HTTP proxy with authentication
+ * ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080, "user", "pass");
+ *
+ * // SOCKS5 proxy with authentication
+ * ProxyConfig proxy = ProxyConfig.socks5("socks.example.com", 1080, "user", "pass");
+ *
+ * // Using builder for advanced configuration
+ * ProxyConfig proxy = ProxyConfig.builder()
+ *     .type(ProxyType.HTTP)
+ *     .host("proxy.example.com")
+ *     .port(8080)
+ *     .username("user")
+ *     .password("pass")
+ *     .nonProxyHosts(Set.of("localhost", "*.internal.com"))
+ *     .build();
+ * }

+ */
+public class ProxyConfig {
+
+    private final ProxyType type;
+    private final String host;
+    private final int port;
+    private final String username;
+    private final String password;
+    private final Set nonProxyHosts;
+
+    private ProxyConfig(Builder builder) {
+        this.type = builder.type;
+        this.host = builder.host;
+        this.port = builder.port;
+        this.username = builder.username;
+        this.password = builder.password;
+        this.nonProxyHosts =
+                builder.nonProxyHosts != null
+                        ? Collections.unmodifiableSet(new HashSet<>(builder.nonProxyHosts))
+                        : null;
+    }
+
+    /**
+     * Create a simple HTTP proxy configuration without authentication.
+     *
+     * @param host proxy server hostname or IP address
+     * @param port proxy server port
+     * @return a new ProxyConfig instance
+     */
+    public static ProxyConfig http(String host, int port) {
+        return builder().type(ProxyType.HTTP).host(host).port(port).build();
+    }
+
+    /**
+     * Create an HTTP proxy configuration with authentication.
+     *
+     * @param host proxy server hostname or IP address
+     * @param port proxy server port
+     * @param username authentication username
+     * @param password authentication password
+     * @return a new ProxyConfig instance
+     */
+    public static ProxyConfig http(String host, int port, String username, String password) {
+        return builder()
+                .type(ProxyType.HTTP)
+                .host(host)
+                .port(port)
+                .username(username)
+                .password(password)
+                .build();
+    }
+
+    /**
+     * Create a simple SOCKS4 proxy configuration.
+     *
+     * 
Note: SOCKS4 does not support authentication.
+     *
+     * @param host proxy server hostname or IP address
+     * @param port proxy server port
+     * @return a new ProxyConfig instance
+     */
+    public static ProxyConfig socks4(String host, int port) {
+        return builder().type(ProxyType.SOCKS4).host(host).port(port).build();
+    }
+
+    /**
+     * Create a simple SOCKS5 proxy configuration without authentication.
+     *
+     * @param host proxy server hostname or IP address
+     * @param port proxy server port
+     * @return a new ProxyConfig instance
+     */
+    public static ProxyConfig socks5(String host, int port) {
+        return builder().type(ProxyType.SOCKS5).host(host).port(port).build();
+    }
+
+    /**
+     * Create a SOCKS5 proxy configuration with authentication.
+     *
+     * 
Note: SOCKS5 authentication is only supported when using OkHttp-based
+     * transport implementations. JDK HttpClient does not support SOCKS5 authentication.
+     *
+     * @param host proxy server hostname or IP address
+     * @param port proxy server port
+     * @param username authentication username
+     * @param password authentication password
+     * @return a new ProxyConfig instance
+     */
+    public static ProxyConfig socks5(String host, int port, String username, String password) {
+        return builder()
+                .type(ProxyType.SOCKS5)
+                .host(host)
+                .port(port)
+                .username(username)
+                .password(password)
+                .build();
+    }
+
+    /**
+     * Create a new builder for ProxyConfig.
+     *
+     * @return a new Builder instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Get the proxy type.
+     *
+     * @return the proxy type
+     */
+    public ProxyType getType() {
+        return type;
+    }
+
+    /**
+     * Get the proxy server hostname or IP address.
+     *
+     * @return the proxy host
+     */
+    public String getHost() {
+        return host;
+    }
+
+    /**
+     * Get the proxy server port.
+     *
+     * @return the proxy port
+     */
+    public int getPort() {
+        return port;
+    }
+
+    /**
+     * Get the authentication username.
+     *
+     * @return the username, or null if no authentication is configured
+     */
+    public String getUsername() {
+        return username;
+    }
+
+    /**
+     * Get the authentication password.
+     *
+     * @return the password, or null if no authentication is configured
+     */
+    public String getPassword() {
+        return password;
+    }
+
+    /**
+     * Get the set of hosts that should bypass the proxy.
+     *
+     * 
The set may contain exact hostnames (e.g., "localhost") or wildcard patterns
+     * (e.g., "*.internal.com", "192.168.*").
+     *
+     * @return the set of non-proxy hosts, or null if not configured
+     */
+    public Set getNonProxyHosts() {
+        return nonProxyHosts;
+    }
+
+    /**
+     * Check if authentication credentials are configured.
+     *
+     * @return true if both username and password are set
+     */
+    public boolean hasAuthentication() {
+        return username != null && !username.isEmpty() && password != null && !password.isEmpty();
+    }
+
+    /**
+     * Check if the given hostname should bypass the proxy.
+     *
+     * @param hostname the hostname to check
+     * @return true if the hostname should bypass the proxy
+     */
+    public boolean shouldBypass(String hostname) {
+        if (nonProxyHosts == null || nonProxyHosts.isEmpty() || hostname == null) {
+            return false;
+        }
+
+        for (String pattern : nonProxyHosts) {
+            if (matchesPattern(hostname, pattern)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Convert this configuration to a {@link java.net.Proxy} instance.
+     *
+     * @return the Java Proxy instance
+     */
+    public Proxy toJavaProxy() {
+        Proxy.Type proxyType;
+        switch (type) {
+            case HTTP:
+                proxyType = Proxy.Type.HTTP;
+                break;
+            case SOCKS4:
+            case SOCKS5:
+                proxyType = Proxy.Type.SOCKS;
+                break;
+            default:
+                throw new IllegalStateException("Unknown proxy type: " + type);
+        }
+        return new Proxy(proxyType, new InetSocketAddress(host, port));
+    }
+
+    /**
+     * Get the socket address for this proxy.
+     *
+     * @return the proxy socket address
+     */
+    public InetSocketAddress getSocketAddress() {
+        return new InetSocketAddress(host, port);
+    }
+
+    private boolean matchesPattern(String hostname, String pattern) {
+        if (pattern.equals(hostname)) {
+            return true;
+        }
+
+        if (pattern.startsWith("*.")) {
+            String suffix = pattern.substring(1);
+            return hostname.endsWith(suffix);
+        }
+
+        if (pattern.endsWith(".*")) {
+            String prefix = pattern.substring(0, pattern.length() - 1);
+            return hostname.startsWith(prefix);
+        }
+
+        if (pattern.contains("*")) {
+            String regex = pattern.replace(".", "\\.").replace("*", ".*");
+            return Pattern.matches(regex, hostname);
+        }
+
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("ProxyConfig{type=").append(type);
+        sb.append(", host='").append(host).append('\'');
+        sb.append(", port=").append(port);
+        if (hasAuthentication()) {
+            sb.append(", username='").append(username).append('\'');
+            sb.append(", password='****'");
+        }
+        if (nonProxyHosts != null) {
+            sb.append(", nonProxyHosts=").append(nonProxyHosts);
+        }
+        sb.append('}');
+        return sb.toString();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        ProxyConfig that = (ProxyConfig) o;
+        return port == that.port
+                && type == that.type
+                && Objects.equals(host, that.host)
+                && Objects.equals(username, that.username)
+                && Objects.equals(password, that.password)
+                && Objects.equals(nonProxyHosts, that.nonProxyHosts);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(type, host, port, username, password, nonProxyHosts);
+    }
+
+    /** Builder for ProxyConfig. */
+    public static class Builder {
+        private ProxyType type;
+        private String host;
+        private int port;
+        private String username;
+        private String password;
+        private Set nonProxyHosts;
+
+        private Builder() {}
+
+        /**
+         * Set the proxy type.
+         *
+         * @param type the proxy type
+         * @return this builder
+         */
+        public Builder type(ProxyType type) {
+            this.type = type;
+            return this;
+        }
+
+        /**
+         * Set the proxy server hostname or IP address.
+         *
+         * @param host the proxy host
+         * @return this builder
+         */
+        public Builder host(String host) {
+            this.host = host;
+            return this;
+        }
+
+        /**
+         * Set the proxy server port.
+         *
+         * @param port the proxy port
+         * @return this builder
+         */
+        public Builder port(int port) {
+            this.port = port;
+            return this;
+        }
+
+        /**
+         * Set the authentication username.
+         *
+         * @param username the username
+         * @return this builder
+         */
+        public Builder username(String username) {
+            this.username = username;
+            return this;
+        }
+
+        /**
+         * Set the authentication password.
+         *
+         * @param password the password
+         * @return this builder
+         */
+        public Builder password(String password) {
+            this.password = password;
+            return this;
+        }
+
+        /**
+         * Set the hosts that should bypass the proxy.
+         *
+         * 
Supports exact hostnames and wildcard patterns:
+         *
+         * 
    
+         *   
  • {@code localhost} - exact match
+         *   
  • {@code *.internal.com} - suffix match
+         *   
  • {@code 192.168.*} - prefix match
+         * 

+         *
+         * @param nonProxyHosts the set of non-proxy hosts
+         * @return this builder
+         */
+        public Builder nonProxyHosts(Set nonProxyHosts) {
+            this.nonProxyHosts = nonProxyHosts;
+            return this;
+        }
+
+        /**
+         * Build the ProxyConfig.
+         *
+         * @return a new ProxyConfig instance
+         * @throws NullPointerException if type or host is null
+         * @throws IllegalArgumentException if port is out of range
+         */
+        public ProxyConfig build() {
+            Objects.requireNonNull(type, "type is required");
+            Objects.requireNonNull(host, "host is required");
+            if (port <= 0 || port > 65535) {
+                throw new IllegalArgumentException("port must be between 1 and 65535");
+            }
+            return new ProxyConfig(this);
+        }
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyType.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyType.java
new file mode 100644
index 000000000..a1e049a82
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/ProxyType.java
@@ -0,0 +1,47 @@
+/*
+ * 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.model.transport;
+
+/**
+ * Enumeration of supported proxy types.
+ *
+ * 
This enum defines the types of proxies that can be configured for HTTP and WebSocket
+ * transport layers.
+ */
+public enum ProxyType {
+
+    /**
+     * HTTP/HTTPS proxy.
+     *
+     * 
Supports authentication via username/password.
+     */
+    HTTP,
+
+    /**
+     * SOCKS version 4 proxy.
+     *
+     * 
Does not support authentication.
+     */
+    SOCKS4,
+
+    /**
+     * SOCKS version 5 proxy.
+     *
+     * 
Supports authentication via username/password, but only when using OkHttp-based
+     * transport implementations. JDK HttpClient does not support SOCKS5 authentication.
+     */
+    SOCKS5
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/WebSocketTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/WebSocketTransport.java
new file mode 100644
index 000000000..17494ef29
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/WebSocketTransport.java
@@ -0,0 +1,95 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport;
+
+import io.agentscope.core.model.transport.websocket.WebSocketConnection;
+import io.agentscope.core.model.transport.websocket.WebSocketRequest;
+import reactor.core.publisher.Mono;
+
+/**
+ * WebSocket client interface.
+ *
+ * 
Similar to HTTPClient design:
+ *
+ * 
    
+ *   
  • Client instance is stateless and reusable
+ *   
  • Each connect() creates a new connection
+ *   
  • Connection configuration is passed via WebSocketRequest
+ *   
  • Supports generic type parameter for message format (String or byte[])
+ * 

+ *
+ * 
Implementations:
+ *
+ * 
    
+ *   
  • {@code JdkWebSocketTransport} - Based on JDK 11+ HttpClient
+ *   
  • {@code OkHttpWebSocketTransport} - Based on OkHttp
+ * 

+ *
+ * 
Usage example (text protocol):
+ *
+ * 
{@code
+ * // Create client (reusable)
+ * WebSocketTransport client = JdkWebSocketTransport.create();
+ *
+ * // Create connection request
+ * WebSocketRequest request = WebSocketRequest.builder("wss://api.openai.com/v1/realtime")
+ *     .header("Authorization", "Bearer " + apiKey)
+ *     .build();
+ *
+ * // Establish connection (specify String type)
+ * client.connect(request, String.class)
+ *     .flatMapMany(connection -> {
+ *         // Send JSON configuration
+ *         connection.send(sessionConfig).subscribe();
+ *         // Receive JSON messages
+ *         return connection.receive();
+ *     })
+ *     .subscribe(json -> handleMessage(json));
+ * }

+ *
+ * 
Usage example (binary protocol):
+ *
+ * 
{@code
+ * // Establish connection (specify byte[] type)
+ * client.connect(request, byte[].class)
+ *     .flatMapMany(connection -> {
+ *         // Send binary data
+ *         connection.send(binaryFrame).subscribe();
+ *         // Receive binary data
+ *         return connection.receive();
+ *     })
+ *     .subscribe(data -> handleBinaryMessage(data));
+ * }

+ */
+public interface WebSocketTransport {
+
+    /**
+     * Establish a WebSocket connection.
+     *
+     * @param  Message type: String for text protocol, byte[] for binary protocol
+     * @param request Connection request configuration
+     * @param messageType Class object for message type (String.class or byte[].class)
+     * @return Mono that emits WebSocketConnection on successful connection
+     */
+     Mono> connect(WebSocketRequest request, Class messageType);
+
+    /**
+     * Shutdown the client and release resources.
+     *
+     * 
After shutdown, this client should not be used anymore.
+     */
+    void shutdown();
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/CloseInfo.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/CloseInfo.java
new file mode 100644
index 000000000..9f7ef0681
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/CloseInfo.java
@@ -0,0 +1,68 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+/**
+ * WebSocket connection close information.
+ *
+ * 
Contains the close code and reason when a WebSocket connection is closed.
+ *
+ * @param code WebSocket close code
+ * @param reason Close reason message
+ */
+public record CloseInfo(int code, String reason) {
+
+    /** Normal closure (1000). */
+    public static final int NORMAL_CLOSURE = 1000;
+
+    /** Going away (1001). */
+    public static final int GOING_AWAY = 1001;
+
+    /** Protocol error (1002). */
+    public static final int PROTOCOL_ERROR = 1002;
+
+    /** Abnormal closure (1006). */
+    public static final int ABNORMAL_CLOSURE = 1006;
+
+    /**
+     * Check if this is a normal closure.
+     *
+     * @return true if the close code is 1000 (normal closure)
+     */
+    public boolean isNormal() {
+        return code == NORMAL_CLOSURE;
+    }
+
+    /**
+     * Create a CloseInfo for normal closure.
+     *
+     * @param reason Close reason
+     * @return CloseInfo instance
+     */
+    public static CloseInfo normal(String reason) {
+        return new CloseInfo(NORMAL_CLOSURE, reason);
+    }
+
+    /**
+     * Create a CloseInfo for abnormal closure.
+     *
+     * @param reason Close reason
+     * @return CloseInfo instance
+     */
+    public static CloseInfo abnormal(String reason) {
+        return new CloseInfo(ABNORMAL_CLOSURE, reason);
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnection.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnection.java
new file mode 100644
index 000000000..ba0f964f1
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnection.java
@@ -0,0 +1,280 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import java.net.http.WebSocket;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.locks.ReentrantLock;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.core.publisher.Sinks;
+
+/**
+ * WebSocket connection implementation based on JDK WebSocket.
+ *
+ * 
Supports both text (String) and binary (byte[]) message types through generic type parameter.
+ *
+ * @param  Message type: String for text protocol, byte[] for binary protocol
+ */
+public class JdkWebSocketConnection implements WebSocketConnection {
+
+    private static final Logger log = LoggerFactory.getLogger(JdkWebSocketConnection.class);
+
+    private final String url;
+    private final Class messageType;
+    private volatile WebSocket webSocket;
+    private final AtomicBoolean closed = new AtomicBoolean(false);
+    private volatile CloseInfo closeInfo;
+
+    // Message receive sink (unicast - single subscriber only)
+    private final Sinks.Many messageSink = Sinks.many().unicast().onBackpressureBuffer();
+
+    // Buffer for accumulating fragmented messages
+    private final StringBuilder textBuffer = new StringBuilder();
+    private ByteBuffer binaryBuffer;
+
+    // Send lock (JDK WebSocket is not thread-safe for sending)
+    private final ReentrantLock sendLock = new ReentrantLock();
+
+    // JDK WebSocket.Listener implementation
+    private final WebSocket.Listener listener =
+            new WebSocket.Listener() {
+                @Override
+                public void onOpen(WebSocket webSocket) {
+                    log.debug("WebSocket opened: {}", url);
+                    webSocket.request(1);
+                }
+
+                @Override
+                public CompletionStage onText(
+                        WebSocket webSocket, CharSequence data, boolean last) {
+                    textBuffer.append(data);
+                    if (last) {
+                        String message = textBuffer.toString();
+                        textBuffer.setLength(0);
+                        log.trace("Received text message, size: {} bytes", message.length());
+                        emitMessage(message);
+                    }
+                    webSocket.request(1);
+                    return CompletableFuture.completedFuture(null);
+                }
+
+                @Override
+                public CompletionStage onBinary(
+                        WebSocket webSocket, ByteBuffer data, boolean last) {
+                    if (binaryBuffer == null) {
+                        binaryBuffer = ByteBuffer.allocate(data.remaining());
+                    }
+                    // Expand buffer if needed
+                    if (binaryBuffer.remaining() < data.remaining()) {
+                        ByteBuffer newBuffer =
+                                ByteBuffer.allocate(binaryBuffer.position() + data.remaining());
+                        binaryBuffer.flip();
+                        newBuffer.put(binaryBuffer);
+                        binaryBuffer = newBuffer;
+                    }
+                    binaryBuffer.put(data);
+
+                    if (last) {
+                        binaryBuffer.flip();
+                        byte[] bytes = new byte[binaryBuffer.remaining()];
+                        binaryBuffer.get(bytes);
+                        binaryBuffer = null;
+                        emitMessage(bytes);
+                    }
+                    webSocket.request(1);
+                    return CompletableFuture.completedFuture(null);
+                }
+
+                @Override
+                public CompletionStage onClose(
+                        WebSocket webSocket, int statusCode, String reason) {
+                    log.info("WebSocket closed: {} [code={}, reason={}]", url, statusCode, reason);
+                    closed.set(true);
+                    closeInfo = new CloseInfo(statusCode, reason);
+                    messageSink.tryEmitComplete();
+                    return CompletableFuture.completedFuture(null);
+                }
+
+                @Override
+                public void onError(WebSocket webSocket, Throwable error) {
+                    log.error("WebSocket error: {}", url, error);
+                    closed.set(true);
+                    closeInfo = new CloseInfo(CloseInfo.ABNORMAL_CLOSURE, error.getMessage());
+                    messageSink.tryEmitError(
+                            new WebSocketTransportException(
+                                    "WebSocket error", error, url, "ERROR"));
+                }
+            };
+
+    /**
+     * Create a new JdkWebSocketConnection.
+     *
+     * @param url WebSocket URL
+     * @param messageType Message type class (String.class or byte[].class)
+     */
+    JdkWebSocketConnection(String url, Class messageType) {
+        this.url = url;
+        this.messageType = messageType;
+    }
+
+    /**
+     * Get the JDK WebSocket.Listener (internal use).
+     *
+     * @return WebSocket.Listener instance
+     */
+    WebSocket.Listener getListener() {
+        return listener;
+    }
+
+    /**
+     * Set the WebSocket instance (internal use).
+     *
+     * @param webSocket WebSocket instance
+     */
+    void setWebSocket(WebSocket webSocket) {
+        this.webSocket = webSocket;
+    }
+
+    @SuppressWarnings("unchecked")
+    private void emitMessage(String message) {
+        if (messageType == String.class) {
+            messageSink.tryEmitNext((T) message);
+        } else if (messageType == byte[].class) {
+            messageSink.tryEmitNext((T) message.getBytes(StandardCharsets.UTF_8));
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private void emitMessage(byte[] data) {
+        if (messageType == byte[].class) {
+            messageSink.tryEmitNext((T) data);
+        } else if (messageType == String.class) {
+            messageSink.tryEmitNext((T) new String(data, StandardCharsets.UTF_8));
+        }
+    }
+
+    @Override
+    public Mono send(T data) {
+        return Mono.create(
+                        sink -> {
+                            if (webSocket == null || closed.get()) {
+                                sink.error(
+                                        new WebSocketTransportException(
+                                                "Connection is not open",
+                                                null,
+                                                url,
+                                                closed.get() ? "CLOSED" : "NOT_CONNECTED"));
+                                return;
+                            }
+
+                            sendLock.lock();
+                            try {
+                                CompletableFuture future;
+                                if (data instanceof String text) {
+                                    future = webSocket.sendText(text, true);
+                                } else if (data instanceof byte[] bytes) {
+                                    future = webSocket.sendBinary(ByteBuffer.wrap(bytes), true);
+                                } else {
+                                    sink.error(
+                                            new IllegalArgumentException(
+                                                    "Unsupported message type: "
+                                                            + data.getClass().getName()));
+                                    return;
+                                }
+
+                                future.whenComplete(
+                                        (ws, error) -> {
+                                            if (error != null) {
+                                                log.error("Failed to send message: {}", url, error);
+                                                sink.error(
+                                                        new WebSocketTransportException(
+                                                                "Failed to send message",
+                                                                error,
+                                                                url,
+                                                                "OPEN"));
+                                            } else {
+                                                sink.success();
+                                            }
+                                        });
+                            } finally {
+                                sendLock.unlock();
+                            }
+                        })
+                .onErrorMap(
+                        e ->
+                                e instanceof WebSocketTransportException
+                                        ? e
+                                        : new WebSocketTransportException(
+                                                "Send failed", e, url, "OPEN"));
+    }
+
+    @Override
+    public Flux receive() {
+        return messageSink
+                .asFlux()
+                .onErrorMap(
+                        e ->
+                                e instanceof WebSocketTransportException
+                                        ? e
+                                        : new WebSocketTransportException(
+                                                "Receive failed", e, url, "OPEN"));
+    }
+
+    @Override
+    public Mono close() {
+        return Mono.create(
+                sink -> {
+                    if (webSocket != null && !closed.getAndSet(true)) {
+                        log.info("Closing WebSocket connection: {}", url);
+                        webSocket
+                                .sendClose(CloseInfo.NORMAL_CLOSURE, "")
+                                .whenComplete(
+                                        (ws, error) -> {
+                                            closeInfo = new CloseInfo(CloseInfo.NORMAL_CLOSURE, "");
+                                            if (error != null) {
+                                                log.warn(
+                                                        "Error during WebSocket close: {}",
+                                                        url,
+                                                        error);
+                                                sink.error(error);
+                                            } else {
+                                                log.info("WebSocket closed: {}", url);
+                                                sink.success();
+                                            }
+                                        });
+                    } else {
+                        sink.success();
+                    }
+                });
+    }
+
+    @Override
+    public boolean isOpen() {
+        return webSocket != null && !closed.get();
+    }
+
+    @Override
+    public CloseInfo getCloseInfo() {
+        return closeInfo;
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransport.java
new file mode 100644
index 000000000..75aad4013
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransport.java
@@ -0,0 +1,276 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import io.agentscope.core.model.transport.ProxyConfig;
+import io.agentscope.core.model.transport.ProxyType;
+import io.agentscope.core.model.transport.WebSocketTransport;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.net.PasswordAuthentication;
+import java.net.Proxy;
+import java.net.ProxySelector;
+import java.net.SocketAddress;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.WebSocket;
+import java.security.KeyManagementException;
+import java.security.NoSuchAlgorithmException;
+import java.security.SecureRandom;
+import java.security.cert.X509Certificate;
+import java.time.Duration;
+import java.util.Collections;
+import java.util.List;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.X509TrustManager;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+/**
+ * WebSocket client implementation based on JDK 11+ HttpClient.
+ *
+ * 
Features:
+ *
+ * 
    
+ *   
  • No additional dependencies, uses JDK built-in API
+ *   
  • Client instance is reusable
+ *   
  • Thread-safe
+ * 

+ *
+ * 
Usage example:
+ *
+ * 
{@code
+ * WebSocketTransport client = JdkWebSocketTransport.create();
+ *
+ * WebSocketRequest request = WebSocketRequest.builder("wss://api.example.com/ws")
+ *     .header("Authorization", "Bearer token")
+ *     .build();
+ *
+ * client.connect(request, String.class)
+ *     .flatMapMany(conn -> {
+ *         conn.send("{\"type\":\"config\"}").subscribe();
+ *         return conn.receive();
+ *     })
+ *     .subscribe(data -> handle(data));
+ * }

+ */
+public class JdkWebSocketTransport implements WebSocketTransport {
+
+    private static final Logger log = LoggerFactory.getLogger(JdkWebSocketTransport.class);
+
+    private final HttpClient httpClient;
+
+    private JdkWebSocketTransport(HttpClient httpClient) {
+        this.httpClient = httpClient;
+    }
+
+    /**
+     * Create a client with default configuration.
+     *
+     * @return JdkWebSocketTransport instance
+     */
+    public static JdkWebSocketTransport create() {
+        return new JdkWebSocketTransport(
+                HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build());
+    }
+
+    /**
+     * Create a client with custom HttpClient.
+     *
+     * @param httpClient Custom HttpClient instance
+     * @return JdkWebSocketTransport instance
+     */
+    public static JdkWebSocketTransport create(HttpClient httpClient) {
+        return new JdkWebSocketTransport(httpClient);
+    }
+
+    /**
+     * Create a client with custom configuration.
+     *
+     * 
This method supports proxy configuration and other advanced settings.
+     *
+     * @param config the WebSocket client configuration
+     * @return JdkWebSocketTransport instance
+     */
+    public static JdkWebSocketTransport create(WebSocketTransportConfig config) {
+        return new JdkWebSocketTransport(buildClient(config));
+    }
+
+    private static HttpClient buildClient(WebSocketTransportConfig config) {
+        HttpClient.Builder builder =
+                HttpClient.newBuilder()
+                        .version(HttpClient.Version.HTTP_2)
+                        .connectTimeout(config.getConnectTimeout());
+
+        // Configure SSL (optionally ignore certificate verification)
+        if (config.isIgnoreSsl()) {
+            log.error(
+                    "SSL certificate verification has been disabled for this WebSocket client. This"
+                        + " configuration must only be used for local development or testing with"
+                        + " self-signed certificates. Do not disable SSL verification in production"
+                        + " environments, as it exposes connections to man-in-the-middle attacks.");
+            try {
+                SSLContext sslContext = SSLContext.getInstance("TLS");
+                sslContext.init(
+                        null,
+                        new TrustManager[] {createTrustAllTrustManager()},
+                        new SecureRandom());
+                builder.sslContext(sslContext);
+            } catch (NoSuchAlgorithmException | KeyManagementException e) {
+                throw new RuntimeException("Failed to create trust-all SSL context", e);
+            }
+        }
+
+        // Configure proxy
+        if (config.getProxyConfig() != null) {
+            ProxyConfig proxyConfig = config.getProxyConfig();
+
+            if (proxyConfig.getNonProxyHosts() != null
+                    && !proxyConfig.getNonProxyHosts().isEmpty()) {
+                builder.proxy(new NonProxyHostsSelector(proxyConfig));
+            } else {
+                builder.proxy(
+                        ProxySelector.of(
+                                new InetSocketAddress(
+                                        proxyConfig.getHost(), proxyConfig.getPort())));
+            }
+
+            // Note: JDK HttpClient does not support SOCKS5 authentication directly.
+            // For HTTP proxy authentication, use Authenticator.
+            if (proxyConfig.hasAuthentication() && proxyConfig.getType() == ProxyType.HTTP) {
+                final String username = proxyConfig.getUsername();
+                final String password = proxyConfig.getPassword();
+                builder.authenticator(
+                        new java.net.Authenticator() {
+                            @Override
+                            protected PasswordAuthentication getPasswordAuthentication() {
+                                if (getRequestorType() == RequestorType.PROXY) {
+                                    return new PasswordAuthentication(
+                                            username, password.toCharArray());
+                                }
+                                return null;
+                            }
+                        });
+            }
+        }
+
+        return builder.build();
+    }
+
+    private static X509TrustManager createTrustAllTrustManager() {
+        return new X509TrustManager() {
+            @Override
+            public void checkClientTrusted(X509Certificate[] chain, String authType) {
+                // Trust all certificates
+            }
+
+            @Override
+            public void checkServerTrusted(X509Certificate[] chain, String authType) {
+                // Trust all certificates
+            }
+
+            @Override
+            public X509Certificate[] getAcceptedIssuers() {
+                return new X509Certificate[0];
+            }
+        };
+    }
+
+    @Override
+    public  Mono> connect(
+            WebSocketRequest request, Class messageType) {
+        return Mono.create(
+                sink -> {
+                    log.info("Connecting to WebSocket: {}", request.getUrl());
+
+                    WebSocket.Builder builder = httpClient.newWebSocketBuilder();
+
+                    // Set connection timeout
+                    if (request.getConnectTimeout() != null) {
+                        builder.connectTimeout(request.getConnectTimeout());
+                    }
+
+                    // Add request headers
+                    request.getHeaders().forEach(builder::header);
+
+                    // Create connection handler
+                    JdkWebSocketConnection connection =
+                            new JdkWebSocketConnection<>(request.getUrl(), messageType);
+
+                    builder.buildAsync(URI.create(request.getUrl()), connection.getListener())
+                            .whenComplete(
+                                    (webSocket, error) -> {
+                                        if (error != null) {
+                                            log.error(
+                                                    "Failed to connect to WebSocket: {}",
+                                                    request.getUrl(),
+                                                    error);
+                                            sink.error(
+                                                    new WebSocketTransportException(
+                                                            "Failed to connect",
+                                                            error,
+                                                            request.getUrl(),
+                                                            "CONNECTING",
+                                                            request.getHeaders()));
+                                        } else {
+                                            log.info(
+                                                    "WebSocket connected successfully: {}",
+                                                    request.getUrl());
+                                            connection.setWebSocket(webSocket);
+                                            sink.success(connection);
+                                        }
+                                    });
+                });
+    }
+
+    @Override
+    public void shutdown() {
+        // JDK HttpClient does not require explicit shutdown
+        // If a custom ExecutorService is used, it may need to be closed
+        log.debug("JdkWebSocketTransport shutdown called");
+    }
+
+    /**
+     * ProxySelector that respects non-proxy hosts configuration.
+     */
+    private static class NonProxyHostsSelector extends ProxySelector {
+        private final ProxyConfig proxyConfig;
+        private final List proxyList;
+
+        NonProxyHostsSelector(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            this.proxyList = Collections.singletonList(proxyConfig.toJavaProxy());
+        }
+
+        @Override
+        public List select(URI uri) {
+            if (uri == null || uri.getHost() == null) {
+                return proxyList;
+            }
+            if (proxyConfig.shouldBypass(uri.getHost())) {
+                return Collections.singletonList(Proxy.NO_PROXY);
+            }
+            return proxyList;
+        }
+
+        @Override
+        public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
+            log.warn("Proxy connection failed: uri={}, address={}", uri, sa, ioe);
+        }
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnection.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnection.java
new file mode 100644
index 000000000..4f588dd73
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnection.java
@@ -0,0 +1,197 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.atomic.AtomicBoolean;
+import okhttp3.WebSocket;
+import okio.ByteString;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.core.publisher.Sinks;
+
+/**
+ * WebSocket connection implementation based on OkHttp WebSocket.
+ *
+ * 
Supports both text (String) and binary (byte[]) message types through generic type parameter.
+ *
+ * @param  Message type: String for text protocol, byte[] for binary protocol
+ */
+public class OkHttpWebSocketConnection implements WebSocketConnection {
+
+    private static final Logger log = LoggerFactory.getLogger(OkHttpWebSocketConnection.class);
+
+    private final String url;
+    private final Class messageType;
+    private volatile WebSocket webSocket;
+    private final AtomicBoolean closed = new AtomicBoolean(false);
+    private final AtomicBoolean initialized = new AtomicBoolean(false);
+    private volatile CloseInfo closeInfo;
+
+    // Message receive sink (unicast - single subscriber only)
+    private final Sinks.Many messageSink = Sinks.many().unicast().onBackpressureBuffer();
+
+    /**
+     * Create a new OkHttpWebSocketConnection.
+     *
+     * @param url WebSocket URL
+     * @param messageType Message type class (String.class or byte[].class)
+     */
+    OkHttpWebSocketConnection(String url, Class messageType) {
+        this.url = url;
+        this.messageType = messageType;
+    }
+
+    /**
+     * Set the WebSocket instance (internal use).
+     *
+     * @param webSocket WebSocket instance
+     */
+    void setWebSocket(WebSocket webSocket) {
+        this.webSocket = webSocket;
+        this.initialized.set(true);
+    }
+
+    /**
+     * Check if the connection is initialized (internal use).
+     *
+     * @return true if initialized
+     */
+    boolean isInitialized() {
+        return initialized.get();
+    }
+
+    /**
+     * Handle received message (internal use).
+     *
+     * @param data Message data as byte array
+     */
+    @SuppressWarnings("unchecked")
+    void onMessage(byte[] data) {
+        if (messageType == byte[].class) {
+            messageSink.tryEmitNext((T) data);
+        } else if (messageType == String.class) {
+            messageSink.tryEmitNext((T) new String(data, StandardCharsets.UTF_8));
+        }
+    }
+
+    /**
+     * Handle connection closed (internal use).
+     *
+     * @param code Close code
+     * @param reason Close reason
+     */
+    void onClosed(int code, String reason) {
+        closed.set(true);
+        closeInfo = new CloseInfo(code, reason);
+        messageSink.tryEmitComplete();
+    }
+
+    /**
+     * Handle error (internal use).
+     *
+     * @param error Error that occurred
+     */
+    void onError(Throwable error) {
+        closed.set(true);
+        closeInfo = new CloseInfo(CloseInfo.ABNORMAL_CLOSURE, error.getMessage());
+        messageSink.tryEmitError(
+                new WebSocketTransportException("WebSocket error", error, url, "ERROR"));
+    }
+
+    @Override
+    public Mono send(T data) {
+        return Mono.create(
+                        sink -> {
+                            if (webSocket == null || closed.get()) {
+                                sink.error(
+                                        new WebSocketTransportException(
+                                                "Connection is not open",
+                                                null,
+                                                url,
+                                                closed.get() ? "CLOSED" : "NOT_CONNECTED"));
+                                return;
+                            }
+
+                            boolean success;
+                            if (data instanceof String text) {
+                                log.debug("Sending text message, size: {} chars", text.length());
+                                success = webSocket.send(text);
+                            } else if (data instanceof byte[] bytes) {
+                                log.debug("Sending binary message, size: {} bytes", bytes.length);
+                                success = webSocket.send(ByteString.of(bytes));
+                            } else {
+                                sink.error(
+                                        new IllegalArgumentException(
+                                                "Unsupported message type: "
+                                                        + data.getClass().getName()));
+                                return;
+                            }
+
+                            if (!success) {
+                                log.error("Failed to send message: {}", url);
+                                sink.error(
+                                        new WebSocketTransportException(
+                                                "Failed to send message", null, url, "OPEN"));
+                            } else {
+                                sink.success();
+                            }
+                        })
+                .onErrorMap(
+                        e ->
+                                e instanceof WebSocketTransportException
+                                        ? e
+                                        : new WebSocketTransportException(
+                                                "Send failed", e, url, "OPEN"));
+    }
+
+    @Override
+    public Flux receive() {
+        return messageSink
+                .asFlux()
+                .onErrorMap(
+                        e ->
+                                e instanceof WebSocketTransportException
+                                        ? e
+                                        : new WebSocketTransportException(
+                                                "Receive failed", e, url, "OPEN"));
+    }
+
+    @Override
+    public Mono close() {
+        return Mono.create(
+                sink -> {
+                    if (webSocket != null && !closed.getAndSet(true)) {
+                        log.info("Closing WebSocket connection: {}", url);
+                        webSocket.close(CloseInfo.NORMAL_CLOSURE, "");
+                        closeInfo = new CloseInfo(CloseInfo.NORMAL_CLOSURE, "");
+                    }
+                    sink.success();
+                });
+    }
+
+    @Override
+    public boolean isOpen() {
+        return webSocket != null && !closed.get();
+    }
+
+    @Override
+    public CloseInfo getCloseInfo() {
+        return closeInfo;
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransport.java
new file mode 100644
index 000000000..b81e0ec15
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransport.java
@@ -0,0 +1,333 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import io.agentscope.core.model.transport.ProxyConfig;
+import io.agentscope.core.model.transport.WebSocketTransport;
+import java.io.IOException;
+import java.net.Proxy;
+import java.net.ProxySelector;
+import java.net.SocketAddress;
+import java.net.URI;
+import java.nio.charset.StandardCharsets;
+import java.security.KeyManagementException;
+import java.security.NoSuchAlgorithmException;
+import java.security.SecureRandom;
+import java.security.cert.X509Certificate;
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.X509TrustManager;
+import okhttp3.Credentials;
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.Response;
+import okhttp3.WebSocket;
+import okhttp3.WebSocketListener;
+import okio.ByteString;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+/**
+ * WebSocket client implementation based on OkHttp.
+ *
+ * 
Features:
+ *
+ * 
    
+ *   
  • Mature and stable HTTP client library
+ *   
  • Built-in ping/pong heartbeat (pingInterval)
+ *   
  • Better connection pool management
+ *   
  • Client instance is reusable
+ * 

+ *
+ * 
Usage example:
+ *
+ * 
{@code
+ * WebSocketTransport client = OkHttpWebSocketTransport.create();
+ *
+ * WebSocketRequest request = WebSocketRequest.builder("wss://api.example.com/ws")
+ *     .header("Authorization", "Bearer token")
+ *     .build();
+ *
+ * client.connect(request, String.class)
+ *     .flatMapMany(conn -> {
+ *         conn.send("{\"type\":\"config\"}").subscribe();
+ *         return conn.receive();
+ *     })
+ *     .subscribe(data -> handle(data));
+ * }

+ */
+public class OkHttpWebSocketTransport implements WebSocketTransport {
+
+    private static final Logger log = LoggerFactory.getLogger(OkHttpWebSocketTransport.class);
+
+    private final OkHttpClient client;
+
+    private OkHttpWebSocketTransport(OkHttpClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Create a client with default configuration.
+     *
+     * @return OkHttpWebSocketTransport instance
+     */
+    public static OkHttpWebSocketTransport create() {
+        return new OkHttpWebSocketTransport(
+                new OkHttpClient.Builder()
+                        .connectTimeout(30, TimeUnit.SECONDS)
+                        .readTimeout(0, TimeUnit.SECONDS) // No read timeout for WebSocket
+                        .writeTimeout(30, TimeUnit.SECONDS)
+                        .pingInterval(30, TimeUnit.SECONDS) // Heartbeat interval
+                        .build());
+    }
+
+    /**
+     * Create a client with custom OkHttpClient.
+     *
+     * @param client Custom OkHttpClient instance
+     * @return OkHttpWebSocketTransport instance
+     */
+    public static OkHttpWebSocketTransport create(OkHttpClient client) {
+        return new OkHttpWebSocketTransport(client);
+    }
+
+    /**
+     * Create a client with custom configuration.
+     *
+     * 
This method supports proxy configuration and other advanced settings.
+     *
+     * @param config the WebSocket client configuration
+     * @return OkHttpWebSocketTransport instance
+     */
+    public static OkHttpWebSocketTransport create(WebSocketTransportConfig config) {
+        return new OkHttpWebSocketTransport(buildClient(config));
+    }
+
+    private static OkHttpClient buildClient(WebSocketTransportConfig config) {
+        OkHttpClient.Builder builder =
+                new OkHttpClient.Builder()
+                        .connectTimeout(
+                                config.getConnectTimeout().toMillis(), TimeUnit.MILLISECONDS)
+                        .readTimeout(config.getReadTimeout().toMillis(), TimeUnit.MILLISECONDS)
+                        .writeTimeout(config.getWriteTimeout().toMillis(), TimeUnit.MILLISECONDS)
+                        .pingInterval(config.getPingInterval().toMillis(), TimeUnit.MILLISECONDS);
+
+        // Configure SSL (optionally ignore certificate verification)
+        if (config.isIgnoreSsl()) {
+            log.error(
+                    "SSL certificate verification has been disabled for this WebSocket client. This"
+                        + " configuration must only be used for local development or testing with"
+                        + " self-signed certificates. Do not disable SSL verification in production"
+                        + " environments, as it exposes connections to man-in-the-middle attacks.");
+            try {
+                SSLContext sslContext = SSLContext.getInstance("TLS");
+                X509TrustManager trustManager = createTrustAllTrustManager();
+                sslContext.init(null, new TrustManager[] {trustManager}, new SecureRandom());
+                builder.sslSocketFactory(sslContext.getSocketFactory(), trustManager)
+                        .hostnameVerifier((hostname, session) -> true);
+            } catch (NoSuchAlgorithmException | KeyManagementException e) {
+                throw new RuntimeException("Failed to create trust-all SSL socket factory", e);
+            }
+        }
+
+        // Configure proxy
+        if (config.getProxyConfig() != null) {
+            ProxyConfig proxyConfig = config.getProxyConfig();
+
+            if (proxyConfig.getNonProxyHosts() != null
+                    && !proxyConfig.getNonProxyHosts().isEmpty()) {
+                builder.proxySelector(new NonProxyHostsSelector(proxyConfig));
+            } else {
+                builder.proxy(proxyConfig.toJavaProxy());
+            }
+
+            if (proxyConfig.hasAuthentication()) {
+                final String username = proxyConfig.getUsername();
+                final String password = proxyConfig.getPassword();
+                builder.proxyAuthenticator(
+                        (route, response) -> {
+                            if (response.request().header("Proxy-Authorization") != null) {
+                                return null; // Avoid infinite retry
+                            }
+                            String credential = Credentials.basic(username, password);
+                            return response.request()
+                                    .newBuilder()
+                                    .header("Proxy-Authorization", credential)
+                                    .build();
+                        });
+            }
+        }
+
+        return builder.build();
+    }
+
+    private static X509TrustManager createTrustAllTrustManager() {
+        return new X509TrustManager() {
+            @Override
+            public void checkClientTrusted(X509Certificate[] chain, String authType) {
+                // Trust all certificates
+            }
+
+            @Override
+            public void checkServerTrusted(X509Certificate[] chain, String authType) {
+                // Trust all certificates
+            }
+
+            @Override
+            public X509Certificate[] getAcceptedIssuers() {
+                return new X509Certificate[0];
+            }
+        };
+    }
+
+    @Override
+    public  Mono> connect(
+            WebSocketRequest request, Class messageType) {
+        return Mono.create(
+                sink -> {
+                    log.info("Connecting to WebSocket: {}", request.getUrl());
+
+                    Request.Builder requestBuilder = new Request.Builder().url(request.getUrl());
+
+                    // Add request headers
+                    request.getHeaders().forEach(requestBuilder::addHeader);
+
+                    Request okRequest = requestBuilder.build();
+                    OkHttpWebSocketConnection connection =
+                            new OkHttpWebSocketConnection<>(request.getUrl(), messageType);
+
+                    WebSocket webSocket =
+                            client.newWebSocket(
+                                    okRequest,
+                                    new WebSocketListener() {
+                                        @Override
+                                        public void onOpen(WebSocket webSocket, Response response) {
+                                            log.info(
+                                                    "WebSocket connected successfully: {}",
+                                                    request.getUrl());
+                                            connection.setWebSocket(webSocket);
+                                            sink.success(connection);
+                                        }
+
+                                        @Override
+                                        public void onMessage(WebSocket webSocket, String text) {
+                                            log.trace(
+                                                    "Received text message, size: {} chars",
+                                                    text.length());
+                                            connection.onMessage(
+                                                    text.getBytes(StandardCharsets.UTF_8));
+                                        }
+
+                                        @Override
+                                        public void onMessage(
+                                                WebSocket webSocket, ByteString bytes) {
+                                            log.trace(
+                                                    "Received binary message, size: {} bytes",
+                                                    bytes.size());
+                                            connection.onMessage(bytes.toByteArray());
+                                        }
+
+                                        @Override
+                                        public void onClosing(
+                                                WebSocket webSocket, int code, String reason) {
+                                            log.debug(
+                                                    "WebSocket closing: {} [code={}, reason={}]",
+                                                    request.getUrl(),
+                                                    code,
+                                                    reason);
+                                            webSocket.close(code, reason);
+                                        }
+
+                                        @Override
+                                        public void onClosed(
+                                                WebSocket webSocket, int code, String reason) {
+                                            log.info(
+                                                    "WebSocket closed: {} [code={}, reason={}]",
+                                                    request.getUrl(),
+                                                    code,
+                                                    reason);
+                                            connection.onClosed(code, reason);
+                                        }
+
+                                        @Override
+                                        public void onFailure(
+                                                WebSocket webSocket,
+                                                Throwable t,
+                                                Response response) {
+                                            if (!connection.isInitialized()) {
+                                                // Connection establishment failed
+                                                log.error(
+                                                        "Failed to connect to WebSocket: {}",
+                                                        request.getUrl(),
+                                                        t);
+                                                sink.error(
+                                                        new WebSocketTransportException(
+                                                                "Failed to connect",
+                                                                t,
+                                                                request.getUrl(),
+                                                                "CONNECTING",
+                                                                request.getHeaders()));
+                                            } else {
+                                                // Connection interrupted
+                                                log.error(
+                                                        "WebSocket error: {}", request.getUrl(), t);
+                                                connection.onError(t);
+                                            }
+                                        }
+                                    });
+                });
+    }
+
+    @Override
+    public void shutdown() {
+        log.debug("OkHttpWebSocketTransport shutdown called");
+        client.dispatcher().executorService().shutdown();
+        client.connectionPool().evictAll();
+    }
+
+    /**
+     * ProxySelector that respects non-proxy hosts configuration.
+     */
+    private static class NonProxyHostsSelector extends ProxySelector {
+        private final ProxyConfig proxyConfig;
+        private final List proxyList;
+
+        NonProxyHostsSelector(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            this.proxyList = Collections.singletonList(proxyConfig.toJavaProxy());
+        }
+
+        @Override
+        public List select(URI uri) {
+            if (uri == null || uri.getHost() == null) {
+                return proxyList;
+            }
+            if (proxyConfig.shouldBypass(uri.getHost())) {
+                return Collections.singletonList(Proxy.NO_PROXY);
+            }
+            return proxyList;
+        }
+
+        @Override
+        public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
+            log.warn("Proxy connection failed: uri={}, address={}", uri, sa, ioe);
+        }
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketConnection.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketConnection.java
new file mode 100644
index 000000000..9aff54c13
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketConnection.java
@@ -0,0 +1,151 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+/**
+ * WebSocket connection interface.
+ *
+ * 
Represents an active WebSocket connection with send/receive capabilities. Uses generic type
+ * parameter to support different message formats:
+ *
+ * 
    
+ *   
  • {@code WebSocketConnection} - Text protocol (JSON over WebSocket)
+ *   
  • {@code WebSocketConnection} - Binary protocol
+ * 

+ *
+ * 
Error handling: All methods return Mono/Flux that propagate errors through Reactor's error
+ * channel. Errors are wrapped in {@link WebSocketTransportException} with connection context.
+ *
+ * 
Logging: Implementations should log at appropriate levels:
+ *
+ * 
    
+ *   
  • INFO: Connection established/closed
+ *   
  • DEBUG: Message send/receive operations
+ *   
  • TRACE: Detailed message content (size, preview)
+ *   
  • ERROR: Connection errors, send/receive failures
+ * 

+ *
+ * 
Usage example (text protocol):
+ *
+ * 
{@code
+ * WebSocketTransport client = JdkWebSocketTransport.create();
+ * client.connect(request, String.class)
+ *     .flatMapMany(connection -> {
+ *         // Send JSON message
+ *         connection.send("{\"type\":\"config\"}").subscribe();
+ *
+ *         // Receive JSON messages
+ *         return connection.receive();
+ *     })
+ *     .subscribe(
+ *         json -> handleMessage(json),
+ *         error -> handleError(error)  // WebSocketTransportException with context
+ *     );
+ * }

+ *
+ * 
Usage example (binary protocol):
+ *
+ * 
{@code
+ * client.connect(request, byte[].class)
+ *     .flatMapMany(connection -> {
+ *         // Send binary message
+ *         connection.send(binaryData).subscribe();
+ *
+ *         // Receive binary messages
+ *         return connection.receive();
+ *     })
+ *     .subscribe(
+ *         data -> handleBinaryMessage(data),
+ *         error -> handleError(error)
+ *     );
+ * }

+ *
+ * @param  Message type: String for text protocols, byte[] for binary protocols
+ */
+public interface WebSocketConnection {
+
+    /**
+     * Send a message.
+     *
+     * 
Implementation should:
+     *
+     * 
    
+     *   
  • Log at DEBUG level before sending
+     *   
  • Log at TRACE level with message size
+     *   
  • Wrap errors in WebSocketTransportException using onErrorMap
+     *   
  • Log errors at ERROR level with full context
+     * 

+     *
+     * @param data Message data (String or byte[])
+     * @return Mono that completes when send is done, or emits WebSocketTransportException on error
+     */
+    Mono send(T data);
+
+    /**
+     * Receive message stream.
+     *
+     * 
The returned Flux:
+     *
+     * 
    
+     *   
  • Completes when connection is closed normally
+     *   
  • Emits error (WebSocketTransportException) on connection failure
+     *   
  • Logs each received message at TRACE level
+     * 

+     *
+     * 
Implementation should:
+     *
+     * 
    
+     *   
  • Log received messages at TRACE level with size
+     *   
  • Wrap errors in WebSocketTransportException using onErrorMap
+     *   
  • Log errors at ERROR level with connection context
+     * 

+     *
+     * @return Message stream (String or byte[])
+     */
+    Flux receive();
+
+    /**
+     * Close the connection.
+     *
+     * 
Implementation should:
+     *
+     * 
    
+     *   
  • Log at INFO level with close code and reason
+     *   
  • Send WebSocket close frame with code 1000 (normal closure)
+     *   
  • Clean up resources
+     * 

+     *
+     * @return Mono that completes when connection is closed
+     */
+    Mono close();
+
+    /**
+     * Check if connection is open.
+     *
+     * @return true if connection is open
+     */
+    boolean isOpen();
+
+    /**
+     * Get close information (if closed).
+     *
+     * @return Close info, or null if not closed
+     */
+    CloseInfo getCloseInfo();
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketRequest.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketRequest.java
new file mode 100644
index 000000000..2a97d86b2
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketRequest.java
@@ -0,0 +1,139 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import java.time.Duration;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * WebSocket connection request configuration.
+ *
+ * 
Usage example:
+ *
+ * 
{@code
+ * WebSocketRequest request = WebSocketRequest.builder("wss://api.openai.com/v1/realtime")
+ *     .header("Authorization", "Bearer " + apiKey)
+ *     .header("OpenAI-Beta", "realtime=v1")
+ *     .connectTimeout(Duration.ofSeconds(30))
+ *     .build();
+ * }

+ */
+public final class WebSocketRequest {
+
+    private final String url;
+    private final Map headers;
+    private final Duration connectTimeout;
+
+    private WebSocketRequest(Builder builder) {
+        this.url = builder.url;
+        this.headers = Collections.unmodifiableMap(new LinkedHashMap<>(builder.headers));
+        this.connectTimeout = builder.connectTimeout;
+    }
+
+    /**
+     * Get the WebSocket URL.
+     *
+     * @return WebSocket URL
+     */
+    public String getUrl() {
+        return url;
+    }
+
+    /**
+     * Get the request headers.
+     *
+     * @return Request headers (immutable)
+     */
+    public Map getHeaders() {
+        return headers;
+    }
+
+    /**
+     * Get the connection timeout.
+     *
+     * @return Connection timeout
+     */
+    public Duration getConnectTimeout() {
+        return connectTimeout;
+    }
+
+    /**
+     * Create a new builder with the specified URL.
+     *
+     * @param url WebSocket URL
+     * @return Builder instance
+     */
+    public static Builder builder(String url) {
+        return new Builder(url);
+    }
+
+    /** Builder for WebSocketRequest. */
+    public static class Builder {
+        private final String url;
+        private final Map headers = new LinkedHashMap<>();
+        private Duration connectTimeout = Duration.ofSeconds(30);
+
+        private Builder(String url) {
+            this.url = Objects.requireNonNull(url, "url is required");
+        }
+
+        /**
+         * Add a header.
+         *
+         * @param name Header name
+         * @param value Header value
+         * @return this builder
+         */
+        public Builder header(String name, String value) {
+            this.headers.put(name, value);
+            return this;
+        }
+
+        /**
+         * Add multiple headers.
+         *
+         * @param headers Headers to add
+         * @return this builder
+         */
+        public Builder headers(Map headers) {
+            this.headers.putAll(headers);
+            return this;
+        }
+
+        /**
+         * Set the connection timeout.
+         *
+         * @param timeout Connection timeout
+         * @return this builder
+         */
+        public Builder connectTimeout(Duration timeout) {
+            this.connectTimeout = timeout;
+            return this;
+        }
+
+        /**
+         * Build the WebSocketRequest.
+         *
+         * @return WebSocketRequest instance
+         */
+        public WebSocketRequest build() {
+            return new WebSocketRequest(this);
+        }
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfig.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfig.java
new file mode 100644
index 000000000..69a028dc3
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfig.java
@@ -0,0 +1,237 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import io.agentscope.core.model.transport.ProxyConfig;
+import java.time.Duration;
+
+/**
+ * Configuration for WebSocket clients.
+ *
+ * 
This class holds configuration options for WebSocket client behavior such as
+ * timeouts, heartbeat intervals, proxy settings, and SSL options.
+ *
+ * 
Usage example:
+ *
+ * 
{@code
+ * WebSocketTransportConfig config = WebSocketTransportConfig.builder()
+ *     .connectTimeout(Duration.ofSeconds(30))
+ *     .pingInterval(Duration.ofSeconds(30))
+ *     .proxy(ProxyConfig.http("proxy.example.com", 8080))
+ *     .build();
+ *
+ * WebSocketTransport client = OkHttpWebSocketTransport.create(config);
+ * }

+ */
+public class WebSocketTransportConfig {
+
+    /** Default connect timeout: 30 seconds. */
+    public static final Duration DEFAULT_CONNECT_TIMEOUT = Duration.ofSeconds(30);
+
+    /** Default read timeout: 0 (no timeout for WebSocket). */
+    public static final Duration DEFAULT_READ_TIMEOUT = Duration.ZERO;
+
+    /** Default write timeout: 30 seconds. */
+    public static final Duration DEFAULT_WRITE_TIMEOUT = Duration.ofSeconds(30);
+
+    /** Default ping interval: 30 seconds. */
+    public static final Duration DEFAULT_PING_INTERVAL = Duration.ofSeconds(30);
+
+    private final Duration connectTimeout;
+    private final Duration readTimeout;
+    private final Duration writeTimeout;
+    private final Duration pingInterval;
+    private final ProxyConfig proxyConfig;
+    private final boolean ignoreSsl;
+
+    private WebSocketTransportConfig(Builder builder) {
+        this.connectTimeout = builder.connectTimeout;
+        this.readTimeout = builder.readTimeout;
+        this.writeTimeout = builder.writeTimeout;
+        this.pingInterval = builder.pingInterval;
+        this.proxyConfig = builder.proxyConfig;
+        this.ignoreSsl = builder.ignoreSsl;
+    }
+
+    /**
+     * Get the connect timeout.
+     *
+     * @return the connect timeout duration
+     */
+    public Duration getConnectTimeout() {
+        return connectTimeout;
+    }
+
+    /**
+     * Get the read timeout.
+     *
+     * @return the read timeout duration
+     */
+    public Duration getReadTimeout() {
+        return readTimeout;
+    }
+
+    /**
+     * Get the write timeout.
+     *
+     * @return the write timeout duration
+     */
+    public Duration getWriteTimeout() {
+        return writeTimeout;
+    }
+
+    /**
+     * Get the ping interval for heartbeat (OkHttp only).
+     *
+     * @return the ping interval duration
+     */
+    public Duration getPingInterval() {
+        return pingInterval;
+    }
+
+    /**
+     * Get the proxy configuration.
+     *
+     * @return the proxy configuration, or null if no proxy is configured
+     */
+    public ProxyConfig getProxyConfig() {
+        return proxyConfig;
+    }
+
+    /**
+     * Get whether SSL certificate verification should be ignored.
+     *
+     * 
Warning: Setting this to true disables SSL certificate verification,
+     * which makes the connection vulnerable to man-in-the-middle attacks.
+     * This should only be used for testing or with trusted self-signed certificates.
+     *
+     * @return true to ignore SSL certificate verification, false otherwise
+     */
+    public boolean isIgnoreSsl() {
+        return ignoreSsl;
+    }
+
+    /**
+     * Create a new builder for WebSocketTransportConfig.
+     *
+     * @return a new Builder instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Create a default configuration.
+     *
+     * @return a default WebSocketTransportConfig instance
+     */
+    public static WebSocketTransportConfig defaults() {
+        return builder().build();
+    }
+
+    /**
+     * Builder for WebSocketTransportConfig.
+     */
+    public static class Builder {
+        private Duration connectTimeout = DEFAULT_CONNECT_TIMEOUT;
+        private Duration readTimeout = DEFAULT_READ_TIMEOUT;
+        private Duration writeTimeout = DEFAULT_WRITE_TIMEOUT;
+        private Duration pingInterval = DEFAULT_PING_INTERVAL;
+        private ProxyConfig proxyConfig = null;
+        private boolean ignoreSsl = false;
+
+        /**
+         * Set the connect timeout.
+         *
+         * @param connectTimeout the connect timeout duration
+         * @return this builder
+         */
+        public Builder connectTimeout(Duration connectTimeout) {
+            this.connectTimeout = connectTimeout;
+            return this;
+        }
+
+        /**
+         * Set the read timeout.
+         *
+         * @param readTimeout the read timeout duration
+         * @return this builder
+         */
+        public Builder readTimeout(Duration readTimeout) {
+            this.readTimeout = readTimeout;
+            return this;
+        }
+
+        /**
+         * Set the write timeout.
+         *
+         * @param writeTimeout the write timeout duration
+         * @return this builder
+         */
+        public Builder writeTimeout(Duration writeTimeout) {
+            this.writeTimeout = writeTimeout;
+            return this;
+        }
+
+        /**
+         * Set the ping interval for heartbeat (OkHttp only).
+         *
+         * @param pingInterval the ping interval duration
+         * @return this builder
+         */
+        public Builder pingInterval(Duration pingInterval) {
+            this.pingInterval = pingInterval;
+            return this;
+        }
+
+        /**
+         * Set the proxy configuration.
+         *
+         * 
Supports HTTP and SOCKS proxies. See {@link ProxyConfig} for details.
+         *
+         * @param proxyConfig the proxy configuration
+         * @return this builder
+         */
+        public Builder proxy(ProxyConfig proxyConfig) {
+            this.proxyConfig = proxyConfig;
+            return this;
+        }
+
+        /**
+         * Set whether to ignore SSL certificate verification.
+         *
+         * 
Warning: Setting this to true disables SSL certificate verification,
+         * which makes the connection vulnerable to man-in-the-middle attacks.
+         * This should only be used for testing or with trusted self-signed certificates.
+         *
+         * @param ignoreSsl true to ignore SSL certificate verification, false otherwise
+         * @return this builder
+         */
+        public Builder ignoreSsl(boolean ignoreSsl) {
+            this.ignoreSsl = ignoreSsl;
+            return this;
+        }
+
+        /**
+         * Build the WebSocketTransportConfig.
+         *
+         * @return a new WebSocketTransportConfig instance
+         */
+        public WebSocketTransportConfig build() {
+            return new WebSocketTransportConfig(this);
+        }
+    }
+}
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportException.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportException.java
new file mode 100644
index 000000000..4399fa349
--- /dev/null
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/websocket/WebSocketTransportException.java
@@ -0,0 +1,106 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * WebSocket transport layer exception.
+ *
+ * 
Wraps underlying transport errors with connection context to help diagnose issues. This
+ * exception preserves the complete error chain while adding transport-specific context.
+ *
+ * 
Context information includes:
+ *
+ * 
    
+ *   
  • WebSocket URL
+ *   
  • Connection state (OPEN/CLOSED/CONNECTING)
+ *   
  • Request headers (for authentication/configuration debugging)
+ * 

+ */
+public class WebSocketTransportException extends RuntimeException {
+
+    private final String url;
+    private final String connectionState;
+    private final Map headers;
+
+    /**
+     * Create a WebSocketTransportException.
+     *
+     * @param message Error message
+     * @param cause Root cause exception
+     * @param url WebSocket URL
+     * @param connectionState Connection state (OPEN/CLOSED/CONNECTING)
+     */
+    public WebSocketTransportException(
+            String message, Throwable cause, String url, String connectionState) {
+        this(message, cause, url, connectionState, Collections.emptyMap());
+    }
+
+    /**
+     * Create a WebSocketTransportException with headers.
+     *
+     * @param message Error message
+     * @param cause Root cause exception
+     * @param url WebSocket URL
+     * @param connectionState Connection state
+     * @param headers Request headers (for debugging)
+     */
+    public WebSocketTransportException(
+            String message,
+            Throwable cause,
+            String url,
+            String connectionState,
+            Map headers) {
+        super(message, cause);
+        this.url = url;
+        this.connectionState = connectionState;
+        this.headers = headers != null ? Map.copyOf(headers) : Collections.emptyMap();
+    }
+
+    /**
+     * Get the WebSocket URL.
+     *
+     * @return WebSocket URL
+     */
+    public String getUrl() {
+        return url;
+    }
+
+    /**
+     * Get the connection state.
+     *
+     * @return Connection state
+     */
+    public String getConnectionState() {
+        return connectionState;
+    }
+
+    /**
+     * Get the request headers.
+     *
+     * @return Request headers (immutable)
+     */
+    public Map getHeaders() {
+        return headers;
+    }
+
+    @Override
+    public String getMessage() {
+        return String.format("%s [url=%s, state=%s]", super.getMessage(), url, connectionState);
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/ProxyConfigTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/ProxyConfigTest.java
new file mode 100644
index 000000000..071aabbda
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/ProxyConfigTest.java
@@ -0,0 +1,236 @@
+/*
+ * 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.model.transport;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.net.Proxy;
+import java.util.Set;
+import org.junit.jupiter.api.Test;
+
+class ProxyConfigTest {
+
+    @Test
+    void testHttpProxyWithoutAuth() {
+        ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080);
+
+        assertEquals(ProxyType.HTTP, proxy.getType());
+        assertEquals("proxy.example.com", proxy.getHost());
+        assertEquals(8080, proxy.getPort());
+        assertNull(proxy.getUsername());
+        assertNull(proxy.getPassword());
+        assertFalse(proxy.hasAuthentication());
+    }
+
+    @Test
+    void testHttpProxyWithAuth() {
+        ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080, "user", "pass");
+
+        assertEquals(ProxyType.HTTP, proxy.getType());
+        assertEquals("proxy.example.com", proxy.getHost());
+        assertEquals(8080, proxy.getPort());
+        assertEquals("user", proxy.getUsername());
+        assertEquals("pass", proxy.getPassword());
+        assertTrue(proxy.hasAuthentication());
+    }
+
+    @Test
+    void testSocks4Proxy() {
+        ProxyConfig proxy = ProxyConfig.socks4("socks.example.com", 1080);
+
+        assertEquals(ProxyType.SOCKS4, proxy.getType());
+        assertEquals("socks.example.com", proxy.getHost());
+        assertEquals(1080, proxy.getPort());
+        assertFalse(proxy.hasAuthentication());
+    }
+
+    @Test
+    void testSocks5ProxyWithoutAuth() {
+        ProxyConfig proxy = ProxyConfig.socks5("socks.example.com", 1080);
+
+        assertEquals(ProxyType.SOCKS5, proxy.getType());
+        assertEquals("socks.example.com", proxy.getHost());
+        assertEquals(1080, proxy.getPort());
+        assertFalse(proxy.hasAuthentication());
+    }
+
+    @Test
+    void testSocks5ProxyWithAuth() {
+        ProxyConfig proxy = ProxyConfig.socks5("socks.example.com", 1080, "user", "pass");
+
+        assertEquals(ProxyType.SOCKS5, proxy.getType());
+        assertEquals("socks.example.com", proxy.getHost());
+        assertEquals(1080, proxy.getPort());
+        assertEquals("user", proxy.getUsername());
+        assertEquals("pass", proxy.getPassword());
+        assertTrue(proxy.hasAuthentication());
+    }
+
+    @Test
+    void testBuilderWithNonProxyHosts() {
+        ProxyConfig proxy =
+                ProxyConfig.builder()
+                        .type(ProxyType.HTTP)
+                        .host("proxy.example.com")
+                        .port(8080)
+                        .nonProxyHosts(Set.of("localhost", "*.internal.com"))
+                        .build();
+
+        assertNotNull(proxy.getNonProxyHosts());
+        assertEquals(2, proxy.getNonProxyHosts().size());
+        assertTrue(proxy.getNonProxyHosts().contains("localhost"));
+        assertTrue(proxy.getNonProxyHosts().contains("*.internal.com"));
+    }
+
+    @Test
+    void testShouldBypassExactMatch() {
+        ProxyConfig proxy =
+                ProxyConfig.builder()
+                        .type(ProxyType.HTTP)
+                        .host("proxy.example.com")
+                        .port(8080)
+                        .nonProxyHosts(Set.of("localhost", "127.0.0.1"))
+                        .build();
+
+        assertTrue(proxy.shouldBypass("localhost"));
+        assertTrue(proxy.shouldBypass("127.0.0.1"));
+        assertFalse(proxy.shouldBypass("example.com"));
+    }
+
+    @Test
+    void testShouldBypassWildcardSuffix() {
+        ProxyConfig proxy =
+                ProxyConfig.builder()
+                        .type(ProxyType.HTTP)
+                        .host("proxy.example.com")
+                        .port(8080)
+                        .nonProxyHosts(Set.of("*.internal.com"))
+                        .build();
+
+        assertTrue(proxy.shouldBypass("app.internal.com"));
+        assertTrue(proxy.shouldBypass("api.internal.com"));
+        assertFalse(proxy.shouldBypass("internal.com"));
+        assertFalse(proxy.shouldBypass("example.com"));
+    }
+
+    @Test
+    void testShouldBypassWildcardPrefix() {
+        ProxyConfig proxy =
+                ProxyConfig.builder()
+                        .type(ProxyType.HTTP)
+                        .host("proxy.example.com")
+                        .port(8080)
+                        .nonProxyHosts(Set.of("192.168.*"))
+                        .build();
+
+        assertTrue(proxy.shouldBypass("192.168.1.1"));
+        assertTrue(proxy.shouldBypass("192.168.0.100"));
+        assertFalse(proxy.shouldBypass("10.0.0.1"));
+    }
+
+    @Test
+    void testShouldBypassWithNullNonProxyHosts() {
+        ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080);
+
+        assertFalse(proxy.shouldBypass("localhost"));
+        assertFalse(proxy.shouldBypass("example.com"));
+    }
+
+    @Test
+    void testToJavaProxyHttp() {
+        ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080);
+
+        Proxy javaProxy = proxy.toJavaProxy();
+
+        assertEquals(Proxy.Type.HTTP, javaProxy.type());
+        assertNotNull(javaProxy.address());
+    }
+
+    @Test
+    void testToJavaProxySocks() {
+        ProxyConfig proxy = ProxyConfig.socks5("socks.example.com", 1080);
+
+        Proxy javaProxy = proxy.toJavaProxy();
+
+        assertEquals(Proxy.Type.SOCKS, javaProxy.type());
+        assertNotNull(javaProxy.address());
+    }
+
+    @Test
+    void testBuilderRequiresType() {
+        assertThrows(
+                NullPointerException.class,
+                () -> ProxyConfig.builder().host("proxy.example.com").port(8080).build());
+    }
+
+    @Test
+    void testBuilderRequiresHost() {
+        assertThrows(
+                NullPointerException.class,
+                () -> ProxyConfig.builder().type(ProxyType.HTTP).port(8080).build());
+    }
+
+    @Test
+    void testBuilderValidatesPort() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ProxyConfig.builder()
+                                .type(ProxyType.HTTP)
+                                .host("proxy.example.com")
+                                .port(0)
+                                .build());
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ProxyConfig.builder()
+                                .type(ProxyType.HTTP)
+                                .host("proxy.example.com")
+                                .port(70000)
+                                .build());
+    }
+
+    @Test
+    void testEqualsAndHashCode() {
+        ProxyConfig proxy1 = ProxyConfig.http("proxy.example.com", 8080);
+        ProxyConfig proxy2 = ProxyConfig.http("proxy.example.com", 8080);
+        ProxyConfig proxy3 = ProxyConfig.http("proxy.example.com", 8081);
+
+        assertEquals(proxy1, proxy2);
+        assertEquals(proxy1.hashCode(), proxy2.hashCode());
+        assertFalse(proxy1.equals(proxy3));
+    }
+
+    @Test
+    void testToString() {
+        ProxyConfig proxy = ProxyConfig.http("proxy.example.com", 8080, "user", "secretpass");
+
+        String str = proxy.toString();
+
+        assertTrue(str.contains("HTTP"));
+        assertTrue(str.contains("proxy.example.com"));
+        assertTrue(str.contains("8080"));
+        assertTrue(str.contains("user"));
+        assertTrue(str.contains("****")); // Password should be masked
+        assertFalse(str.contains("secretpass")); // Password should not be visible
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/CloseInfoTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/CloseInfoTest.java
new file mode 100644
index 000000000..6f22d38fc
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/CloseInfoTest.java
@@ -0,0 +1,75 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("CloseInfo Tests")
+class CloseInfoTest {
+
+    @Test
+    @DisplayName("Should create CloseInfo with code and reason")
+    void shouldCreateCloseInfoWithCodeAndReason() {
+        CloseInfo closeInfo = new CloseInfo(1000, "Normal closure");
+
+        assertEquals(1000, closeInfo.code());
+        assertEquals("Normal closure", closeInfo.reason());
+    }
+
+    @Test
+    @DisplayName("Should identify normal closure")
+    void shouldIdentifyNormalClosure() {
+        CloseInfo normalClose = new CloseInfo(CloseInfo.NORMAL_CLOSURE, "Normal");
+        CloseInfo abnormalClose = new CloseInfo(CloseInfo.ABNORMAL_CLOSURE, "Abnormal");
+
+        assertTrue(normalClose.isNormal());
+        assertFalse(abnormalClose.isNormal());
+    }
+
+    @Test
+    @DisplayName("Should create normal closure via factory method")
+    void shouldCreateNormalClosureViaFactoryMethod() {
+        CloseInfo closeInfo = CloseInfo.normal("Session ended");
+
+        assertEquals(CloseInfo.NORMAL_CLOSURE, closeInfo.code());
+        assertEquals("Session ended", closeInfo.reason());
+        assertTrue(closeInfo.isNormal());
+    }
+
+    @Test
+    @DisplayName("Should create abnormal closure via factory method")
+    void shouldCreateAbnormalClosureViaFactoryMethod() {
+        CloseInfo closeInfo = CloseInfo.abnormal("Connection lost");
+
+        assertEquals(CloseInfo.ABNORMAL_CLOSURE, closeInfo.code());
+        assertEquals("Connection lost", closeInfo.reason());
+        assertFalse(closeInfo.isNormal());
+    }
+
+    @Test
+    @DisplayName("Should have correct close code constants")
+    void shouldHaveCorrectCloseCodeConstants() {
+        assertEquals(1000, CloseInfo.NORMAL_CLOSURE);
+        assertEquals(1001, CloseInfo.GOING_AWAY);
+        assertEquals(1002, CloseInfo.PROTOCOL_ERROR);
+        assertEquals(1006, CloseInfo.ABNORMAL_CLOSURE);
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnectionTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnectionTest.java
new file mode 100644
index 000000000..19f9885e1
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketConnectionTest.java
@@ -0,0 +1,617 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyBoolean;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.net.http.WebSocket;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+@DisplayName("JdkWebSocketConnection Tests")
+class JdkWebSocketConnectionTest {
+
+    private static final String TEST_URL = "wss://example.com";
+
+    @Nested
+    @DisplayName("Basic State Tests")
+    class BasicStateTests {
+
+        private JdkWebSocketConnection textConnection;
+        private JdkWebSocketConnection binaryConnection;
+
+        @BeforeEach
+        void setUp() {
+            textConnection = new JdkWebSocketConnection<>(TEST_URL, String.class);
+            binaryConnection = new JdkWebSocketConnection<>(TEST_URL, byte[].class);
+        }
+
+        @Test
+        @DisplayName("Should not be open before WebSocket is set")
+        void shouldNotBeOpenBeforeWebSocketIsSet() {
+            assertFalse(textConnection.isOpen());
+            assertFalse(binaryConnection.isOpen());
+        }
+
+        @Test
+        @DisplayName("Should return null close info before close")
+        void shouldReturnNullCloseInfoBeforeClose() {
+            assertNull(textConnection.getCloseInfo());
+            assertNull(binaryConnection.getCloseInfo());
+        }
+
+        @Test
+        @DisplayName("Should be open after WebSocket is set")
+        void shouldBeOpenAfterWebSocketIsSet() {
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            textConnection.setWebSocket(mockWebSocket);
+
+            assertTrue(textConnection.isOpen());
+        }
+
+        @Test
+        @DisplayName("Should not be open after close")
+        void shouldNotBeOpenAfterClose() {
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            when(mockWebSocket.sendClose(eq(CloseInfo.NORMAL_CLOSURE), anyString()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+            textConnection.setWebSocket(mockWebSocket);
+
+            textConnection.close().block();
+
+            assertFalse(textConnection.isOpen());
+        }
+
+        @Test
+        @DisplayName("Should have listener available")
+        void shouldHaveListenerAvailable() {
+            assertNotNull(textConnection.getListener());
+            assertNotNull(binaryConnection.getListener());
+        }
+    }
+
+    @Nested
+    @DisplayName("Listener Callback Tests")
+    class ListenerCallbackTests {
+
+        private JdkWebSocketConnection textConnection;
+        private JdkWebSocketConnection binaryConnection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            textConnection = new JdkWebSocketConnection<>(TEST_URL, String.class);
+            binaryConnection = new JdkWebSocketConnection<>(TEST_URL, byte[].class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should request more data on open")
+        void shouldRequestMoreDataOnOpen() {
+            WebSocket.Listener listener = textConnection.getListener();
+
+            listener.onOpen(mockWebSocket);
+
+            verify(mockWebSocket).request(1);
+        }
+
+        @Test
+        @DisplayName("Should handle single fragment text message")
+        void shouldHandleSingleFragmentTextMessage() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            // Subscribe to messages
+            List received = new ArrayList<>();
+            textConnection.receive().subscribe(received::add);
+
+            // Simulate single fragment message
+            listener.onText(mockWebSocket, "Hello World", true);
+
+            assertEquals(1, received.size());
+            assertEquals("Hello World", received.get(0));
+            verify(mockWebSocket).request(1);
+        }
+
+        @Test
+        @DisplayName("Should handle multiple fragment text message")
+        void shouldHandleMultipleFragmentTextMessage() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            List received = new ArrayList<>();
+            textConnection.receive().subscribe(received::add);
+
+            // Simulate fragmented message
+            listener.onText(mockWebSocket, "Hello ", false);
+            listener.onText(mockWebSocket, "World", true);
+
+            assertEquals(1, received.size());
+            assertEquals("Hello World", received.get(0));
+            verify(mockWebSocket, times(2)).request(1);
+        }
+
+        @Test
+        @DisplayName("Should handle single fragment binary message")
+        void shouldHandleSingleFragmentBinaryMessage() {
+            binaryConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = binaryConnection.getListener();
+
+            List received = new ArrayList<>();
+            binaryConnection.receive().subscribe(received::add);
+
+            byte[] data = {0x01, 0x02, 0x03};
+            ByteBuffer buffer = ByteBuffer.wrap(data);
+            listener.onBinary(mockWebSocket, buffer, true);
+
+            assertEquals(1, received.size());
+            assertArrayEquals(data, received.get(0));
+            verify(mockWebSocket).request(1);
+        }
+
+        @Test
+        @DisplayName("Should handle multiple fragment binary message")
+        void shouldHandleMultipleFragmentBinaryMessage() {
+            binaryConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = binaryConnection.getListener();
+
+            List received = new ArrayList<>();
+            binaryConnection.receive().subscribe(received::add);
+
+            // Simulate fragmented binary message
+            ByteBuffer buffer1 = ByteBuffer.wrap(new byte[] {0x01, 0x02});
+            ByteBuffer buffer2 = ByteBuffer.wrap(new byte[] {0x03, 0x04});
+            listener.onBinary(mockWebSocket, buffer1, false);
+            listener.onBinary(mockWebSocket, buffer2, true);
+
+            assertEquals(1, received.size());
+            assertArrayEquals(new byte[] {0x01, 0x02, 0x03, 0x04}, received.get(0));
+            verify(mockWebSocket, times(2)).request(1);
+        }
+
+        @Test
+        @DisplayName("Should handle binary buffer expansion")
+        void shouldHandleBinaryBufferExpansion() {
+            binaryConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = binaryConnection.getListener();
+
+            List received = new ArrayList<>();
+            binaryConnection.receive().subscribe(received::add);
+
+            // First fragment - small
+            byte[] small = new byte[10];
+            for (int i = 0; i < 10; i++) small[i] = (byte) i;
+
+            // Second fragment - larger (requires buffer expansion)
+            byte[] large = new byte[100];
+            for (int i = 0; i < 100; i++) large[i] = (byte) (i + 10);
+
+            listener.onBinary(mockWebSocket, ByteBuffer.wrap(small), false);
+            listener.onBinary(mockWebSocket, ByteBuffer.wrap(large), true);
+
+            assertEquals(1, received.size());
+            assertEquals(110, received.get(0).length);
+        }
+
+        @Test
+        @DisplayName("Should handle onClose")
+        void shouldHandleOnClose() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            listener.onClose(mockWebSocket, CloseInfo.NORMAL_CLOSURE, "Normal closure");
+
+            assertFalse(textConnection.isOpen());
+            assertNotNull(textConnection.getCloseInfo());
+            assertEquals(CloseInfo.NORMAL_CLOSURE, textConnection.getCloseInfo().code());
+            assertEquals("Normal closure", textConnection.getCloseInfo().reason());
+        }
+
+        @Test
+        @DisplayName("Should complete receive flux on close")
+        void shouldCompleteReceiveFluxOnClose() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            StepVerifier.create(textConnection.receive())
+                    .then(() -> listener.onClose(mockWebSocket, CloseInfo.NORMAL_CLOSURE, "Bye"))
+                    .verifyComplete();
+        }
+
+        @Test
+        @DisplayName("Should handle onError")
+        void shouldHandleOnError() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            listener.onError(mockWebSocket, new RuntimeException("Test error"));
+
+            assertFalse(textConnection.isOpen());
+            assertNotNull(textConnection.getCloseInfo());
+            assertEquals(CloseInfo.ABNORMAL_CLOSURE, textConnection.getCloseInfo().code());
+        }
+
+        @Test
+        @DisplayName("Should emit error on receive when onError is called")
+        void shouldEmitErrorOnReceiveWhenOnErrorIsCalled() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            StepVerifier.create(textConnection.receive())
+                    .then(
+                            () ->
+                                    listener.onError(
+                                            mockWebSocket, new RuntimeException("Connection lost")))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+    }
+
+    @Nested
+    @DisplayName("Message Type Conversion Tests")
+    class MessageTypeConversionTests {
+
+        @Test
+        @DisplayName("Should receive text as String when messageType is String")
+        void shouldReceiveTextAsStringWhenMessageTypeIsString() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, String.class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            listener.onText(mockWebSocket, "Hello", true);
+
+            assertEquals(1, received.size());
+            assertEquals("Hello", received.get(0));
+        }
+
+        @Test
+        @DisplayName("Should receive text as byte[] when messageType is byte[]")
+        void shouldReceiveTextAsByteArrayWhenMessageTypeIsByteArray() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, byte[].class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            listener.onText(mockWebSocket, "Hello", true);
+
+            assertEquals(1, received.size());
+            assertArrayEquals("Hello".getBytes(StandardCharsets.UTF_8), received.get(0));
+        }
+
+        @Test
+        @DisplayName("Should receive binary as byte[] when messageType is byte[]")
+        void shouldReceiveBinaryAsByteArrayWhenMessageTypeIsByteArray() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, byte[].class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            byte[] data = {0x01, 0x02, 0x03};
+            listener.onBinary(mockWebSocket, ByteBuffer.wrap(data), true);
+
+            assertEquals(1, received.size());
+            assertArrayEquals(data, received.get(0));
+        }
+
+        @Test
+        @DisplayName("Should receive binary as String when messageType is String")
+        void shouldReceiveBinaryAsStringWhenMessageTypeIsString() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, String.class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            byte[] data = "Hello".getBytes(StandardCharsets.UTF_8);
+            listener.onBinary(mockWebSocket, ByteBuffer.wrap(data), true);
+
+            assertEquals(1, received.size());
+            assertEquals("Hello", received.get(0));
+        }
+    }
+
+    @Nested
+    @DisplayName("Send Message Tests")
+    class SendMessageTests {
+
+        private JdkWebSocketConnection textConnection;
+        private JdkWebSocketConnection binaryConnection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            textConnection = new JdkWebSocketConnection<>(TEST_URL, String.class);
+            binaryConnection = new JdkWebSocketConnection<>(TEST_URL, byte[].class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should fail send when not connected - text")
+        void shouldFailSendWhenNotConnectedText() {
+            StepVerifier.create(textConnection.send("hello"))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should fail send when not connected - binary")
+        void shouldFailSendWhenNotConnectedBinary() {
+            StepVerifier.create(binaryConnection.send("hello".getBytes(StandardCharsets.UTF_8)))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should send text message successfully")
+        void shouldSendTextMessageSuccessfully() {
+            textConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendText(anyString(), anyBoolean()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            StepVerifier.create(textConnection.send("Hello")).verifyComplete();
+
+            verify(mockWebSocket).sendText("Hello", true);
+        }
+
+        @Test
+        @DisplayName("Should send binary message successfully")
+        void shouldSendBinaryMessageSuccessfully() {
+            binaryConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendBinary(
+                            org.mockito.ArgumentMatchers.any(ByteBuffer.class), eq(true)))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            byte[] data = {0x01, 0x02, 0x03};
+            StepVerifier.create(binaryConnection.send(data)).verifyComplete();
+
+            verify(mockWebSocket)
+                    .sendBinary(org.mockito.ArgumentMatchers.any(ByteBuffer.class), eq(true));
+        }
+
+        @Test
+        @DisplayName("Should fail send when WebSocket sendText fails")
+        void shouldFailSendWhenWebSocketSendTextFails() {
+            textConnection.setWebSocket(mockWebSocket);
+            CompletableFuture failedFuture = new CompletableFuture<>();
+            failedFuture.completeExceptionally(new RuntimeException("Send failed"));
+            when(mockWebSocket.sendText(anyString(), anyBoolean())).thenReturn(failedFuture);
+
+            StepVerifier.create(textConnection.send("Hello"))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should fail send when connection is closed")
+        void shouldFailSendWhenConnectionIsClosed() {
+            textConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendClose(eq(CloseInfo.NORMAL_CLOSURE), anyString()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            textConnection.close().block();
+
+            StepVerifier.create(textConnection.send("Hello"))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should handle concurrent sends safely")
+        void shouldHandleConcurrentSendsSafely() {
+            textConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendText(anyString(), anyBoolean()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            List> sends =
+                    IntStream.range(0, 100)
+                            .mapToObj(i -> textConnection.send("msg-" + i))
+                            .collect(Collectors.toList());
+
+            Flux.merge(sends).blockLast(Duration.ofSeconds(10));
+
+            verify(mockWebSocket, times(100)).sendText(anyString(), eq(true));
+        }
+    }
+
+    @Nested
+    @DisplayName("Receive Message Tests")
+    class ReceiveMessageTests {
+
+        private JdkWebSocketConnection textConnection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            textConnection = new JdkWebSocketConnection<>(TEST_URL, String.class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should receive multiple messages as Flux")
+        void shouldReceiveMultipleMessagesAsFlux() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            StepVerifier.create(textConnection.receive().take(3))
+                    .then(() -> listener.onText(mockWebSocket, "Message 1", true))
+                    .expectNext("Message 1")
+                    .then(() -> listener.onText(mockWebSocket, "Message 2", true))
+                    .expectNext("Message 2")
+                    .then(() -> listener.onText(mockWebSocket, "Message 3", true))
+                    .expectNext("Message 3")
+                    .verifyComplete();
+        }
+
+        @Test
+        @DisplayName("Should map non-WebSocketTransportException to WebSocketTransportException")
+        void shouldMapNonWebSocketTransportExceptionToWebSocketTransportException() {
+            textConnection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = textConnection.getListener();
+
+            StepVerifier.create(textConnection.receive())
+                    .then(() -> listener.onError(mockWebSocket, new RuntimeException("Test error")))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+    }
+
+    @Nested
+    @DisplayName("Close Connection Tests")
+    class CloseConnectionTests {
+
+        private JdkWebSocketConnection textConnection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            textConnection = new JdkWebSocketConnection<>(TEST_URL, String.class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should complete close when not connected")
+        void shouldCompleteCloseWhenNotConnected() {
+            StepVerifier.create(textConnection.close()).verifyComplete();
+        }
+
+        @Test
+        @DisplayName("Should close connection successfully")
+        void shouldCloseConnectionSuccessfully() {
+            textConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendClose(eq(CloseInfo.NORMAL_CLOSURE), anyString()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            StepVerifier.create(textConnection.close()).verifyComplete();
+
+            assertFalse(textConnection.isOpen());
+            assertNotNull(textConnection.getCloseInfo());
+            assertEquals(CloseInfo.NORMAL_CLOSURE, textConnection.getCloseInfo().code());
+            verify(mockWebSocket).sendClose(CloseInfo.NORMAL_CLOSURE, "");
+        }
+
+        @Test
+        @DisplayName("Should handle close failure")
+        void shouldHandleCloseFailure() {
+            textConnection.setWebSocket(mockWebSocket);
+            CompletableFuture failedFuture = new CompletableFuture<>();
+            failedFuture.completeExceptionally(new RuntimeException("Close failed"));
+            when(mockWebSocket.sendClose(eq(CloseInfo.NORMAL_CLOSURE), anyString()))
+                    .thenReturn(failedFuture);
+
+            StepVerifier.create(textConnection.close())
+                    .expectError(RuntimeException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should be idempotent when closing multiple times")
+        void shouldBeIdempotentWhenClosingMultipleTimes() {
+            textConnection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.sendClose(eq(CloseInfo.NORMAL_CLOSURE), anyString()))
+                    .thenReturn(CompletableFuture.completedFuture(mockWebSocket));
+
+            // First close
+            StepVerifier.create(textConnection.close()).verifyComplete();
+
+            // Second close should also complete (without calling sendClose again)
+            StepVerifier.create(textConnection.close()).verifyComplete();
+
+            // sendClose should only be called once
+            verify(mockWebSocket, times(1)).sendClose(CloseInfo.NORMAL_CLOSURE, "");
+        }
+    }
+
+    @Nested
+    @DisplayName("CloseInfo Tests")
+    class CloseInfoTests {
+
+        @Test
+        @DisplayName("Should set close info on normal close")
+        void shouldSetCloseInfoOnNormalClose() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, String.class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            listener.onClose(mockWebSocket, 1000, "Normal closure");
+
+            CloseInfo closeInfo = connection.getCloseInfo();
+            assertNotNull(closeInfo);
+            assertEquals(1000, closeInfo.code());
+            assertEquals("Normal closure", closeInfo.reason());
+            assertTrue(closeInfo.isNormal());
+        }
+
+        @Test
+        @DisplayName("Should set close info on abnormal close")
+        void shouldSetCloseInfoOnAbnormalClose() {
+            JdkWebSocketConnection connection =
+                    new JdkWebSocketConnection<>(TEST_URL, String.class);
+            WebSocket mockWebSocket = mock(WebSocket.class);
+            connection.setWebSocket(mockWebSocket);
+            WebSocket.Listener listener = connection.getListener();
+
+            listener.onError(mockWebSocket, new RuntimeException("Connection lost"));
+
+            CloseInfo closeInfo = connection.getCloseInfo();
+            assertNotNull(closeInfo);
+            assertEquals(CloseInfo.ABNORMAL_CLOSURE, closeInfo.code());
+            assertFalse(closeInfo.isNormal());
+        }
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransportTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransportTest.java
new file mode 100644
index 000000000..bfb062da9
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/JdkWebSocketTransportTest.java
@@ -0,0 +1,474 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+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.model.transport.ProxyConfig;
+import io.agentscope.core.model.transport.ProxyType;
+import io.agentscope.core.model.transport.WebSocketTransport;
+import java.net.http.HttpClient;
+import java.time.Duration;
+import java.util.Set;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import reactor.test.StepVerifier;
+
+@DisplayName("JdkWebSocketTransport Tests")
+class JdkWebSocketTransportTest {
+
+    @Nested
+    @DisplayName("Basic Creation Tests")
+    class BasicCreationTests {
+
+        @Test
+        @DisplayName("Should create client with default config")
+        void shouldCreateClientWithDefaultConfig() {
+            WebSocketTransport client = JdkWebSocketTransport.create();
+
+            assertNotNull(client);
+        }
+
+        @Test
+        @DisplayName("Should create client with custom HttpClient")
+        void shouldCreateClientWithCustomHttpClient() {
+            HttpClient httpClient =
+                    HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(60)).build();
+
+            WebSocketTransport client = JdkWebSocketTransport.create(httpClient);
+
+            assertNotNull(client);
+        }
+
+        @Test
+        @DisplayName("Should build request with headers")
+        void shouldBuildRequestWithHeaders() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("wss://example.com")
+                            .header("Authorization", "Bearer token")
+                            .header("X-Custom", "value")
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .build();
+
+            assertEquals("wss://example.com", request.getUrl());
+            assertEquals("Bearer token", request.getHeaders().get("Authorization"));
+            assertEquals(Duration.ofSeconds(60), request.getConnectTimeout());
+        }
+
+        @Test
+        @DisplayName("Should handle shutdown gracefully")
+        void shouldHandleShutdownGracefully() {
+            WebSocketTransport client = JdkWebSocketTransport.create();
+
+            // Should not throw
+            client.shutdown();
+        }
+    }
+
+    @Nested
+    @DisplayName("Configuration Tests")
+    class ConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with basic config")
+        void shouldCreateClientWithBasicConfig() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with ignoreSsl config")
+        void shouldCreateClientWithIgnoreSslConfig() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with default config values")
+        void shouldCreateClientWithDefaultConfigValues() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.defaults();
+
+            assertEquals(Duration.ofSeconds(30), config.getConnectTimeout());
+            assertEquals(Duration.ZERO, config.getReadTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getWriteTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getPingInterval());
+            assertFalse(config.isIgnoreSsl());
+        }
+
+        @Test
+        @DisplayName("Should create client with all config values set")
+        void shouldCreateClientWithAllConfigValuesSet() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .readTimeout(Duration.ofSeconds(30))
+                            .writeTimeout(Duration.ofSeconds(45))
+                            .pingInterval(Duration.ofSeconds(20))
+                            .ignoreSsl(true)
+                            .build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+            assertEquals(Duration.ofSeconds(60), config.getConnectTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getReadTimeout());
+            assertEquals(Duration.ofSeconds(45), config.getWriteTimeout());
+            assertEquals(Duration.ofSeconds(20), config.getPingInterval());
+            assertTrue(config.isIgnoreSsl());
+        }
+    }
+
+    @Nested
+    @DisplayName("Proxy Configuration Tests")
+    class ProxyConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with simple HTTP proxy")
+        void shouldCreateClientWithSimpleHttpProxy() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with HTTP proxy with authentication")
+        void shouldCreateClientWithHttpProxyWithAuthentication() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.http("proxy.example.com", 8080, "user", "password");
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with SOCKS5 proxy")
+        void shouldCreateClientWithSocks5Proxy() {
+            ProxyConfig proxyConfig = ProxyConfig.socks5("socks.example.com", 1080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with SOCKS4 proxy")
+        void shouldCreateClientWithSocks4Proxy() {
+            ProxyConfig proxyConfig = ProxyConfig.socks4("socks.example.com", 1080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with proxy and nonProxyHosts")
+        void shouldCreateClientWithProxyAndNonProxyHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost", "*.internal.com"))
+                            .build();
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should bypass proxy for matching hosts")
+        void shouldBypassProxyForMatchingHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost", "*.internal.com", "192.168.*"))
+                            .build();
+
+            assertTrue(proxyConfig.shouldBypass("localhost"));
+            assertTrue(proxyConfig.shouldBypass("api.internal.com"));
+            assertTrue(proxyConfig.shouldBypass("192.168.1.1"));
+            assertFalse(proxyConfig.shouldBypass("example.com"));
+        }
+
+        @Test
+        @DisplayName("Should not bypass proxy for non-matching hosts")
+        void shouldNotBypassProxyForNonMatchingHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost"))
+                            .build();
+
+            assertFalse(proxyConfig.shouldBypass("example.com"));
+            assertFalse(proxyConfig.shouldBypass("api.example.com"));
+        }
+
+        @Test
+        @DisplayName("Should handle null nonProxyHosts")
+        void shouldHandleNullNonProxyHosts() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+
+            assertFalse(proxyConfig.shouldBypass("localhost"));
+            assertFalse(proxyConfig.shouldBypass("example.com"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Connection Tests")
+    class ConnectionTests {
+
+        @Test
+        @DisplayName("Should handle connection to non-existent server")
+        void shouldHandleConnectionToNonExistentServer() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("ws://localhost:59999/nonexistent")
+                            .connectTimeout(Duration.ofSeconds(2))
+                            .build();
+
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(2))
+                            .build();
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            StepVerifier.create(transport.connect(request, String.class))
+                    .expectError(WebSocketTransportException.class)
+                    .verify(Duration.ofSeconds(10));
+
+            transport.shutdown();
+        }
+
+        @Test
+        @DisplayName("Should handle connection with invalid URL")
+        void shouldHandleConnectionWithInvalidUrl() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("ws://invalid-host-that-does-not-exist:9999/ws")
+                            .connectTimeout(Duration.ofSeconds(2))
+                            .build();
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create();
+
+            StepVerifier.create(transport.connect(request, String.class))
+                    .expectError(WebSocketTransportException.class)
+                    .verify(Duration.ofSeconds(30));
+
+            transport.shutdown();
+        }
+
+        @Test
+        @DisplayName("Should include connect timeout in request")
+        void shouldIncludeConnectTimeoutInRequest() {
+            Duration customTimeout = Duration.ofSeconds(45);
+            WebSocketRequest request =
+                    WebSocketRequest.builder("ws://localhost:9999/ws")
+                            .connectTimeout(customTimeout)
+                            .build();
+
+            assertEquals(customTimeout, request.getConnectTimeout());
+        }
+
+        @Test
+        @DisplayName("Should include headers in request")
+        void shouldIncludeHeadersInRequest() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("ws://localhost:9999/ws")
+                            .header("Authorization", "Bearer token")
+                            .header("X-Custom", "value")
+                            .build();
+
+            assertEquals("Bearer token", request.getHeaders().get("Authorization"));
+            assertEquals("value", request.getHeaders().get("X-Custom"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Shutdown Tests")
+    class ShutdownTests {
+
+        @Test
+        @DisplayName("Should shutdown cleanly with no active connections")
+        void shouldShutdownCleanlyWithNoActiveConnections() {
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create();
+
+            // Should not throw
+            transport.shutdown();
+        }
+
+        @Test
+        @DisplayName("Should shutdown cleanly with config")
+        void shouldShutdownCleanlyWithConfig() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(30))
+                            .build();
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+
+            // Should not throw
+            transport.shutdown();
+        }
+    }
+
+    @Nested
+    @DisplayName("SSL Configuration Tests")
+    class SslConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with SSL verification enabled by default")
+        void shouldCreateClientWithSslVerificationEnabledByDefault() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.defaults();
+
+            assertFalse(config.isIgnoreSsl());
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with SSL verification disabled")
+        void shouldCreateClientWithSslVerificationDisabled() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).build();
+
+            assertTrue(config.isIgnoreSsl());
+
+            JdkWebSocketTransport transport = JdkWebSocketTransport.create(config);
+            assertNotNull(transport);
+        }
+    }
+
+    @Nested
+    @DisplayName("ProxyConfig Tests")
+    class ProxyConfigTests {
+
+        @Test
+        @DisplayName("Should detect authentication configured")
+        void shouldDetectAuthenticationConfigured() {
+            ProxyConfig withAuth = ProxyConfig.http("proxy.example.com", 8080, "user", "password");
+            ProxyConfig withoutAuth = ProxyConfig.http("proxy.example.com", 8080);
+            ProxyConfig emptyPassword =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .username("user")
+                            .password("")
+                            .build();
+            ProxyConfig nullPassword =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .username("user")
+                            .build();
+
+            assertTrue(withAuth.hasAuthentication());
+            assertFalse(withoutAuth.hasAuthentication());
+            assertFalse(emptyPassword.hasAuthentication());
+            assertFalse(nullPassword.hasAuthentication());
+        }
+
+        @Test
+        @DisplayName("Should get proxy configuration details")
+        void shouldGetProxyConfigurationDetails() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .username("user")
+                            .password("password")
+                            .nonProxyHosts(Set.of("localhost"))
+                            .build();
+
+            assertEquals(ProxyType.HTTP, proxyConfig.getType());
+            assertEquals("proxy.example.com", proxyConfig.getHost());
+            assertEquals(8080, proxyConfig.getPort());
+            assertEquals("user", proxyConfig.getUsername());
+            assertEquals("password", proxyConfig.getPassword());
+            assertNotNull(proxyConfig.getNonProxyHosts());
+            assertTrue(proxyConfig.getNonProxyHosts().contains("localhost"));
+        }
+
+        @Test
+        @DisplayName("Should get socket address from proxy config")
+        void shouldGetSocketAddressFromProxyConfig() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+
+            java.net.InetSocketAddress socketAddress = proxyConfig.getSocketAddress();
+
+            assertEquals("proxy.example.com", socketAddress.getHostString());
+            assertEquals(8080, socketAddress.getPort());
+        }
+
+        @Test
+        @DisplayName("Should convert to string correctly")
+        void shouldConvertToStringCorrectly() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.http("proxy.example.com", 8080, "user", "password");
+
+            String str = proxyConfig.toString();
+
+            assertTrue(str.contains("proxy.example.com"));
+            assertTrue(str.contains("8080"));
+            assertTrue(str.contains("user"));
+            assertTrue(str.contains("****")); // Password should be masked
+        }
+
+        @Test
+        @DisplayName("Should check equality correctly")
+        void shouldCheckEqualityCorrectly() {
+            ProxyConfig config1 = ProxyConfig.http("proxy.example.com", 8080);
+            ProxyConfig config2 = ProxyConfig.http("proxy.example.com", 8080);
+            ProxyConfig config3 = ProxyConfig.http("proxy.example.com", 8081);
+
+            assertEquals(config1, config2);
+            assertEquals(config1.hashCode(), config2.hashCode());
+            assertFalse(config1.equals(config3));
+        }
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnectionTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnectionTest.java
new file mode 100644
index 000000000..c75593664
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketConnectionTest.java
@@ -0,0 +1,207 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import okhttp3.WebSocket;
+import okio.ByteString;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import reactor.test.StepVerifier;
+
+@DisplayName("OkHttpWebSocketConnection Tests")
+class OkHttpWebSocketConnectionTest {
+
+    private static final String TEST_URL = "wss://example.com/ws";
+
+    @Nested
+    @DisplayName("Text Protocol Tests")
+    class TextProtocolTests {
+
+        private OkHttpWebSocketConnection connection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            connection = new OkHttpWebSocketConnection<>(TEST_URL, String.class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should not be open before WebSocket is set")
+        void shouldNotBeOpenBeforeWebSocketSet() {
+            assertFalse(connection.isOpen());
+            assertFalse(connection.isInitialized());
+        }
+
+        @Test
+        @DisplayName("Should be open after WebSocket is set")
+        void shouldBeOpenAfterWebSocketSet() {
+            connection.setWebSocket(mockWebSocket);
+
+            assertTrue(connection.isOpen());
+            assertTrue(connection.isInitialized());
+        }
+
+        @Test
+        @DisplayName("Should send text message successfully")
+        void shouldSendTextMessageSuccessfully() {
+            connection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.send(any(String.class))).thenReturn(true);
+
+            StepVerifier.create(connection.send("Hello")).verifyComplete();
+
+            verify(mockWebSocket).send("Hello");
+        }
+
+        @Test
+        @DisplayName("Should fail to send when connection is not open")
+        void shouldFailToSendWhenNotOpen() {
+            StepVerifier.create(connection.send("Hello"))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should fail to send when WebSocket returns false")
+        void shouldFailToSendWhenWebSocketReturnsFalse() {
+            connection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.send(any(String.class))).thenReturn(false);
+
+            StepVerifier.create(connection.send("Hello"))
+                    .expectError(WebSocketTransportException.class)
+                    .verify();
+        }
+
+        @Test
+        @DisplayName("Should receive text messages")
+        void shouldReceiveTextMessages() {
+            connection.setWebSocket(mockWebSocket);
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            connection.onMessage("Hello".getBytes(StandardCharsets.UTF_8));
+            connection.onMessage("World".getBytes(StandardCharsets.UTF_8));
+
+            assertEquals(2, received.size());
+            assertEquals("Hello", received.get(0));
+            assertEquals("World", received.get(1));
+        }
+
+        @Test
+        @DisplayName("Should handle close")
+        void shouldHandleClose() {
+            connection.setWebSocket(mockWebSocket);
+
+            connection.onClosed(CloseInfo.NORMAL_CLOSURE, "Normal closure");
+
+            assertFalse(connection.isOpen());
+            assertNotNull(connection.getCloseInfo());
+            assertEquals(CloseInfo.NORMAL_CLOSURE, connection.getCloseInfo().code());
+            assertEquals("Normal closure", connection.getCloseInfo().reason());
+        }
+
+        @Test
+        @DisplayName("Should handle error")
+        void shouldHandleError() {
+            connection.setWebSocket(mockWebSocket);
+
+            connection.onError(new RuntimeException("Test error"));
+
+            assertFalse(connection.isOpen());
+            assertNotNull(connection.getCloseInfo());
+            assertEquals(CloseInfo.ABNORMAL_CLOSURE, connection.getCloseInfo().code());
+        }
+
+        @Test
+        @DisplayName("Should close connection")
+        void shouldCloseConnection() {
+            connection.setWebSocket(mockWebSocket);
+
+            StepVerifier.create(connection.close()).verifyComplete();
+
+            assertFalse(connection.isOpen());
+            assertNotNull(connection.getCloseInfo());
+            assertEquals(CloseInfo.NORMAL_CLOSURE, connection.getCloseInfo().code());
+            verify(mockWebSocket).close(CloseInfo.NORMAL_CLOSURE, "");
+        }
+
+        @Test
+        @DisplayName("Should return null close info before close")
+        void shouldReturnNullCloseInfoBeforeClose() {
+            assertNull(connection.getCloseInfo());
+        }
+    }
+
+    @Nested
+    @DisplayName("Binary Protocol Tests")
+    class BinaryProtocolTests {
+
+        private OkHttpWebSocketConnection connection;
+        private WebSocket mockWebSocket;
+
+        @BeforeEach
+        void setUp() {
+            connection = new OkHttpWebSocketConnection<>(TEST_URL, byte[].class);
+            mockWebSocket = mock(WebSocket.class);
+        }
+
+        @Test
+        @DisplayName("Should send binary message successfully")
+        void shouldSendBinaryMessageSuccessfully() {
+            connection.setWebSocket(mockWebSocket);
+            when(mockWebSocket.send(any(ByteString.class))).thenReturn(true);
+
+            byte[] data = new byte[] {0x01, 0x02, 0x03};
+            StepVerifier.create(connection.send(data)).verifyComplete();
+
+            verify(mockWebSocket).send(ByteString.of(data));
+        }
+
+        @Test
+        @DisplayName("Should receive binary messages")
+        void shouldReceiveBinaryMessages() {
+            connection.setWebSocket(mockWebSocket);
+
+            List received = new ArrayList<>();
+            connection.receive().subscribe(received::add);
+
+            byte[] data1 = new byte[] {0x01, 0x02};
+            byte[] data2 = new byte[] {0x03, 0x04};
+            connection.onMessage(data1);
+            connection.onMessage(data2);
+
+            assertEquals(2, received.size());
+            assertEquals(2, received.get(0).length);
+            assertEquals(2, received.get(1).length);
+        }
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransportTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransportTest.java
new file mode 100644
index 000000000..6b29296f1
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/OkHttpWebSocketTransportTest.java
@@ -0,0 +1,511 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.agentscope.core.model.transport.ProxyConfig;
+import io.agentscope.core.model.transport.ProxyType;
+import io.agentscope.core.model.transport.WebSocketTransport;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.time.Duration;
+import java.util.Set;
+import java.util.concurrent.TimeUnit;
+import okhttp3.OkHttpClient;
+import okhttp3.Response;
+import okhttp3.WebSocket;
+import okhttp3.WebSocketListener;
+import okhttp3.mockwebserver.MockResponse;
+import okhttp3.mockwebserver.MockWebServer;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import reactor.test.StepVerifier;
+
+@DisplayName("OkHttpWebSocketTransport Tests")
+class OkHttpWebSocketTransportTest {
+
+    @Nested
+    @DisplayName("Basic Creation Tests")
+    class BasicCreationTests {
+
+        @Test
+        @DisplayName("Should create client with default config")
+        void shouldCreateClientWithDefaultConfig() {
+            WebSocketTransport client = OkHttpWebSocketTransport.create();
+
+            assertNotNull(client);
+        }
+
+        @Test
+        @DisplayName("Should create client with custom OkHttpClient")
+        void shouldCreateClientWithCustomOkHttpClient() {
+            OkHttpClient okHttpClient =
+                    new OkHttpClient.Builder()
+                            .connectTimeout(60, TimeUnit.SECONDS)
+                            .pingInterval(15, TimeUnit.SECONDS)
+                            .build();
+
+            WebSocketTransport client = OkHttpWebSocketTransport.create(okHttpClient);
+
+            assertNotNull(client);
+        }
+
+        @Test
+        @DisplayName("Should build request with headers")
+        void shouldBuildRequestWithHeaders() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("wss://example.com")
+                            .header("Authorization", "Bearer token")
+                            .header("X-Custom", "value")
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .build();
+
+            assertEquals("wss://example.com", request.getUrl());
+            assertEquals("Bearer token", request.getHeaders().get("Authorization"));
+            assertEquals("value", request.getHeaders().get("X-Custom"));
+            assertEquals(Duration.ofSeconds(60), request.getConnectTimeout());
+        }
+
+        @Test
+        @DisplayName("Should handle shutdown gracefully")
+        void shouldHandleShutdownGracefully() {
+            WebSocketTransport client = OkHttpWebSocketTransport.create();
+
+            // Should not throw
+            client.shutdown();
+        }
+    }
+
+    @Nested
+    @DisplayName("Configuration Tests")
+    class ConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with basic config")
+        void shouldCreateClientWithBasicConfig() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .readTimeout(Duration.ofSeconds(30))
+                            .writeTimeout(Duration.ofSeconds(45))
+                            .pingInterval(Duration.ofSeconds(20))
+                            .build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with ignoreSsl config")
+        void shouldCreateClientWithIgnoreSslConfig() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with default timeout values")
+        void shouldCreateClientWithDefaultTimeoutValues() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.defaults();
+
+            assertEquals(Duration.ofSeconds(30), config.getConnectTimeout());
+            assertEquals(Duration.ZERO, config.getReadTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getWriteTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getPingInterval());
+        }
+    }
+
+    @Nested
+    @DisplayName("Proxy Configuration Tests")
+    class ProxyConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with simple HTTP proxy")
+        void shouldCreateClientWithSimpleHttpProxy() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with HTTP proxy with authentication")
+        void shouldCreateClientWithHttpProxyWithAuthentication() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.http("proxy.example.com", 8080, "user", "password");
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with SOCKS5 proxy")
+        void shouldCreateClientWithSocks5Proxy() {
+            ProxyConfig proxyConfig = ProxyConfig.socks5("socks.example.com", 1080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with proxy and nonProxyHosts")
+        void shouldCreateClientWithProxyAndNonProxyHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost", "*.internal.com"))
+                            .build();
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should bypass proxy for matching hosts")
+        void shouldBypassProxyForMatchingHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost", "*.internal.com", "192.168.*"))
+                            .build();
+
+            assertTrue(proxyConfig.shouldBypass("localhost"));
+            assertTrue(proxyConfig.shouldBypass("api.internal.com"));
+            assertTrue(proxyConfig.shouldBypass("192.168.1.1"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Connection Tests")
+    class ConnectionTests {
+
+        @Test
+        @DisplayName("Should connect to WebSocket server successfully")
+        void shouldConnectToWebSocketServerSuccessfully() throws IOException {
+            MockWebServer server = new MockWebServer();
+            server.enqueue(
+                    new MockResponse()
+                            .withWebSocketUpgrade(
+                                    new WebSocketListener() {
+                                        @Override
+                                        public void onOpen(WebSocket webSocket, Response response) {
+                                            // Connection opened
+                                        }
+                                    }));
+            server.start();
+
+            try {
+                String wsUrl = server.url("/ws").toString().replace("http://", "ws://");
+                WebSocketRequest request = WebSocketRequest.builder(wsUrl).build();
+                OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+                StepVerifier.create(transport.connect(request, String.class))
+                        .assertNext(
+                                connection -> {
+                                    assertNotNull(connection);
+                                    assertTrue(connection.isOpen());
+                                })
+                        .verifyComplete();
+
+                transport.shutdown();
+            } finally {
+                server.shutdown();
+            }
+        }
+
+        @Test
+        @DisplayName("Should include headers in request")
+        void shouldIncludeHeadersInRequest() throws IOException, InterruptedException {
+            MockWebServer server = new MockWebServer();
+            server.enqueue(
+                    new MockResponse()
+                            .withWebSocketUpgrade(
+                                    new WebSocketListener() {
+                                        @Override
+                                        public void onOpen(WebSocket webSocket, Response response) {
+                                            // Connection opened
+                                        }
+                                    }));
+            server.start();
+
+            try {
+                String wsUrl = server.url("/ws").toString().replace("http://", "ws://");
+                WebSocketRequest request =
+                        WebSocketRequest.builder(wsUrl)
+                                .header("Authorization", "Bearer test-token")
+                                .header("X-Custom-Header", "custom-value")
+                                .build();
+                OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+                StepVerifier.create(transport.connect(request, String.class))
+                        .assertNext(
+                                connection -> {
+                                    assertNotNull(connection);
+                                })
+                        .verifyComplete();
+
+                // Verify headers were sent
+                var recordedRequest = server.takeRequest();
+                assertEquals("Bearer test-token", recordedRequest.getHeader("Authorization"));
+                assertEquals("custom-value", recordedRequest.getHeader("X-Custom-Header"));
+
+                transport.shutdown();
+            } finally {
+                server.shutdown();
+            }
+        }
+
+        @Test
+        @DisplayName("Should handle connection failure")
+        void shouldHandleConnectionFailure() throws IOException {
+            MockWebServer server = new MockWebServer();
+            server.enqueue(new MockResponse().setResponseCode(404));
+            server.start();
+
+            try {
+                String wsUrl = server.url("/ws").toString().replace("http://", "ws://");
+                WebSocketRequest request = WebSocketRequest.builder(wsUrl).build();
+                OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+                StepVerifier.create(transport.connect(request, String.class))
+                        .expectError(WebSocketTransportException.class)
+                        .verify(Duration.ofSeconds(10));
+
+                transport.shutdown();
+            } finally {
+                server.shutdown();
+            }
+        }
+
+        @Test
+        @DisplayName("Should handle connection to non-existent server")
+        void shouldHandleConnectionToNonExistentServer() {
+            WebSocketRequest request =
+                    WebSocketRequest.builder("ws://localhost:59999/nonexistent")
+                            .connectTimeout(Duration.ofSeconds(2))
+                            .build();
+
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(2))
+                            .build();
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+
+            StepVerifier.create(transport.connect(request, String.class))
+                    .expectError(WebSocketTransportException.class)
+                    .verify(Duration.ofSeconds(10));
+
+            transport.shutdown();
+        }
+    }
+
+    @Nested
+    @DisplayName("Send and Receive Tests")
+    class SendAndReceiveTests {
+
+        @Test
+        @DisplayName("Should send and receive text messages")
+        void shouldSendAndReceiveTextMessages() throws IOException {
+            MockWebServer server = new MockWebServer();
+            server.enqueue(
+                    new MockResponse()
+                            .withWebSocketUpgrade(
+                                    new WebSocketListener() {
+                                        @Override
+                                        public void onOpen(WebSocket webSocket, Response response) {
+                                            // Echo server
+                                        }
+
+                                        @Override
+                                        public void onMessage(WebSocket webSocket, String text) {
+                                            webSocket.send("Echo: " + text);
+                                        }
+                                    }));
+            server.start();
+
+            try {
+                String wsUrl = server.url("/ws").toString().replace("http://", "ws://");
+                WebSocketRequest request = WebSocketRequest.builder(wsUrl).build();
+                OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+                StepVerifier.create(
+                                transport
+                                        .connect(request, String.class)
+                                        .flatMapMany(
+                                                connection -> {
+                                                    connection.send("Hello").subscribe();
+                                                    return connection.receive().take(1);
+                                                }))
+                        .assertNext(
+                                message -> {
+                                    assertEquals("Echo: Hello", message);
+                                })
+                        .verifyComplete();
+
+                transport.shutdown();
+            } finally {
+                server.shutdown();
+            }
+        }
+    }
+
+    @Nested
+    @DisplayName("Shutdown Tests")
+    class ShutdownTests {
+
+        @Test
+        @DisplayName("Should shutdown cleanly with no active connections")
+        void shouldShutdownCleanlyWithNoActiveConnections() {
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+            // Should not throw
+            transport.shutdown();
+        }
+
+        @Test
+        @DisplayName("Should shutdown after connection was established")
+        void shouldShutdownAfterConnectionWasEstablished() throws IOException {
+            MockWebServer server = new MockWebServer();
+            server.enqueue(
+                    new MockResponse()
+                            .withWebSocketUpgrade(
+                                    new WebSocketListener() {
+                                        @Override
+                                        public void onOpen(WebSocket webSocket, Response response) {
+                                            // Connection opened
+                                        }
+                                    }));
+            server.start();
+
+            try {
+                String wsUrl = server.url("/ws").toString().replace("http://", "ws://");
+                WebSocketRequest request = WebSocketRequest.builder(wsUrl).build();
+                OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create();
+
+                WebSocketConnection connection =
+                        transport.connect(request, String.class).block(Duration.ofSeconds(5));
+                assertNotNull(connection);
+
+                // Should not throw
+                transport.shutdown();
+            } finally {
+                server.shutdown();
+            }
+        }
+    }
+
+    @Nested
+    @DisplayName("SSL Configuration Tests")
+    class SslConfigurationTests {
+
+        @Test
+        @DisplayName("Should create client with SSL verification enabled by default")
+        void shouldCreateClientWithSslVerificationEnabledByDefault() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.defaults();
+
+            assertEquals(false, config.isIgnoreSsl());
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+            assertNotNull(transport);
+        }
+
+        @Test
+        @DisplayName("Should create client with SSL verification disabled")
+        void shouldCreateClientWithSslVerificationDisabled() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).build();
+
+            assertEquals(true, config.isIgnoreSsl());
+
+            OkHttpWebSocketTransport transport = OkHttpWebSocketTransport.create(config);
+            assertNotNull(transport);
+        }
+    }
+
+    @Nested
+    @DisplayName("ProxyConfig Integration Tests")
+    class ProxyConfigIntegrationTests {
+
+        @Test
+        @DisplayName("Should create Java Proxy from HTTP ProxyConfig")
+        void shouldCreateJavaProxyFromHttpProxyConfig() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+
+            java.net.Proxy javaProxy = proxyConfig.toJavaProxy();
+
+            assertEquals(java.net.Proxy.Type.HTTP, javaProxy.type());
+            InetSocketAddress address = (InetSocketAddress) javaProxy.address();
+            assertEquals("proxy.example.com", address.getHostString());
+            assertEquals(8080, address.getPort());
+        }
+
+        @Test
+        @DisplayName("Should create Java Proxy from SOCKS5 ProxyConfig")
+        void shouldCreateJavaProxyFromSocks5ProxyConfig() {
+            ProxyConfig proxyConfig = ProxyConfig.socks5("socks.example.com", 1080);
+
+            java.net.Proxy javaProxy = proxyConfig.toJavaProxy();
+
+            assertEquals(java.net.Proxy.Type.SOCKS, javaProxy.type());
+            InetSocketAddress address = (InetSocketAddress) javaProxy.address();
+            assertEquals("socks.example.com", address.getHostString());
+            assertEquals(1080, address.getPort());
+        }
+
+        @Test
+        @DisplayName("Should detect authentication configured")
+        void shouldDetectAuthenticationConfigured() {
+            ProxyConfig withAuth = ProxyConfig.http("proxy.example.com", 8080, "user", "password");
+            ProxyConfig withoutAuth = ProxyConfig.http("proxy.example.com", 8080);
+            ProxyConfig emptyPassword =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .username("user")
+                            .password("")
+                            .build();
+
+            assertTrue(withAuth.hasAuthentication());
+            assertTrue(!withoutAuth.hasAuthentication());
+            assertTrue(!emptyPassword.hasAuthentication());
+        }
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketRequestTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketRequestTest.java
new file mode 100644
index 000000000..a0ea3a2e0
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketRequestTest.java
@@ -0,0 +1,86 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.time.Duration;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("WebSocketRequest Tests")
+class WebSocketRequestTest {
+
+    @Test
+    @DisplayName("Should build request with url")
+    void shouldBuildRequestWithUrl() {
+        WebSocketRequest request = WebSocketRequest.builder("wss://example.com").build();
+
+        assertEquals("wss://example.com", request.getUrl());
+        assertTrue(request.getHeaders().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should build request with headers")
+    void shouldBuildRequestWithHeaders() {
+        WebSocketRequest request =
+                WebSocketRequest.builder("wss://example.com")
+                        .header("Authorization", "Bearer token")
+                        .header("X-Custom", "value")
+                        .build();
+
+        assertEquals("Bearer token", request.getHeaders().get("Authorization"));
+        assertEquals("value", request.getHeaders().get("X-Custom"));
+    }
+
+    @Test
+    @DisplayName("Should build request with timeout")
+    void shouldBuildRequestWithTimeout() {
+        WebSocketRequest request =
+                WebSocketRequest.builder("wss://example.com")
+                        .connectTimeout(Duration.ofSeconds(60))
+                        .build();
+
+        assertEquals(Duration.ofSeconds(60), request.getConnectTimeout());
+    }
+
+    @Test
+    @DisplayName("Should have default timeout")
+    void shouldHaveDefaultTimeout() {
+        WebSocketRequest request = WebSocketRequest.builder("wss://example.com").build();
+
+        assertEquals(Duration.ofSeconds(30), request.getConnectTimeout());
+    }
+
+    @Test
+    @DisplayName("Headers should be immutable")
+    void headersShouldBeImmutable() {
+        WebSocketRequest request =
+                WebSocketRequest.builder("wss://example.com").header("Key", "Value").build();
+
+        assertThrows(
+                UnsupportedOperationException.class,
+                () -> request.getHeaders().put("New", "Value"));
+    }
+
+    @Test
+    @DisplayName("Should throw exception when url is null")
+    void shouldThrowExceptionWhenUrlIsNull() {
+        assertThrows(NullPointerException.class, () -> WebSocketRequest.builder(null));
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfigTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfigTest.java
new file mode 100644
index 000000000..b84ffa0b5
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportConfigTest.java
@@ -0,0 +1,289 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.agentscope.core.model.transport.ProxyConfig;
+import io.agentscope.core.model.transport.ProxyType;
+import java.time.Duration;
+import java.util.Set;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("WebSocketTransportConfig Tests")
+class WebSocketTransportConfigTest {
+
+    @Nested
+    @DisplayName("Default Configuration Tests")
+    class DefaultConfigurationTests {
+
+        @Test
+        @DisplayName("Should have correct default values")
+        void shouldHaveCorrectDefaultValues() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.defaults();
+
+            assertEquals(Duration.ofSeconds(30), config.getConnectTimeout());
+            assertEquals(Duration.ZERO, config.getReadTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getWriteTimeout());
+            assertEquals(Duration.ofSeconds(30), config.getPingInterval());
+            assertNull(config.getProxyConfig());
+            assertFalse(config.isIgnoreSsl());
+        }
+
+        @Test
+        @DisplayName("Should have correct default constant values")
+        void shouldHaveCorrectDefaultConstantValues() {
+            assertEquals(Duration.ofSeconds(30), WebSocketTransportConfig.DEFAULT_CONNECT_TIMEOUT);
+            assertEquals(Duration.ZERO, WebSocketTransportConfig.DEFAULT_READ_TIMEOUT);
+            assertEquals(Duration.ofSeconds(30), WebSocketTransportConfig.DEFAULT_WRITE_TIMEOUT);
+            assertEquals(Duration.ofSeconds(30), WebSocketTransportConfig.DEFAULT_PING_INTERVAL);
+        }
+
+        @Test
+        @DisplayName("Builder should use defaults when not specified")
+        void builderShouldUseDefaultsWhenNotSpecified() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.builder().build();
+
+            assertEquals(
+                    WebSocketTransportConfig.DEFAULT_CONNECT_TIMEOUT, config.getConnectTimeout());
+            assertEquals(WebSocketTransportConfig.DEFAULT_READ_TIMEOUT, config.getReadTimeout());
+            assertEquals(WebSocketTransportConfig.DEFAULT_WRITE_TIMEOUT, config.getWriteTimeout());
+            assertEquals(WebSocketTransportConfig.DEFAULT_PING_INTERVAL, config.getPingInterval());
+            assertFalse(config.isIgnoreSsl());
+            assertNull(config.getProxyConfig());
+        }
+    }
+
+    @Nested
+    @DisplayName("Builder Tests")
+    class BuilderTests {
+
+        @Test
+        @DisplayName("Should build with custom values")
+        void shouldBuildWithCustomValues() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofSeconds(60))
+                            .readTimeout(Duration.ofSeconds(120))
+                            .writeTimeout(Duration.ofSeconds(45))
+                            .pingInterval(Duration.ofSeconds(15))
+                            .ignoreSsl(true)
+                            .build();
+
+            assertEquals(Duration.ofSeconds(60), config.getConnectTimeout());
+            assertEquals(Duration.ofSeconds(120), config.getReadTimeout());
+            assertEquals(Duration.ofSeconds(45), config.getWriteTimeout());
+            assertEquals(Duration.ofSeconds(15), config.getPingInterval());
+            assertTrue(config.isIgnoreSsl());
+        }
+
+        @Test
+        @DisplayName("Should support builder chaining")
+        void shouldSupportBuilderChaining() {
+            WebSocketTransportConfig.Builder builder = WebSocketTransportConfig.builder();
+
+            // Verify each method returns the same builder instance
+            assertSame(builder, builder.connectTimeout(Duration.ofSeconds(10)));
+            assertSame(builder, builder.readTimeout(Duration.ofSeconds(20)));
+            assertSame(builder, builder.writeTimeout(Duration.ofSeconds(30)));
+            assertSame(builder, builder.pingInterval(Duration.ofSeconds(40)));
+            assertSame(builder, builder.ignoreSsl(true));
+            assertSame(builder, builder.proxy(null));
+        }
+
+        @Test
+        @DisplayName("Should build with proxy config")
+        void shouldBuildWithProxyConfig() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertEquals("proxy.example.com", config.getProxyConfig().getHost());
+            assertEquals(8080, config.getProxyConfig().getPort());
+        }
+
+        @Test
+        @DisplayName("Should build with proxy and authentication")
+        void shouldBuildWithProxyAndAuthentication() {
+            ProxyConfig proxyConfig = ProxyConfig.socks5("socks.example.com", 1080, "user", "pass");
+
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertEquals("socks.example.com", config.getProxyConfig().getHost());
+            assertEquals(1080, config.getProxyConfig().getPort());
+            assertTrue(config.getProxyConfig().hasAuthentication());
+        }
+
+        @Test
+        @DisplayName("Should build with null proxy")
+        void shouldBuildWithNullProxy() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(null).build();
+
+            assertNull(config.getProxyConfig());
+        }
+
+        @Test
+        @DisplayName("Should build with ignoreSsl false by default")
+        void shouldBuildWithIgnoreSslFalseByDefault() {
+            WebSocketTransportConfig config = WebSocketTransportConfig.builder().build();
+
+            assertFalse(config.isIgnoreSsl());
+        }
+
+        @Test
+        @DisplayName("Should override ignoreSsl when set to true")
+        void shouldOverrideIgnoreSslWhenSetToTrue() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).build();
+
+            assertTrue(config.isIgnoreSsl());
+        }
+
+        @Test
+        @DisplayName("Should allow setting ignoreSsl back to false")
+        void shouldAllowSettingIgnoreSslBackToFalse() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().ignoreSsl(true).ignoreSsl(false).build();
+
+            assertFalse(config.isIgnoreSsl());
+        }
+    }
+
+    @Nested
+    @DisplayName("Proxy Configuration Tests")
+    class ProxyConfigurationTests {
+
+        @Test
+        @DisplayName("Should support HTTP proxy")
+        void shouldSupportHttpProxy() {
+            ProxyConfig proxyConfig = ProxyConfig.http("proxy.example.com", 8080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertEquals(ProxyType.HTTP, config.getProxyConfig().getType());
+        }
+
+        @Test
+        @DisplayName("Should support SOCKS4 proxy")
+        void shouldSupportSocks4Proxy() {
+            ProxyConfig proxyConfig = ProxyConfig.socks4("socks.example.com", 1080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertEquals(ProxyType.SOCKS4, config.getProxyConfig().getType());
+        }
+
+        @Test
+        @DisplayName("Should support SOCKS5 proxy")
+        void shouldSupportSocks5Proxy() {
+            ProxyConfig proxyConfig = ProxyConfig.socks5("socks.example.com", 1080);
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertEquals(ProxyType.SOCKS5, config.getProxyConfig().getType());
+        }
+
+        @Test
+        @DisplayName("Should support proxy with nonProxyHosts")
+        void shouldSupportProxyWithNonProxyHosts() {
+            ProxyConfig proxyConfig =
+                    ProxyConfig.builder()
+                            .type(ProxyType.HTTP)
+                            .host("proxy.example.com")
+                            .port(8080)
+                            .nonProxyHosts(Set.of("localhost", "*.internal.com"))
+                            .build();
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder().proxy(proxyConfig).build();
+
+            assertNotNull(config.getProxyConfig());
+            assertNotNull(config.getProxyConfig().getNonProxyHosts());
+            assertTrue(config.getProxyConfig().getNonProxyHosts().contains("localhost"));
+            assertTrue(config.getProxyConfig().getNonProxyHosts().contains("*.internal.com"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Timeout Configuration Tests")
+    class TimeoutConfigurationTests {
+
+        @Test
+        @DisplayName("Should support zero timeout")
+        void shouldSupportZeroTimeout() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ZERO)
+                            .readTimeout(Duration.ZERO)
+                            .writeTimeout(Duration.ZERO)
+                            .pingInterval(Duration.ZERO)
+                            .build();
+
+            assertEquals(Duration.ZERO, config.getConnectTimeout());
+            assertEquals(Duration.ZERO, config.getReadTimeout());
+            assertEquals(Duration.ZERO, config.getWriteTimeout());
+            assertEquals(Duration.ZERO, config.getPingInterval());
+        }
+
+        @Test
+        @DisplayName("Should support large timeout values")
+        void shouldSupportLargeTimeoutValues() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofMinutes(10))
+                            .readTimeout(Duration.ofHours(1))
+                            .writeTimeout(Duration.ofMinutes(5))
+                            .pingInterval(Duration.ofMinutes(2))
+                            .build();
+
+            assertEquals(Duration.ofMinutes(10), config.getConnectTimeout());
+            assertEquals(Duration.ofHours(1), config.getReadTimeout());
+            assertEquals(Duration.ofMinutes(5), config.getWriteTimeout());
+            assertEquals(Duration.ofMinutes(2), config.getPingInterval());
+        }
+
+        @Test
+        @DisplayName("Should support millisecond precision")
+        void shouldSupportMillisecondPrecision() {
+            WebSocketTransportConfig config =
+                    WebSocketTransportConfig.builder()
+                            .connectTimeout(Duration.ofMillis(1500))
+                            .readTimeout(Duration.ofMillis(2500))
+                            .writeTimeout(Duration.ofMillis(3500))
+                            .pingInterval(Duration.ofMillis(4500))
+                            .build();
+
+            assertEquals(Duration.ofMillis(1500), config.getConnectTimeout());
+            assertEquals(Duration.ofMillis(2500), config.getReadTimeout());
+            assertEquals(Duration.ofMillis(3500), config.getWriteTimeout());
+            assertEquals(Duration.ofMillis(4500), config.getPingInterval());
+        }
+    }
+}
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportExceptionTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportExceptionTest.java
new file mode 100644
index 000000000..835d9edae
--- /dev/null
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/transport/websocket/WebSocketTransportExceptionTest.java
@@ -0,0 +1,298 @@
+/*
+ * 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
+ *
+ *      https://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.model.transport.websocket;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.util.Map;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("WebSocketTransportException Tests")
+class WebSocketTransportExceptionTest {
+
+    @Nested
+    @DisplayName("Constructor Tests")
+    class ConstructorTests {
+
+        @Test
+        @DisplayName("Should create exception with basic info")
+        void shouldCreateExceptionWithBasicInfo() {
+            IOException cause = new IOException("Connection refused");
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Failed to connect", cause, "wss://example.com", "CONNECTING");
+
+            assertEquals("wss://example.com", exception.getUrl());
+            assertEquals("CONNECTING", exception.getConnectionState());
+            assertSame(cause, exception.getCause());
+            assertTrue(exception.getHeaders().isEmpty());
+        }
+
+        @Test
+        @DisplayName("Should create exception with headers")
+        void shouldCreateExceptionWithHeaders() {
+            Map headers = Map.of("Authorization", "Bearer token");
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Auth failed", null, "wss://example.com", "CONNECTING", headers);
+
+            assertEquals("Bearer token", exception.getHeaders().get("Authorization"));
+        }
+
+        @Test
+        @DisplayName("Should create exception with null cause")
+        void shouldCreateExceptionWithNullCause() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error occurred", null, "wss://example.com", "OPEN");
+
+            assertNull(exception.getCause());
+            assertEquals("wss://example.com", exception.getUrl());
+            assertEquals("OPEN", exception.getConnectionState());
+        }
+
+        @Test
+        @DisplayName("Should create exception with null headers")
+        void shouldCreateExceptionWithNullHeaders() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com", "CLOSED", null);
+
+            assertTrue(exception.getHeaders().isEmpty());
+        }
+
+        @Test
+        @DisplayName("Should create exception with empty headers")
+        void shouldCreateExceptionWithEmptyHeaders() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com", "CLOSED", Map.of());
+
+            assertTrue(exception.getHeaders().isEmpty());
+            assertNotNull(exception.getHeaders());
+        }
+
+        @Test
+        @DisplayName("Should create exception with multiple headers")
+        void shouldCreateExceptionWithMultipleHeaders() {
+            Map headers =
+                    Map.of(
+                            "Authorization", "Bearer token",
+                            "X-Custom-Header", "value",
+                            "Content-Type", "application/json");
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com", "OPEN", headers);
+
+            assertEquals(3, exception.getHeaders().size());
+            assertEquals("Bearer token", exception.getHeaders().get("Authorization"));
+            assertEquals("value", exception.getHeaders().get("X-Custom-Header"));
+            assertEquals("application/json", exception.getHeaders().get("Content-Type"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Message Formatting Tests")
+    class MessageFormattingTests {
+
+        @Test
+        @DisplayName("Should format message with context")
+        void shouldFormatMessageWithContext() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Send failed", null, "wss://api.example.com/ws", "OPEN");
+
+            String message = exception.getMessage();
+            assertTrue(message.contains("Send failed"));
+            assertTrue(message.contains("wss://api.example.com/ws"));
+            assertTrue(message.contains("OPEN"));
+        }
+
+        @Test
+        @DisplayName("Should format message with CONNECTING state")
+        void shouldFormatMessageWithConnectingState() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Connection timeout", null, "wss://example.com", "CONNECTING");
+
+            String message = exception.getMessage();
+            assertTrue(message.contains("Connection timeout"));
+            assertTrue(message.contains("CONNECTING"));
+        }
+
+        @Test
+        @DisplayName("Should format message with CLOSED state")
+        void shouldFormatMessageWithClosedState() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Already closed", null, "wss://example.com", "CLOSED");
+
+            String message = exception.getMessage();
+            assertTrue(message.contains("Already closed"));
+            assertTrue(message.contains("CLOSED"));
+        }
+
+        @Test
+        @DisplayName("Should format message with null URL")
+        void shouldFormatMessageWithNullUrl() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException("Error", null, null, "OPEN");
+
+            String message = exception.getMessage();
+            assertNotNull(message);
+            assertTrue(message.contains("Error"));
+            assertTrue(message.contains("null"));
+        }
+
+        @Test
+        @DisplayName("Should format message with null state")
+        void shouldFormatMessageWithNullState() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException("Error", null, "wss://example.com", null);
+
+            String message = exception.getMessage();
+            assertNotNull(message);
+            assertTrue(message.contains("Error"));
+            assertTrue(message.contains("wss://example.com"));
+        }
+
+        @Test
+        @DisplayName("Should format message with special characters in URL")
+        void shouldFormatMessageWithSpecialCharactersInUrl() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com/path?query=value&other=123", "OPEN");
+
+            String message = exception.getMessage();
+            assertTrue(message.contains("wss://example.com/path?query=value&other=123"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Immutability Tests")
+    class ImmutabilityTests {
+
+        @Test
+        @DisplayName("Headers should be immutable")
+        void headersShouldBeImmutable() {
+            Map headers = Map.of("Key", "Value");
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com", "CLOSED", headers);
+
+            Map returnedHeaders = exception.getHeaders();
+            assertEquals(1, returnedHeaders.size());
+
+            // Attempt to modify should throw exception
+            assertThrows(
+                    UnsupportedOperationException.class,
+                    () -> returnedHeaders.put("New", "Header"));
+        }
+
+        @Test
+        @DisplayName("Exception fields should be accessible after creation")
+        void exceptionFieldsShouldBeAccessibleAfterCreation() {
+            IOException cause = new IOException("Network error");
+            Map headers = Map.of("Auth", "Bearer xyz");
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Connection lost", cause, "wss://api.test.com", "OPEN", headers);
+
+            // Verify all fields are accessible
+            assertEquals("wss://api.test.com", exception.getUrl());
+            assertEquals("OPEN", exception.getConnectionState());
+            assertSame(cause, exception.getCause());
+            assertEquals("Bearer xyz", exception.getHeaders().get("Auth"));
+            assertTrue(exception.getMessage().contains("Connection lost"));
+        }
+    }
+
+    @Nested
+    @DisplayName("Exception Hierarchy Tests")
+    class ExceptionHierarchyTests {
+
+        @Test
+        @DisplayName("Should be a RuntimeException")
+        void shouldBeARuntimeException() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException("Error", null, "wss://example.com", "OPEN");
+
+            assertTrue(exception instanceof RuntimeException);
+        }
+
+        @Test
+        @DisplayName("Should preserve exception chain")
+        void shouldPreserveExceptionChain() {
+            IOException rootCause = new IOException("Network unreachable");
+            RuntimeException intermediateCause =
+                    new RuntimeException("Connection failed", rootCause);
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Transport error",
+                            intermediateCause,
+                            "wss://example.com",
+                            "CONNECTING");
+
+            assertSame(intermediateCause, exception.getCause());
+            assertSame(rootCause, exception.getCause().getCause());
+        }
+    }
+
+    @Nested
+    @DisplayName("Edge Cases Tests")
+    class EdgeCasesTests {
+
+        @Test
+        @DisplayName("Should handle empty message")
+        void shouldHandleEmptyMessage() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException("", null, "wss://example.com", "OPEN");
+
+            assertNotNull(exception.getMessage());
+            assertTrue(exception.getMessage().contains("wss://example.com"));
+        }
+
+        @Test
+        @DisplayName("Should handle very long URL")
+        void shouldHandleVeryLongUrl() {
+            String longUrl = "wss://example.com/" + "a".repeat(1000);
+            WebSocketTransportException exception =
+                    new WebSocketTransportException("Error", null, longUrl, "OPEN");
+
+            assertTrue(exception.getUrl().length() > 1000);
+            assertTrue(exception.getMessage().contains(longUrl));
+        }
+
+        @Test
+        @DisplayName("Should handle custom connection state")
+        void shouldHandleCustomConnectionState() {
+            WebSocketTransportException exception =
+                    new WebSocketTransportException(
+                            "Error", null, "wss://example.com", "CUSTOM_STATE");
+
+            assertEquals("CUSTOM_STATE", exception.getConnectionState());
+            assertTrue(exception.getMessage().contains("CUSTOM_STATE"));
+        }
+    }
+}

From 766bae57732136dcd942b76eb59d464fa59cf511 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=90=A7=E8=BD=A9miss?= 
Date: Fri, 16 Jan 2026 13:49:24 +0800
Subject: [PATCH 15/53] feat: support metadata recording and filtering for Mem0
 (#563)

## 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)]

$ mvn dependency:tree | grep agentscope-parent:pom
[INFO] io.agentscope:agentscope-parent:pom:1.0.8-SNAPSHOT

## Description

[Please describe the background, purpose, changes made, and how to test
this PR]
Feat [#561
](https://github.com/agentscope-ai/agentscope-java/issues/561)


## Checklist

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

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 .../examples/advanced/Mem0Example.java        |   8 +-
 .../core/memory/mem0/Mem0LongTermMemory.java  | 104 ++++++++++++++++--
 .../core/memory/mem0/Mem0SearchRequest.java   |   4 +
 3 files changed, 102 insertions(+), 14 deletions(-)

diff --git a/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java b/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java
index 79872fa61..c64a8bbad 100644
--- a/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java
+++ b/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java
@@ -22,6 +22,8 @@
 import io.agentscope.core.memory.mem0.Mem0LongTermMemory;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.model.DashScopeChatModel;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * Mem0Example - Demonstrates long-term memory using Mem0 backend.
@@ -33,14 +35,16 @@ public static void main(String[] args) throws Exception {
         String dashscopeApiKey = ExampleUtils.getDashScopeApiKey();
         String mem0BaseUrl = getMem0BaseUrl();
         Mem0ApiType mem0ApiType = getMem0ApiType();
-
+        Map metadata = new HashMap<>();
+        metadata.put("agentName", "SmartAssistant");
         Mem0LongTermMemory.Builder memoryBuilder =
                 Mem0LongTermMemory.builder()
                         .agentName("SmartAssistant")
                         .userId("static-control01126")
                         .apiBaseUrl(mem0BaseUrl)
                         .apiKey(System.getenv("MEM0_API_KEY"))
-                        .apiType(mem0ApiType);
+                        .apiType(mem0ApiType)
+                        .metadata(metadata);
 
         Mem0LongTermMemory longTermMemory = memoryBuilder.build();
 
diff --git a/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0LongTermMemory.java b/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0LongTermMemory.java
index c89ba6ca2..cb623252b 100644
--- a/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0LongTermMemory.java
+++ b/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0LongTermMemory.java
@@ -18,6 +18,7 @@
 import io.agentscope.core.memory.LongTermMemory;
 import io.agentscope.core.message.Msg;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.stream.Collectors;
 import reactor.core.publisher.Mono;
@@ -34,6 +35,7 @@
  *   
  • Semantic memory search using vector embeddings
  *   
  • LLM-powered memory extraction and inference
  *   
  • Multi-tenant memory isolation (agent, user, run)
+ *   
  • Custom metadata support for tagging and filtering memories
  *   
  • Automatic fallback mechanisms to ensure reliable memory storage
  *   
  • Reactive, non-blocking operations
  * 
@@ -44,6 +46,7 @@
  *   
  • agentId: Identifies the agent (optional)
    • 
  *   
  • userId: Identifies the user/workspace (optional)
    • 
  *   
  • runId: Identifies the session/run (optional)
    • 
+ *   
  • metadata: Custom key-value pairs for additional filtering (optional)
    • 
  * 
  * At least one identifier is required. During retrieval, only memories with matching
  * metadata are returned.
@@ -53,7 +56,7 @@
  * // Create memory instance with authentication
  * Mem0LongTermMemory memory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .apiKey(System.getenv("MEM0_API_KEY"))
  *     .build();
@@ -61,19 +64,31 @@
  * // For local deployments without authentication
  * Mem0LongTermMemory localMemory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .build();
  *
  * // For self-hosted Mem0
  * Mem0LongTermMemory selfHostedMemory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .apiType(Mem0ApiType.SELF_HOSTED)  // Specify self-hosted API type
  *     .build();
  *
- * // Record a message
+ * // With custom metadata for filtering
+ * Map metadata = new HashMap<>();
+ * metadata.put("category", "travel");
+ * metadata.put("project_id", "proj_001");
+ *
+ * Mem0LongTermMemory memoryWithMetadata = Mem0LongTermMemory.builder()
+ *     .agentName("Assistant")
+ *     .userId("user_123")
+ *     .apiBaseUrl("http://localhost:8000")
+ *     .metadata(metadata)  // Custom metadata for storage and filtering
+ *     .build();
+ *
+ * // Record a message (metadata will be stored with the memory)
  * Msg msg = Msg.builder()
  *     .role(MsgRole.USER)
  *     .content("I prefer homestays when traveling")
@@ -81,7 +96,7 @@
  *
  * memory.record(List.of(msg)).block();
  *
- * // Retrieve relevant memories
+ * // Retrieve relevant memories (metadata will be used as filter)
  * Msg query = Msg.builder()
  *     .role(MsgRole.USER)
  *     .content("What are my travel preferences?")
@@ -101,6 +116,24 @@ public class Mem0LongTermMemory implements LongTermMemory {
     private final String userId;
     private final String runId;
 
+    /**
+     * Custom metadata to be stored with memories and used for filtering during retrieval.
+     *
+     * 
    This metadata is:
+     * 
      
+     *   
    • Included in the {@code metadata} field when recording memories via {@link #record(List)}
      • 
+     *   
    • Added to the {@code filters} field when retrieving memories via {@link #retrieve(Msg)}
      • 
+     * 
    
+     *
+     * 
    Use cases include:
+     * 
      
+     *   
    • Tagging memories with custom labels (e.g., "category": "travel")
      • 
+     *   
    • Filtering memories by project, tenant, or other business attributes
      • 
+     *   
    • Storing additional context that should be associated with all memories
      • 
+     * 
    
+     */
+    private final Map metadata;
+
     /**
      * Private constructor - use Builder instead.
      */
@@ -110,6 +143,7 @@ private Mem0LongTermMemory(Builder builder) {
         this.agentId = builder.agentName;
         this.userId = builder.userId;
         this.runId = builder.runName;
+        this.metadata = builder.metadata;
 
         // Validate that at least one identifier is provided
         if (agentId == null && userId == null && runId == null) {
@@ -161,6 +195,7 @@ public Mono record(List msgs) {
                         .agentId(agentId)
                         .userId(userId)
                         .runId(runId)
+                        .metadata(metadata)
                         .infer(true)
                         .build();
 
@@ -191,17 +226,30 @@ private Mem0Message convertToMem0Message(Msg msg) {
     /**
      * Builds a search request with the given query.
      *
+     * 
    The search request includes:
+     * 
      
+     *   
    • Standard filters: userId, agentId, runId (added by builder convenience methods)
      • 
+     *   
    • Custom metadata filters: merged into filters via builder.getFilters()
      • 
+     * 
    
+     *
      * @param query The search query string
      * @return A configured Mem0SearchRequest for v2 API
      */
     private Mem0SearchRequest buildSearchRequest(String query) {
-        return Mem0SearchRequest.builder()
-                .query(query)
-                .userId(userId)
-                .agentId(agentId)
-                .runId(runId)
-                .topK(5)
-                .build();
+        Mem0SearchRequest.Builder builder =
+                Mem0SearchRequest.builder()
+                        .query(query)
+                        .userId(userId)
+                        .agentId(agentId)
+                        .runId(runId)
+                        .topK(5);
+
+        // Merge custom metadata into filters if present
+        if (metadata != null && !metadata.isEmpty()) {
+            builder.getFilters().putAll(metadata);
+        }
+
+        return builder.build();
     }
 
     /**
@@ -262,6 +310,7 @@ public static class Builder {
         private String apiKey;
         private Mem0ApiType apiType;
         private java.time.Duration timeout = java.time.Duration.ofSeconds(60);
+        private Map metadata;
 
         /**
          * Sets the agent name identifier.
@@ -341,6 +390,37 @@ public Builder apiType(Mem0ApiType apiType) {
             return this;
         }
 
+        /**
+         * Sets custom metadata to be stored with memories and used for filtering.
+         *
+         * 
    This metadata will be:
+         * 
      
+         *   
    • Included in the request body when recording memories
      • 
+         *   
    • Added to the filters when searching/retrieving memories
      • 
+         * 
    
+         *
+         * 
    Example usage:
+         * 
    {@code
+         * Map metadata = new HashMap<>();
+         * metadata.put("category", "travel");
+         * metadata.put("priority", "high");
+         *
+         * Mem0LongTermMemory memory = Mem0LongTermMemory.builder()
+         *     .agentName("Assistant")
+         *     .userId("user_123")
+         *     .apiBaseUrl("http://localhost:8000")
+         *     .metadata(metadata)
+         *     .build();
+         * }
    
+         *
+         * @param metadata Custom metadata map (can be null)
+         * @return This builder
+         */
+        public Builder metadata(Map metadata) {
+            this.metadata = metadata;
+            return this;
+        }
+
         /**
          * Builds the Mem0LongTermMemory instance.
          *
diff --git a/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0SearchRequest.java b/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0SearchRequest.java
index 3a3300959..39d18ba0c 100644
--- a/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0SearchRequest.java
+++ b/agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0SearchRequest.java
@@ -230,6 +230,10 @@ public Builder filters(Map filters) {
             return this;
         }
 
+        public Map getFilters() {
+            return this.filters;
+        }
+
         /**
          * Convenience method to add agent_id to filters.
          *

From c3c1038c5f2945b662ec552cd08b0f370bce51d1 Mon Sep 17 00:00:00 2001
From: LearningGp 
Date: Mon, 19 Jan 2026 21:03:39 +0800
Subject: [PATCH 16/53] =?UTF-8?q?fix(a2a):=20prevent=20a2a=20SDK=20SPI=20l?=
 =?UTF-8?q?oading=20issues=20caused=20by=20delayed=20thread=E2=80=A6=20(#6?=
 =?UTF-8?q?01)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## AgentScope-Java Version

1.0.8

## Description

Same as #464

## Checklist

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

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 .../io/agentscope/core/model/transport/JdkHttpTransport.java     | 1 +
 1 file changed, 1 insertion(+)

diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java b/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
index e00b8d15d..f6a374fe3 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/transport/JdkHttpTransport.java
@@ -225,6 +225,7 @@ public Flux stream(HttpRequest request) {
 
         return Mono.fromCompletionStage(future)
                 .flatMapMany(response -> processStreamResponse(response, request))
+                .publishOn(Schedulers.boundedElastic())
                 .onErrorMap(
                         e -> !(e instanceof HttpTransportException),
                         e -> {

From fc754d5f2fcf19f1977f33e4e848d3a86aa0b7f4 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:30:58 +0800
Subject: [PATCH 17/53] chore(deps): bump com.aliyun:bailian20231229 from 2.7.1
 to 2.7.2 (#594)

Bumps
[com.aliyun:bailian20231229](https://github.com/aliyun/alibabacloud-java-sdk)
from 2.7.1 to 2.7.2.

    
Commits


    

    


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.aliyun:bailian20231229&package-manager=maven&previous-version=2.7.1&new-version=2.7.2)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index a138575d0..c57fd9199 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -76,7 +76,7 @@
         33.5.0-jre
         1.35.0
         2.22.5
-        2.7.1
+        2.7.2
         4.15.0
         2.11.1
         0.17.0

From 77c06dc32d6231e575015bfb56d6b1afd34e39d0 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:31:11 +0800
Subject: [PATCH 18/53] chore(deps): bump ch.qos.logback:logback-classic from
 1.5.24 to 1.5.25 (#595)

Bumps
[ch.qos.logback:logback-classic](https://github.com/qos-ch/logback) from
1.5.24 to 1.5.25.

    
Commits

      

    • f426e00
prepare release of 1.5.25
      • 

    • d28931f
restrict object creation to expected supertype
      • 

    • aa264f7
test default variable values in appender-ref ref attribute
      • 

    • 8fb403a
adjust copyright year
      • 

    • b294a12
check optionList in start()
      • 

    • b65040a
Add EpochConverter for milliseconds/seconds since epoch (related to
issue #96...
      • 

    • 0690174
cla for Duncan Jauncey
      • 

    • 71dc2af
Removed email address for Tony.
      • 

    • 1f97ae1
check for undeclared by referenced appenders
      • 

    • b07355e
Move the artifact version checking code to VersionUtil in
logback-core.
      • 

    • Additional commits viewable in compare
view
      • 

    

    

    


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ch.qos.logback:logback-classic&package-manager=maven&previous-version=1.5.24&new-version=1.5.25)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-examples/micronaut/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-examples/micronaut/pom.xml b/agentscope-examples/micronaut/pom.xml
index e094b6311..47f8c699c 100644
--- a/agentscope-examples/micronaut/pom.xml
+++ b/agentscope-examples/micronaut/pom.xml
@@ -65,7 +65,7 @@
         
             ch.qos.logback
             logback-classic
-            1.5.24
+            1.5.25
             runtime
         
     

From aee6bfe488c7a7205373e39037d1cc1bc498fffe Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:31:34 +0800
Subject: [PATCH 19/53] chore(deps): bump redis.clients:jedis from 7.2.0 to
 7.2.1 (#597)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bumps [redis.clients:jedis](https://github.com/redis/jedis) from 7.2.0
to 7.2.1.

    
Release notes

    Sourced from redis.clients:jedis's
releases.
    

    

    7.2.1
    

    Jedis 7.2.1 (Patch Release)
    

    🐛 Bug Fixes
    

      

    • Cluster client builders ignore custom timeout/attempts when
calculating maxTotalRetriesDuration #4395
      • 

    

    Contributors
    

    We'd like to thank all the contributors who worked on this
release!
    

    @​ggivo
    

    

    

    
Commits

      

    • 26bbb8e
Backport: Fix Cluster client builders ignore custom timeout/attempts
when cal...
      • 

    • 5cd0d9d
Bump snapshot version to 7.2.1
      • 

    • See full diff in compare
view
      • 

    

    

    


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=redis.clients:jedis&package-manager=maven&previous-version=7.2.0&new-version=7.2.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index c57fd9199..ed61afa36 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -96,7 +96,7 @@
         0.3.3.Final
         0.3.3.Final
         0.3.3.Final
-        7.2.0
+        7.2.1
         3.3.2
         2.5.2
         7.0.3

From 10e9a07cc7e3c3dc67b028b644a36172cb8626cb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:32:05 +0800
Subject: [PATCH 20/53] chore(deps): bump
 io.opentelemetry.instrumentation:opentelemetry-reactor-3.1 from 2.23.0-alpha
 to 2.24.0-alpha (#593)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bumps
[io.opentelemetry.instrumentation:opentelemetry-reactor-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
from 2.23.0-alpha to 2.24.0-alpha.

    
Release notes

    Sourced from io.opentelemetry.instrumentation:opentelemetry-reactor-3.1's
releases.
    

    

    Version 2.23.0
    

    This release targets the OpenTelemetry SDK 1.57.0.
    

    Note that many artifacts have the -alpha suffix attached
to their version number, reflecting that they are still alpha quality
and will continue to have breaking changes. Please see the VERSIONING.md
for more details.
    

    ⚠️ Breaking Changes
    

      

    • ActiveMQ Classic JMX metrics: rename attributes and metrics to align
with semantic conventions (see PR description for specifics) (#14996)
      • 

    • Library instrumentation: remove previously deprecated methods from
telemetry builders (#15324)
      • 

    • Logback: captureArguments no longer captures message
template, use captureTemplate (#15423)
      • 

    • Play: disable controller spans by default, re-enable with
otel.instrumentation.common.experimental.controller-telemetry.enabled=true
(#15604)
      • 

    

    🚫 Deprecations
    

      

    • Library instrumentation: deprecate
setSpanNameExtractor() and
setStatusExtractor() in favor of
setSpanNameExtractorCustomizer() and
setStatusExtractorCustomizer() (#15529)
      • 

    

    🌟 New javaagent instrumentation
    


    🌟 New library instrumentation
    


    📈 Enhancements
    

      

    • Spring starter: add declarative config logging exporter (#14917)
      • 

    • Failsafe: add support for RetryPolicy (#15255,
#15537)
      • 

    • GraphQL: add option to disable capturing query documents (#15384)
      • 

    • JMX metrics: allow any classpath resource path in rules (#15413)
      • 

    • Spring Boot actuator autoconfigure: support Spring Boot 4 (#15433)
      • 

    • Spring JMS: support Spring Boot 4 (#15434)
      • 

    • Spring starter: support Spring Boot 4 (#15459)
      • 

    • Lettuce: support custom ClientResources (#15470)
      • 

    • Lettuce: add reactor-core compatibility checker (#15472)
      • 

    • Servlet: propagate context explicitly for async runnables (#15476)
      • 

    • Servlet: always add trace_id and span_id
attributes to requests (#15485)
      • 

    • Pekko HTTP: separate route instrumentation from HTTP server
instrumentation (#15499)
      • 

    • MongoDB: emit versioned scope name (#15500)
      • 

    • Spring WebFlux: support Spring Boot 4 (#15502,
#15574)
      • 

    • Spring WebMVC: support Spring Boot 4 (#15525)
      • 

    • Spring Cloud Gateway: support Spring Boot 4 (#15540)
      • 

    • Spring starter: add missing Kafka configuration options (#15592)
      • 

    • OpenTelemetry API interop: support new GlobalOpenTelemetry methods
introduced in 1.57 (#15620)
      • 

    

    🛠️ Bug fixes
    

      

    • Spring Web/WebFlux: restore GraalVM native-image compatibility (#15306)
      • 

    • Spring Kafka: end span in afterRecord callback (#15367)
      • 

    


    

    ... (truncated)
    

    

    
Changelog

    Sourced from io.opentelemetry.instrumentation:opentelemetry-reactor-3.1's
changelog.
    

    

    Changelog
    

    Unreleased
    

    Version 2.24.0 (2026-01-17)
    

    ⚠️ Breaking Changes
    

      

    • Remove support for previously deprecated property

otel.instrumentation.logback-appender.experimental.capture-logstash-attributes
(#15722)
      • 

    • Remove deprecated methods from HTTP library instrumentations
(#15802)
      • 

    

    🚫 Deprecations
    

      

    • JMX Metrics: Deprecated addClassPathRules and
addCustomRules methods in
JmxTelemetryBuilder, and moved non-public classes to an
internal package
(#15658)
      • 

    • Deprecated setMessagingReceiveInstrumentationEnabled in
favor of
setMessagingReceiveTelemetryEnabled to match config
property name
(#15668)
      • 

    • Deprecated database client attribute getter methods
getDbSystem() and getResponseStatus()
in favor of getDbSystemName() and
getResponseStatusCode() to align with stable semantic
conventions
(#15696)
      • 

    • Deprecated setCapturedRequestParameters() in Servlet
library instrumentation in favor of
Experimental.setCapturedRequestParameters() as request
parameter capture is experimental
(#15826)
      • 

    • Deprecated getHttpClient(),
setHttpClientTransport(), and
setSslContextFactory() in Jetty
client instrumentation in favor of new builder-style methods
newHttpClient(),
newHttpClient(SslContextFactory), and
newHttpClient(HttpClientTransport, SslContextFactory)
(#15827)
      • 

    • Deprecate Netty experimental method that is still in public API
(#15828)
      • 

    • Deprecated newHttpClient() in favor of
wrap() in Java HTTP Client instrumentation for
consistency with naming conventions across library instrumentations
(#15829)
      • 

    • Deprecated new* methods in favor of
create* methods across multiple instrumentation libraries
for consistency (e.g., newHttpClient() →
createHttpClient(), newInterceptor() →
createInterceptor())
(#15832)
      • 

    • Deprecated methods in SqlStatementInfo and
MultiQuery in favor of methods using stable
semantic convention terminology: getFullStatement() →
getQueryText(), getOperation() →
getOperationName(), and getStatements() →
getQueryTexts()
(#15833)
      • 

    • Deprecated database getter methods in favor of methods using stable
semantic convention
terminology: getResponseStatusCode() →
getDbResponseStatusCode(), getBatchSize() →
getDbOperationBatchSize(), and
getQueryParameters() → getDbQueryParameters()
(#15859)
      • 

    


    

    ... (truncated)
    

    

    
Commits


    

    


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=io.opentelemetry.instrumentation:opentelemetry-reactor-3.1&package-manager=maven&previous-version=2.23.0-alpha&new-version=2.24.0-alpha)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index ed61afa36..e4fee3575 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -90,7 +90,7 @@
         3.2.3
         2.1.2
         9.5.0
-        2.23.0-alpha
+        2.24.0-alpha
         1.37.0-alpha
         4.1.0
         0.3.3.Final

From 86dc1be32d492f22e4afe404e8288d2154e937ff Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:33:12 +0800
Subject: [PATCH 21/53] chore(deps): bump com.fasterxml.jackson:jackson-bom
 from 2.20.1 to 2.21.0 (#603)

Bumps
[com.fasterxml.jackson:jackson-bom](https://github.com/FasterXML/jackson-bom)
from 2.20.1 to 2.21.0.

    
Commits


    

    


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.fasterxml.jackson:jackson-bom&package-manager=maven&previous-version=2.20.1&new-version=2.21.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index e4fee3575..56b3d8355 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -70,7 +70,7 @@
         1.58.0
         5.3.2
         2025.0.2
-        2.20.1
+        2.21.0
         5.21.0
         6.0.2
         33.5.0-jre

From 928f1ba29ba881cf48bd2991dd825836d0be2a70 Mon Sep 17 00:00:00 2001
From: guanxu <86234262+guanxuc@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:33:38 +0800
Subject: [PATCH 22/53] chore(dependency): Exclude lombok to compatible with
 jdk25 (#604)

## AgentScope-Java Version

1.0.8

## Description

* Exclude lombok to compatible with jdk25.
* When use the low level lombok and jdk25 will cause the error as the
follow, btw, lombok should not be passed on.
```java
java: java.lang.ExceptionInInitializerError
com.sun.tools.javac.code.TypeTag :: UNKNOWN
java: java.lang.ExceptionInInitializerError
```

## Checklist

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

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 agentscope-core/pom.xml                                       | 4 ++++
 .../agentscope-extensions-rag-simple/pom.xml                  | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/agentscope-core/pom.xml b/agentscope-core/pom.xml
index 0df26d7ff..54bf500a7 100644
--- a/agentscope-core/pom.xml
+++ b/agentscope-core/pom.xml
@@ -100,6 +100,10 @@
                     slf4j-simple
                     org.slf4j
                 
+                
+                    lombok
+                    org.projectlombok
+                
             
         
 
diff --git a/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml b/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
index 8f7938b27..eb3b8e19a 100644
--- a/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
+++ b/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
@@ -45,6 +45,10 @@
                     slf4j-simple
                     org.slf4j
                 
+                
+                    lombok
+                    org.projectlombok
+                
             
         
 

From 2de5c66536922b0758034eecfa581a6d8c94a398 Mon Sep 17 00:00:00 2001
From: B18150228NJUPT <60096181+B18150228NJUPT@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:37:14 +0800
Subject: [PATCH 23/53] fix(a2a): jakarta.servlet.http.HttpServletRequest is
 not compatible with webflux, use @RequestHeader make spring autoAdjust (#587)

## AgentScope-Java Version

main branch

## Description

jakarta.servlet.http.HttpServletRequest is not compatible with webflux,
use @RequestHeader make spring autoAdjust

## Checklist

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

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 .../a2a/controller/A2aJsonRpcController.java  | 19 ++--------
 .../controller/A2aJsonRpcControllerTest.java  | 38 +++++++------------
 2 files changed, 16 insertions(+), 41 deletions(-)

diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/main/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcController.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/main/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcController.java
index 6c20c6058..6401a1c77 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/main/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcController.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/main/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcController.java
@@ -21,15 +21,13 @@
 import io.a2a.util.Utils;
 import io.agentscope.core.a2a.server.AgentScopeA2aServer;
 import io.agentscope.core.a2a.server.transport.jsonrpc.JsonRpcTransportWrapper;
-import jakarta.servlet.http.HttpServletRequest;
-import java.util.Enumeration;
-import java.util.HashMap;
 import java.util.Map;
 import java.util.logging.Logger;
 import org.springframework.http.MediaType;
 import org.springframework.http.codec.ServerSentEvent;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
 import org.springframework.web.bind.annotation.RestController;
@@ -54,8 +52,8 @@ public A2aJsonRpcController(AgentScopeA2aServer agentScopeA2aServer) {
             consumes = MediaType.APPLICATION_JSON_VALUE,
             produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.TEXT_EVENT_STREAM_VALUE})
     @ResponseBody
-    public Object handleRequest(@RequestBody String body, HttpServletRequest httpRequest) {
-        Map header = getHeaders(httpRequest);
+    public Object handleRequest(
+            @RequestBody String body, @RequestHeader Map header) {
         Object result = getJsonRpcHandler().handleRequest(body, header, Map.of());
         if (result instanceof Flux fluxResult) {
             return fluxResult
@@ -76,17 +74,6 @@ private JsonRpcTransportWrapper getJsonRpcHandler() {
         return jsonRpcHandler;
     }
 
-    private Map getHeaders(HttpServletRequest request) {
-        Map headers = new HashMap<>();
-        Enumeration headerNames = request.getHeaderNames();
-        while (headerNames.hasMoreElements()) {
-            String headerName = headerNames.nextElement();
-            String headerValue = request.getHeader(headerName);
-            headers.put(headerName, headerValue);
-        }
-        return headers;
-    }
-
     private ServerSentEvent convertToSse(JSONRPCResponse response) {
         try {
             String data = Utils.OBJECT_MAPPER.writeValueAsString(response);
diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/test/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcControllerTest.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/test/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcControllerTest.java
index b69224f06..4f44452d3 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/test/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcControllerTest.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-a2a-spring-boot-starter/src/test/java/io/agentscope/spring/boot/a2a/controller/A2aJsonRpcControllerTest.java
@@ -29,9 +29,8 @@
 import io.a2a.spec.TransportProtocol;
 import io.agentscope.core.a2a.server.AgentScopeA2aServer;
 import io.agentscope.core.a2a.server.transport.jsonrpc.JsonRpcTransportWrapper;
-import jakarta.servlet.http.HttpServletRequest;
 import java.util.Collections;
-import java.util.Enumeration;
+import java.util.Map;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
@@ -57,7 +56,7 @@ class A2aJsonRpcControllerTest {
 
     @Mock private JsonRpcTransportWrapper jsonRpcTransportWrapper;
 
-    @Mock private HttpServletRequest httpRequest;
+    private Map headers;
 
     @BeforeEach
     void setUp() {
@@ -67,6 +66,7 @@ void setUp() {
                         eq(TransportProtocol.JSONRPC.asString()),
                         eq(JsonRpcTransportWrapper.class)))
                 .thenReturn(jsonRpcTransportWrapper);
+        headers = Collections.emptyMap();
     }
 
     @Nested
@@ -79,11 +79,10 @@ void shouldHandleJsonRpcRequestAndReturnPlainObject() {
             String requestBody = "{\"method\": \"test\"}";
             String responseBody = "{\"result\": \"success\"}";
 
-            when(httpRequest.getHeaderNames()).thenReturn(Collections.emptyEnumeration());
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(responseBody);
 
-            Object result = controller.handleRequest(requestBody, httpRequest);
+            Object result = controller.handleRequest(requestBody, headers);
 
             assertEquals(responseBody, result);
 
@@ -111,11 +110,10 @@ void shouldHandleJsonRpcRequestAndReturnFluxWithJsonRpcResponse() {
             Message message = A2A.toAgentMessage("test");
             SendStreamingMessageResponse response = new SendStreamingMessageResponse(1, message);
 
-            when(httpRequest.getHeaderNames()).thenReturn(Collections.emptyEnumeration());
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(Flux.just(response));
 
-            Object result = controller.handleRequest(requestBody, httpRequest);
+            Object result = controller.handleRequest(requestBody, headers);
 
             assertTrue(result instanceof Flux);
 
@@ -141,17 +139,13 @@ void shouldHandleRequestWithHeaders() {
             String responseBody = "{\"result\": \"success\"}";
 
             // Mock headers
-            Enumeration headerNames =
-                    Collections.enumeration(
-                            java.util.Arrays.asList("Content-Type", "Authorization"));
-            when(httpRequest.getHeaderNames()).thenReturn(headerNames);
-            when(httpRequest.getHeader("Content-Type")).thenReturn("application/json");
-            when(httpRequest.getHeader("Authorization")).thenReturn("Bearer token");
+            Map header =
+                    Map.of("Content-Type", "application/json", "Authorization", "Bearer token");
 
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(responseBody);
 
-            Object result = controller.handleRequest(requestBody, httpRequest);
+            Object result = controller.handleRequest(requestBody, header);
 
             assertEquals(responseBody, result);
 
@@ -179,16 +173,12 @@ void shouldExtractHeadersFromHttpServletRequest() {
             String requestBody = "{\"method\": \"test\"}";
             String responseBody = "{\"result\": \"success\"}";
 
-            Enumeration headerNames =
-                    Collections.enumeration(java.util.Arrays.asList("Header1", "Header2"));
-            when(httpRequest.getHeaderNames()).thenReturn(headerNames);
-            when(httpRequest.getHeader("Header1")).thenReturn("Value1");
-            when(httpRequest.getHeader("Header2")).thenReturn("Value2");
+            Map header = Map.of("Header1", "Value1", "Header2", "Value2");
 
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(responseBody);
 
-            controller.handleRequest(requestBody, httpRequest);
+            controller.handleRequest(requestBody, header);
 
             ArgumentCaptor> headersCaptor =
                     ArgumentCaptor.forClass(java.util.Map.class);
@@ -206,11 +196,10 @@ void shouldHandleEmptyHeaders() {
             String requestBody = "{\"method\": \"test\"}";
             String responseBody = "{\"result\": \"success\"}";
 
-            when(httpRequest.getHeaderNames()).thenReturn(Collections.emptyEnumeration());
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(responseBody);
 
-            controller.handleRequest(requestBody, httpRequest);
+            controller.handleRequest(requestBody, headers);
 
             ArgumentCaptor> headersCaptor =
                     ArgumentCaptor.forClass(java.util.Map.class);
@@ -232,16 +221,15 @@ void shouldLazilyInitializeJsonRpcHandler() {
             String requestBody = "{\"method\": \"test\"}";
             String responseBody = "{\"result\": \"success\"}";
 
-            when(httpRequest.getHeaderNames()).thenReturn(Collections.emptyEnumeration());
             when(jsonRpcTransportWrapper.handleRequest(anyString(), anyMap(), anyMap()))
                     .thenReturn(responseBody);
 
             // First call should initialize the handler
-            Object result1 = controller.handleRequest(requestBody, httpRequest);
+            Object result1 = controller.handleRequest(requestBody, headers);
             assertEquals(responseBody, result1);
 
             // Second call should reuse the same handler
-            Object result2 = controller.handleRequest(requestBody, httpRequest);
+            Object result2 = controller.handleRequest(requestBody, headers);
             assertEquals(responseBody, result2);
 
             // Should only fetch the transport wrapper once

From 1f8fd79a8d1ff45a512248264c684f3f5bcf38b1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 20 Jan 2026 16:37:34 +0800
Subject: [PATCH 24/53] chore(deps): bump com.alibaba:dashscope-sdk-java from
 2.22.5 to 2.22.6 (#596)

Bumps com.alibaba:dashscope-sdk-java from 2.22.5 to 2.22.6.


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.alibaba:dashscope-sdk-java&package-manager=maven&previous-version=2.22.5&new-version=2.22.6)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---


    
Dependabot commands and options

    

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show  ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)



    

Signed-off-by: dependabot[bot] 
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 agentscope-dependencies-bom/pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index 56b3d8355..1a792f164 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -75,7 +75,7 @@
         6.0.2
         33.5.0-jre
         1.35.0
-        2.22.5
+        2.22.6
         2.7.2
         4.15.0
         2.11.1

From 0761c65d9341fbf25fbfa87a86c5a2f8388ca95a Mon Sep 17 00:00:00 2001
From: Shen Junkun <2458684728@qq.com>
Date: Wed, 21 Jan 2026 11:05:30 +0800
Subject: [PATCH 25/53] feat: Elasticsearch RAG Storage (#503)

## AgentScope-Java Version
`io.agentscope:agentscope-parent:pom:1.0.7-SNAPSHOT`


## Description
### Background
This PR addresses #236 by implementing **ElasticSearch** as a dedicated
storage backend for the RAG (Retrieval-Augmented Generation) pipeline.
While the system previously supported other vector stores, this
integration allows users to leverage ElasticSearch's enterprise-grade
scalability, hybrid search capabilities, and robust document management.

### Key Changes
- **Added `ElasticsearchStore.java`**: Implemented the core logic for
the vector store, including document indexing and retrieval
functionality.
- **Comprehensive Testing**:
- Added `ElasticsearchTest.java` for **unit testing** core components.
- Added `ElasticsearchRAGExample.java` as an **end-to-end** test case to
demonstrate the full RAG workflow.
- **Documentation Updates**: Updated the `docs` directory with both
English and Chinese documentation to reflect the new integration.

## Checklist
- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 agentscope-dependencies-bom/pom.xml           |   9 +-
 agentscope-examples/advanced/pom.xml          |  11 +
 .../advanced/ElasticsearchRAGExample.java     | 207 +++++++
 .../agentscope-extensions-rag-simple/pom.xml  |   6 +
 .../core/rag/store/ElasticsearchStore.java    | 564 ++++++++++++++++++
 .../rag/store/ElasticsearchStoreTest.java     | 532 +++++++++++++++++
 docs/en/quickstart/installation.md            |   3 +-
 docs/en/task/rag.md                           |   6 +-
 docs/zh/quickstart/installation.md            |   3 +-
 docs/zh/task/rag.md                           |   3 +-
 10 files changed, 1338 insertions(+), 6 deletions(-)
 create mode 100644 agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java
 create mode 100644 agentscope-extensions/agentscope-extensions-rag-simple/src/main/java/io/agentscope/core/rag/store/ElasticsearchStore.java
 create mode 100644 agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/store/ElasticsearchStoreTest.java

diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml
index 1a792f164..eea23cb0c 100644
--- a/agentscope-dependencies-bom/pom.xml
+++ b/agentscope-dependencies-bom/pom.xml
@@ -83,6 +83,7 @@
         2.0.17
         1.16.2
         2.6.12
+        8.12.0
         42.7.9
         0.1.6
         3.0.6
@@ -238,6 +239,13 @@
                 ${qdrant.version}
             
 
+            
+            
+                co.elastic.clients
+                elasticsearch-java
+                ${elasticsearch.version}
+            
+
             
             
                 org.jetbrains.kotlinx
@@ -251,7 +259,6 @@
                 ${kotlin.coroutines.version}
             
 
-
             
             
                 io.milvus
diff --git a/agentscope-examples/advanced/pom.xml b/agentscope-examples/advanced/pom.xml
index d83b4265f..81019c4a1 100644
--- a/agentscope-examples/advanced/pom.xml
+++ b/agentscope-examples/advanced/pom.xml
@@ -36,6 +36,17 @@
 
     
         
+            
+            
+                co.elastic.clients
+                elasticsearch-java
+                8.12.0
+            
+
             
             
                 org.springframework.boot
diff --git a/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java b/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java
new file mode 100644
index 000000000..3d2faa12a
--- /dev/null
+++ b/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java
@@ -0,0 +1,207 @@
+/*
+ * 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.examples.advanced;
+
+import io.agentscope.core.ReActAgent;
+import io.agentscope.core.embedding.EmbeddingModel;
+import io.agentscope.core.embedding.dashscope.DashScopeTextEmbedding;
+import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
+import io.agentscope.core.memory.InMemoryMemory;
+import io.agentscope.core.model.DashScopeChatModel;
+import io.agentscope.core.rag.Knowledge;
+import io.agentscope.core.rag.RAGMode;
+import io.agentscope.core.rag.knowledge.SimpleKnowledge;
+import io.agentscope.core.rag.model.Document;
+import io.agentscope.core.rag.reader.ReaderInput;
+import io.agentscope.core.rag.reader.SplitStrategy;
+import io.agentscope.core.rag.reader.TextReader;
+import io.agentscope.core.rag.store.ElasticsearchStore;
+import io.agentscope.core.tool.Toolkit;
+import java.io.IOException;
+import java.util.List;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * ElasticsearchRAGExample - Demonstrates RAG capabilities using Elasticsearch as the vector store.
+ *
+ * 
    Prerequisites:
+ * 1. An Elasticsearch instance running (e.g., via Docker: docker run -p 9200:9200 -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.12.0)
+ * 2. DashScope API Key
+ */
+public class ElasticsearchRAGExample {
+
+    private static final Logger log = LoggerFactory.getLogger(ElasticsearchRAGExample.class);
+
+    // Configuration
+    private static final int EMBEDDING_DIMENSIONS = 1024;
+
+    // Elasticsearch Configuration (Modify these as per your setup)
+    private static final String ES_URL = System.getProperty("es.url", "http://localhost:9200");
+    private static final String ES_USERNAME = System.getProperty("es.user", "elastic");
+    private static final String ES_PASSWORD = System.getProperty("es.pass", "changeme");
+    private static final String ES_INDEX_NAME = "agentscope_rag_example";
+
+    public static void main(String[] args) throws Exception {
+        // Print welcome message
+        ExampleUtils.printWelcome(
+                "Elasticsearch RAG Example",
+                "This example demonstrates RAG capabilities using Elasticsearch:\n"
+                        + "  - Connecting to Elasticsearch vector store\n"
+                        + "  - Indexing documents with dense vectors\n"
+                        + "  - Agentic knowledge retrieval backed by ES");
+
+        // Get API key
+        String apiKey = ExampleUtils.getDashScopeApiKey();
+
+        // 1. Create embedding model
+        System.out.println("Creating embedding model...");
+        EmbeddingModel embeddingModel =
+                DashScopeTextEmbedding.builder()
+                        .apiKey(apiKey)
+                        .modelName("text-embedding-v3")
+                        .dimensions(EMBEDDING_DIMENSIONS)
+                        .build();
+        System.out.println("Embedding model created.");
+
+        // 2. Create Elasticsearch vector store
+        System.out.println("Connecting to Elasticsearch at " + ES_URL + "...");
+
+        // Note: We use try-with-resources to ensure the store is closed when done,
+        // effectively closing the underlying HTTP clients.
+        try (ElasticsearchStore vectorStore =
+                ElasticsearchStore.builder()
+                        .url(ES_URL)
+                        .username(ES_USERNAME) // Set null if no auth
+                        .password(ES_PASSWORD) // Set null if no auth
+                        .indexName(ES_INDEX_NAME)
+                        .dimensions(EMBEDDING_DIMENSIONS)
+                        .build()) {
+
+            System.out.println("Elasticsearch store initialized and connected.");
+
+            // 3. Create knowledge base linking the model and the store
+            System.out.println("Creating knowledge base...");
+            Knowledge knowledge =
+                    SimpleKnowledge.builder()
+                            .embeddingModel(embeddingModel)
+                            .embeddingStore(vectorStore)
+                            .build();
+            System.out.println("Knowledge base created.");
+
+            // 4. Add documents to knowledge base (Elasticsearch)
+            System.out.println("Adding documents to Elasticsearch...");
+            // In a real scenario, you might check if data exists first to avoid duplication
+            addSampleDocuments(knowledge);
+            System.out.println("Documents added to index: " + ES_INDEX_NAME);
+
+            // 5. Demonstrate Agentic Mode
+            System.out.println("\n=== Agentic RAG Mode with Elasticsearch ===");
+            demonstrateAgenticMode(apiKey, knowledge);
+
+        } catch (Exception e) {
+            log.error("Error running Elasticsearch RAG Example", e);
+            System.err.println("Error: " + e.getMessage());
+            System.err.println("Make sure Elasticsearch is running at " + ES_URL);
+        }
+
+        System.out.println("\n=== Example completed ===");
+        // System.exit(0) is often needed with async libraries to kill lingering threads
+        System.exit(0);
+    }
+
+    /**
+     * Add sample documents to the knowledge base.
+     */
+    private static void addSampleDocuments(Knowledge knowledge) {
+        // Sample documents about AgentScope and Elasticsearch
+        String[] documents = {
+            "AgentScope is a multi-agent system framework developed by ModelScope. It provides a"
+                    + " unified interface for building and managing multi-agent applications.",
+            "Elasticsearch is a distributed, RESTful search and analytics engine capable of "
+                    + "performing vector similarity search using kNN (k-nearest neighbors).",
+            "This specific example demonstrates how to replace the InMemoryStore with an "
+                    + "ElasticsearchStore in AgentScope to persist knowledge data.",
+            "RAG (Retrieval-Augmented Generation) combines LLMs with external knowledge retrieval "
+                    + "to reduce hallucinations and provide up-to-date information.",
+            "AgentScope allows developers to easily switch between different vector store"
+                    + " implementations via the VDBStoreBase interface."
+        };
+
+        // Create reader for text documents
+        TextReader reader = new TextReader(512, SplitStrategy.PARAGRAPH, 50);
+
+        // Add each document
+        for (int i = 0; i < documents.length; i++) {
+            String docText = documents[i];
+            ReaderInput input = ReaderInput.fromString(docText);
+
+            try {
+                List docs = reader.read(input).block();
+                if (docs != null && !docs.isEmpty()) {
+                    // This will embed the document and push it to Elasticsearch
+                    knowledge.addDocuments(docs).block();
+                    System.out.println(
+                            "  Indexed document "
+                                    + (i + 1)
+                                    + ": "
+                                    + docText.substring(0, Math.min(50, docText.length()))
+                                    + "...");
+                }
+            } catch (Exception e) {
+                System.err.println("  Error adding document " + (i + 1) + ": " + e.getMessage());
+            }
+        }
+    }
+
+    /**
+     * Demonstrate Agentic RAG mode using built-in RAG configuration.
+     */
+    private static void demonstrateAgenticMode(String apiKey, Knowledge knowledge)
+            throws IOException {
+        // Create agent with built-in Agentic RAG configuration
+        ReActAgent agent =
+                ReActAgent.builder()
+                        .name("ES_RAG_Agent")
+                        .sysPrompt(
+                                "You are a helpful assistant with access to an Elasticsearch"
+                                    + " knowledge base. When user asks technical questions, use the"
+                                    + " retrieve_knowledge tool to find the answer in the database."
+                                    + " Always cite your source if possible.")
+                        .model(
+                                DashScopeChatModel.builder()
+                                        .apiKey(apiKey)
+                                        .modelName("qwen-max")
+                                        .stream(true)
+                                        .enableThinking(false)
+                                        .formatter(new DashScopeChatFormatter())
+                                        .build())
+                        .toolkit(new Toolkit())
+                        .memory(new InMemoryMemory())
+                        // Bind the Elasticsearch-backed Knowledge base
+                        .knowledge(knowledge)
+                        .ragMode(RAGMode.AGENTIC)
+                        .build();
+
+        System.out.println("Agent created. Try asking:");
+        System.out.println("  - 'What is AgentScope?'");
+        System.out.println("  - 'How is Elasticsearch used here?'");
+        System.out.println("  - 'Explain RAG.'\n");
+
+        // Start interactive chat
+        ExampleUtils.startChat(agent);
+    }
+}
diff --git a/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml b/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
index eb3b8e19a..b47358937 100644
--- a/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
+++ b/agentscope-extensions/agentscope-extensions-rag-simple/pom.xml
@@ -76,6 +76,12 @@
             milvus-sdk-java
         
 
+        
+        
+            co.elastic.clients
+            elasticsearch-java
+        
+
         
         
             org.postgresql
diff --git a/agentscope-extensions/agentscope-extensions-rag-simple/src/main/java/io/agentscope/core/rag/store/ElasticsearchStore.java b/agentscope-extensions/agentscope-extensions-rag-simple/src/main/java/io/agentscope/core/rag/store/ElasticsearchStore.java
new file mode 100644
index 000000000..504d9ca91
--- /dev/null
+++ b/agentscope-extensions/agentscope-extensions-rag-simple/src/main/java/io/agentscope/core/rag/store/ElasticsearchStore.java
@@ -0,0 +1,564 @@
+/*
+ * 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.rag.store;
+
+import co.elastic.clients.elasticsearch.ElasticsearchClient;
+import co.elastic.clients.elasticsearch._types.mapping.DenseVectorProperty;
+import co.elastic.clients.elasticsearch._types.mapping.KeywordProperty;
+import co.elastic.clients.elasticsearch._types.mapping.Property;
+import co.elastic.clients.elasticsearch._types.mapping.TextProperty;
+import co.elastic.clients.elasticsearch._types.mapping.TypeMapping;
+import co.elastic.clients.elasticsearch.core.BulkRequest;
+import co.elastic.clients.elasticsearch.core.BulkResponse;
+import co.elastic.clients.elasticsearch.core.SearchRequest;
+import co.elastic.clients.elasticsearch.core.SearchResponse;
+import co.elastic.clients.elasticsearch.core.bulk.BulkResponseItem;
+import co.elastic.clients.elasticsearch.core.search.Hit;
+import co.elastic.clients.elasticsearch.indices.CreateIndexRequest;
+import co.elastic.clients.elasticsearch.indices.ExistsRequest;
+import co.elastic.clients.json.jackson.JacksonJsonpMapper;
+import co.elastic.clients.transport.ElasticsearchTransport;
+import co.elastic.clients.transport.rest_client.RestClientTransport;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.agentscope.core.message.ContentBlock;
+import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.rag.exception.VectorStoreException;
+import io.agentscope.core.rag.model.Document;
+import io.agentscope.core.rag.model.DocumentMetadata;
+import io.agentscope.core.rag.store.dto.SearchDocumentDto;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import javax.net.ssl.SSLContext;
+import org.apache.http.HttpHost;
+import org.apache.http.auth.AuthScope;
+import org.apache.http.auth.UsernamePasswordCredentials;
+import org.apache.http.conn.ssl.NoopHostnameVerifier;
+import org.apache.http.impl.client.BasicCredentialsProvider;
+import org.apache.http.ssl.SSLContextBuilder;
+import org.elasticsearch.client.RestClient;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+
+/**
+ * Elasticsearch vector database store implementation.
+ *
+ * 
    This class provides an interface for storing and searching vectors using Elasticsearch.
+ * It uses the official {@code elasticsearch-java} client.
+ *
+ * 
    The implementation uses the {@code dense_vector} field type for storing embeddings and
+ * kNN search for retrieval.
+ *
+ * 
    Example usage:
+ * 
    {@code
+ * // Using builder with authentication
+ * try (ElasticsearchStore store = ElasticsearchStore.builder()
+ * .url("http://localhost:9200")
+ * .indexName("my_rag_index")
+ * .dimensions(1024)
+ * .username("elastic")
+ * .password("changeme")
+ * .build()) {
+ *
+ * store.add(document).block();
+ * List results = store.search(queryEmbedding, 5, 0.7).block();
+ * }
+ * }
    
+ */
+public class ElasticsearchStore implements VDBStoreBase, AutoCloseable {
+    private static final Logger log = LoggerFactory.getLogger(ElasticsearchStore.class);
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    // Field names for Elasticsearch mapping
+    private static final String FIELD_ID = "id";
+    private static final String FIELD_VECTOR = "vector";
+    private static final String FIELD_DOC_ID = "doc_id";
+    private static final String FIELD_CHUNK_ID = "chunk_id";
+    private static final String FIELD_CONTENT = "content";
+
+    private final String indexName;
+    private final int dimensions;
+    private final RestClient restClient;
+    private final ElasticsearchTransport transport;
+    private final ElasticsearchClient client;
+    private final boolean disableSslVerification;
+
+    private volatile boolean closed = false;
+
+    private ElasticsearchStore(Builder builder) throws VectorStoreException {
+        this.indexName = builder.indexName;
+        this.dimensions = builder.dimensions;
+        this.disableSslVerification = builder.disableSslVerification;
+        try {
+            // 1. Configure Low-level RestClient
+            BasicCredentialsProvider credsProv = new BasicCredentialsProvider();
+            if (builder.username != null && builder.password != null) {
+                credsProv.setCredentials(
+                        AuthScope.ANY,
+                        new UsernamePasswordCredentials(builder.username, builder.password));
+            }
+
+            final SSLContext sslContext;
+            if (this.disableSslVerification) {
+                sslContext =
+                        SSLContextBuilder.create()
+                                .loadTrustMaterial(null, (chain, authType) -> true)
+                                .build();
+            } else {
+                sslContext = SSLContext.getDefault();
+            }
+
+            HttpHost host = HttpHost.create(builder.url);
+
+            this.restClient =
+                    RestClient.builder(host)
+                            .setHttpClientConfigCallback(
+                                    httpClientBuilder -> {
+                                        if (builder.username != null) {
+                                            httpClientBuilder.setDefaultCredentialsProvider(
+                                                    credsProv);
+                                        }
+
+                                        if (builder.url != null
+                                                && builder.url.startsWith("https")) {
+                                            httpClientBuilder.setSSLContext(sslContext);
+                                            if (builder.disableSslVerification) {
+                                                httpClientBuilder.setSSLHostnameVerifier(
+                                                        NoopHostnameVerifier.INSTANCE);
+                                            }
+                                        }
+                                        return httpClientBuilder;
+                                    })
+                            .build();
+
+            // 2. Create Transport and Client
+            this.transport =
+                    new RestClientTransport(restClient, new JacksonJsonpMapper(OBJECT_MAPPER));
+            this.client = new ElasticsearchClient(transport);
+
+            // 3. Ensure Index Exists
+            ensureIndex();
+
+            log.debug("ElasticsearchStore initialized successfully for index: {}", indexName);
+
+        } catch (Exception e) {
+            // Cleanup on failure
+            closeQuietly();
+            throw new VectorStoreException("Failed to initialize ElasticsearchStore", e);
+        }
+    }
+
+    /**
+     * Adds a list of documents to the Elasticsearch index.
+     *
+     * @param documents the list of documents to add
+     * @return a Mono that completes when the operation is finished
+     */
+    @Override
+    public Mono add(List documents) {
+        if (documents == null || documents.isEmpty()) {
+            return Mono.empty();
+        }
+
+        return Mono.fromCallable(
+                        () -> {
+                            ensureNotClosed();
+                            executeBulkAdd(documents);
+                            return null;
+                        })
+                .subscribeOn(Schedulers.boundedElastic())
+                .doOnError(e -> log.error("Failed to add documents to Elasticsearch", e))
+                .onErrorMap(
+                        e -> !(e instanceof VectorStoreException),
+                        e -> new VectorStoreException("Failed to add documents", e))
+                .then();
+    }
+
+    private void executeBulkAdd(List documents) throws Exception {
+        BulkRequest.Builder br = new BulkRequest.Builder();
+
+        for (Document doc : documents) {
+            validateDocument(doc);
+            Map esDoc = mapToEsDocument(doc);
+
+            br.operations(
+                    op -> op.index(idx -> idx.index(indexName).id(doc.getId()).document(esDoc)));
+        }
+
+        BulkResponse response = client.bulk(br.build());
+        if (response.errors()) {
+            for (BulkResponseItem item : response.items()) {
+                if (item.error() != null) {
+                    log.error("Error indexing ID {}: {}", item.id(), item.error().reason());
+                }
+            }
+            throw new VectorStoreException("Elasticsearch bulk indexing failed");
+        }
+    }
+
+    /**
+     * Searches for documents in the Elasticsearch index matching the query embedding.
+     *
+     * @param searchDocumentDto the search criteria containing query embedding, limit, and score threshold
+     * @return a Mono containing the list of matching documents
+     */
+    @Override
+    public Mono> search(SearchDocumentDto searchDocumentDto) {
+        double[] queryEmbedding = searchDocumentDto.getQueryEmbedding();
+        int limit = searchDocumentDto.getLimit();
+        Double scoreThreshold = searchDocumentDto.getScoreThreshold();
+        return Mono.fromCallable(
+                        () -> {
+                            ensureNotClosed();
+                            return executeSearch(queryEmbedding, limit, scoreThreshold);
+                        })
+                .subscribeOn(Schedulers.boundedElastic())
+                .doOnError(e -> log.error("Error during vector search", e))
+                .onErrorMap(e -> new VectorStoreException("Vector search failed", e));
+    }
+
+    private List executeSearch(double[] queryEmbedding, int limit, Double scoreThreshold)
+            throws Exception {
+        if (queryEmbedding.length != dimensions) {
+            throw new VectorStoreException("Embedding dimension mismatch");
+        }
+
+        List queryVector = new ArrayList<>();
+        for (double v : queryEmbedding) {
+            queryVector.add((float) v);
+        }
+
+        SearchRequest searchRequest =
+                SearchRequest.of(
+                        s ->
+                                s.index(indexName)
+                                        .knn(
+                                                k ->
+                                                        k.field(FIELD_VECTOR)
+                                                                .queryVector(queryVector)
+                                                                .k(limit)
+                                                                .numCandidates(
+                                                                        Math.max(limit * 2, 50)))
+                                        .size(limit)
+                                        .minScore(scoreThreshold != null ? scoreThreshold : 0.0));
+
+        SearchResponse response = client.search(searchRequest, Map.class);
+        List results = new ArrayList<>();
+
+        for (Hit hit : response.hits().hits()) {
+            Document doc = mapFromEsHit(hit);
+            if (doc != null) {
+                results.add(doc);
+            }
+        }
+        return results;
+    }
+
+    /**
+     * Deletes a document from the Elasticsearch index by its ID.
+     *
+     * @param id the ID of the document to delete
+     * @return a Mono containing true if the document was deleted, false if not found
+     */
+    @Override
+    public Mono delete(String id) {
+        if (id == null || id.trim().isEmpty()) {
+            return Mono.error(new IllegalArgumentException("Document ID cannot be null or empty"));
+        }
+
+        return Mono.fromCallable(
+                        () -> {
+                            ensureNotClosed();
+                            return client.delete(d -> d.index(indexName).id(id));
+                        })
+                .subscribeOn(Schedulers.boundedElastic())
+                .map(response -> response.result().name().equals("Deleted"))
+                .onErrorMap(
+                        e ->
+                                new VectorStoreException(
+                                        "Failed to delete document from Elasticsearch", e));
+    }
+
+    @Override
+    public void close() {
+        closeQuietly();
+    }
+
+    private void closeQuietly() {
+        if (closed) return;
+        synchronized (this) {
+            if (closed) return;
+            closed = true;
+            try {
+                if (transport != null) transport.close();
+                if (restClient != null) restClient.close();
+                log.debug("ElasticsearchStore closed for index: {}", indexName);
+            } catch (Exception e) {
+                log.warn("Error closing Elasticsearch client", e);
+            }
+        }
+    }
+
+    private void ensureNotClosed() throws VectorStoreException {
+        if (closed) {
+            throw new VectorStoreException("ElasticsearchStore has been closed");
+        }
+    }
+
+    private void ensureIndex() throws VectorStoreException {
+        try {
+            ExistsRequest existsRequest = new ExistsRequest.Builder().index(indexName).build();
+
+            boolean exists = client.indices().exists(existsRequest).value();
+            if (exists) {
+                log.debug("Index '{}' already exists", indexName);
+                return;
+            }
+
+            log.debug("Creating index '{}' with dimensions {}", indexName, dimensions);
+
+            // Define field mappings
+            Property idProperty =
+                    new Property.Builder().keyword(new KeywordProperty.Builder().build()).build();
+
+            Property contentProperty =
+                    new Property.Builder()
+                            .text(new TextProperty.Builder().index(false).build())
+                            .build();
+
+            Property vectorProperty =
+                    new Property.Builder()
+                            .denseVector(
+                                    new DenseVectorProperty.Builder()
+                                            .dims(dimensions)
+                                            .index(true)
+                                            .similarity("cosine")
+                                            .build())
+                            .build();
+
+            Map properties = new HashMap<>();
+            properties.put(FIELD_ID, idProperty);
+            properties.put(FIELD_DOC_ID, idProperty);
+            properties.put(FIELD_CHUNK_ID, idProperty);
+            properties.put(FIELD_CONTENT, contentProperty);
+            properties.put(FIELD_VECTOR, vectorProperty);
+
+            TypeMapping mapping = new TypeMapping.Builder().properties(properties).build();
+
+            CreateIndexRequest createRequest =
+                    new CreateIndexRequest.Builder().index(indexName).mappings(mapping).build();
+
+            client.indices().create(createRequest);
+        } catch (Exception e) {
+            throw new VectorStoreException("Failed to ensure index exists: " + indexName, e);
+        }
+    }
+
+    private void validateDocument(Document document) throws VectorStoreException {
+        if (document == null) {
+            throw new IllegalArgumentException("Document cannot be null");
+        }
+        if (document.getEmbedding() == null) {
+            throw new IllegalArgumentException("Document must have embedding set");
+        }
+        if (document.getEmbedding().length != dimensions) {
+            throw new VectorStoreException(
+                    String.format(
+                            "Embedding dimension mismatch: expected %d, got %d",
+                            dimensions, document.getEmbedding().length));
+        }
+    }
+
+    private Map mapToEsDocument(Document doc) {
+        Map map = new HashMap<>();
+        map.put(FIELD_ID, doc.getId());
+
+        // Convert embedding to list
+        List embedding = new ArrayList<>(doc.getEmbedding().length);
+        for (double d : doc.getEmbedding()) {
+            embedding.add((float) d);
+        }
+        map.put(FIELD_VECTOR, embedding);
+
+        // Metadata
+        DocumentMetadata meta = doc.getMetadata();
+        map.put(FIELD_DOC_ID, meta.getDocId());
+        map.put(FIELD_CHUNK_ID, meta.getChunkId());
+
+        // Serialize ContentBlock to JSON string to ensure safe storage/retrieval
+        try {
+            String contentJson = OBJECT_MAPPER.writeValueAsString(meta.getContent());
+            map.put(FIELD_CONTENT, contentJson);
+        } catch (Exception e) {
+            log.warn("Failed to serialize content, using text representation", e);
+            map.put(FIELD_CONTENT, meta.getContentText());
+        }
+
+        return map;
+    }
+
+    @SuppressWarnings("unchecked")
+    private Document mapFromEsHit(Hit hit) {
+        try {
+            Map source = hit.source();
+            if (source == null) return null;
+
+            String docId = (String) source.get(FIELD_DOC_ID);
+            String chunkId = (String) source.get(FIELD_CHUNK_ID);
+            String contentJson = (String) source.get(FIELD_CONTENT);
+
+            // Reconstruct ContentBlock
+            ContentBlock content;
+            try {
+                content = OBJECT_MAPPER.readValue(contentJson, ContentBlock.class);
+            } catch (Exception e) {
+                log.debug("Failed to deserialize ContentBlock, creating TextBlock", e);
+                content = TextBlock.builder().text(contentJson).build();
+            }
+
+            DocumentMetadata metadata = new DocumentMetadata(content, docId, chunkId);
+            Document doc = new Document(metadata);
+
+            // Set score if present
+            if (hit.score() != null) {
+                doc.setScore(hit.score());
+            }
+
+            // Extract embedding if we requested source (default is yes)
+            // Note: In some RAG flows we might not strictly need the vector back,
+            // but if available, we parse it.
+            if (source.containsKey(FIELD_VECTOR)) {
+                Object vecObj = source.get(FIELD_VECTOR);
+                if (vecObj instanceof List) {
+                    List vecList = (List) vecObj;
+                    double[] embedding = new double[vecList.size()];
+                    for (int i = 0; i < vecList.size(); i++) {
+                        embedding[i] = vecList.get(i).doubleValue();
+                    }
+                    doc.setEmbedding(embedding);
+                }
+            }
+            return doc;
+        } catch (Exception e) {
+            log.error("Failed to map Elasticsearch hit to Document", e);
+            return null;
+        }
+    }
+
+    /**
+     * Creates a new builder for ElasticsearchStore.
+     * @return a new Builder instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder for ElasticsearchStore.
+     */
+    public static class Builder {
+        private String url = "http://localhost:9200";
+        private String indexName;
+        private int dimensions;
+        private String username;
+        private String password;
+        private boolean disableSslVerification = false;
+
+        private Builder() {}
+
+        /**
+         * Sets the Elasticsearch connection URL.
+         * @param url the URL
+         * @return the builder
+         */
+        public Builder url(String url) {
+            this.url = url;
+            return this;
+        }
+
+        /**
+         * Sets the index name.
+         * @param indexName the index name
+         * @return the builder
+         */
+        public Builder indexName(String indexName) {
+            this.indexName = indexName;
+            return this;
+        }
+
+        /**
+         * Sets the vector dimensions.
+         * @param dimensions the number of dimensions
+         * @return the builder
+         */
+        public Builder dimensions(int dimensions) {
+            this.dimensions = dimensions;
+            return this;
+        }
+
+        /**
+         * Sets the username for authentication.
+         * @param username the username
+         * @return the builder
+         */
+        public Builder username(String username) {
+            this.username = username;
+            return this;
+        }
+
+        /**
+         * Sets the password for authentication.
+         * @param password the password
+         * @return the builder
+         */
+        public Builder password(String password) {
+            this.password = password;
+            return this;
+        }
+
+        /**
+         * Sets whether to disable SSL verification.
+         * 
    Warning: Disabling SSL verification is insecure and should only be used for development.
+         * @param disableSslVerification true to disable verification
+         * @return the builder
+         */
+        public Builder disableSslVerification(boolean disableSslVerification) {
+            this.disableSslVerification = disableSslVerification;
+            return this;
+        }
+
+        /**
+         * Builds the ElasticsearchStore instance.
+         * @return the store instance
+         * @throws VectorStoreException if configuration is invalid
+         */
+        public ElasticsearchStore build() throws VectorStoreException {
+            if (url == null || url.trim().isEmpty()) {
+                throw new IllegalArgumentException("URL cannot be null or empty");
+            }
+            if (indexName == null || indexName.trim().isEmpty()) {
+                throw new IllegalArgumentException("Index name cannot be null or empty");
+            }
+            if (dimensions <= 0) {
+                throw new IllegalArgumentException("Dimensions must be positive");
+            }
+            return new ElasticsearchStore(this);
+        }
+    }
+}
diff --git a/agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/store/ElasticsearchStoreTest.java b/agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/store/ElasticsearchStoreTest.java
new file mode 100644
index 000000000..c7df80af4
--- /dev/null
+++ b/agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/store/ElasticsearchStoreTest.java
@@ -0,0 +1,532 @@
+/*
+ * 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.rag.store;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockConstruction;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import co.elastic.clients.elasticsearch.ElasticsearchClient;
+import co.elastic.clients.elasticsearch._types.Result;
+import co.elastic.clients.elasticsearch._types.mapping.Property;
+import co.elastic.clients.elasticsearch.core.BulkRequest;
+import co.elastic.clients.elasticsearch.core.BulkResponse;
+import co.elastic.clients.elasticsearch.core.DeleteResponse;
+import co.elastic.clients.elasticsearch.core.SearchRequest;
+import co.elastic.clients.elasticsearch.core.SearchResponse;
+import co.elastic.clients.elasticsearch.core.search.Hit;
+import co.elastic.clients.elasticsearch.core.search.HitsMetadata;
+import co.elastic.clients.elasticsearch.indices.CreateIndexRequest;
+import co.elastic.clients.elasticsearch.indices.CreateIndexResponse;
+import co.elastic.clients.elasticsearch.indices.ElasticsearchIndicesClient;
+import co.elastic.clients.elasticsearch.indices.ExistsRequest;
+import co.elastic.clients.transport.endpoints.BooleanResponse;
+import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.rag.exception.VectorStoreException;
+import io.agentscope.core.rag.model.Document;
+import io.agentscope.core.rag.model.DocumentMetadata;
+import io.agentscope.core.rag.store.dto.SearchDocumentDto;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.MockedConstruction;
+import reactor.test.StepVerifier;
+
+@Tag("unit")
+@DisplayName("ElasticsearchStore Unit Tests")
+public class ElasticsearchStoreTest {
+    private static final String TEST_URL = "http://localhost:9200";
+    private static final String TEST_INDEX = "test_index";
+    private static final int TEST_DIMENSIONS = 1536;
+
+    private ElasticsearchStore store;
+
+    @AfterEach
+    void tearDown() {
+        if (store != null) {
+            store.close();
+            store = null;
+        }
+    }
+
+    // ==================== Builder Validation Tests ====================
+
+    @Test
+    @DisplayName("Should create builder instance")
+    void testBuilderCreation() {
+        ElasticsearchStore.Builder builder = ElasticsearchStore.builder();
+        assertNotNull(builder);
+    }
+
+    @Test
+    @DisplayName("Should throw exception for null URL")
+    void testNullUrl() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ElasticsearchStore.builder()
+                                .url(null)
+                                .indexName(TEST_INDEX)
+                                .dimensions(TEST_DIMENSIONS)
+                                .build());
+    }
+
+    @Test
+    @DisplayName("Should throw exception for empty URL")
+    void testEmptyUrl() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ElasticsearchStore.builder()
+                                .url("")
+                                .indexName(TEST_INDEX)
+                                .dimensions(TEST_DIMENSIONS)
+                                .build());
+    }
+
+    @Test
+    @DisplayName("Should throw exception for null index name")
+    void testNullIndexName() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ElasticsearchStore.builder()
+                                .url(TEST_URL)
+                                .indexName(null)
+                                .dimensions(TEST_DIMENSIONS)
+                                .build());
+    }
+
+    @Test
+    @DisplayName("Should throw exception for zero dimensions")
+    void testZeroDimensions() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        ElasticsearchStore.builder()
+                                .url(TEST_URL)
+                                .indexName(TEST_INDEX)
+                                .dimensions(0)
+                                .build());
+    }
+
+    // ==================== Mock-based Functional Tests ====================
+
+    /**
+     * Helper to create a store with a mock ElasticsearchClient.
+     * This mocks the constructor initialization including ensureIndex().
+     */
+    private ElasticsearchStore createMockStore() throws VectorStoreException {
+        // We mock the construction of ElasticsearchClient
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            // Mock indices client for ensureIndex()
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+
+                            // Mock index exists check -> return true to skip creation logic
+                            BooleanResponse boolResp = mock(BooleanResponse.class);
+                            when(boolResp.value()).thenReturn(true);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(boolResp);
+                        })) {
+            return ElasticsearchStore.builder()
+                    .url(TEST_URL)
+                    .indexName(TEST_INDEX)
+                    .dimensions(TEST_DIMENSIONS)
+                    .build();
+        }
+    }
+
+    @Test
+    @DisplayName("Should build store with mock client")
+    void testBuildWithMockClient() throws VectorStoreException {
+        store = createMockStore();
+        assertNotNull(store);
+    }
+
+    @Test
+    @DisplayName("Should close store successfully")
+    void testCloseStore() throws VectorStoreException {
+        store = createMockStore();
+        store.close();
+        // ElasticsearchStore doesn't expose isClosed(), but we verify no exception is thrown
+    }
+
+    @Test
+    @DisplayName("Should configure SSL context when URL starts with https")
+    void testBuildWithHttpsUrl() throws VectorStoreException {
+        // Mock the construction process to avoid real network connections
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            // Mock index check to avoid throwing exceptions in the constructor
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+                            BooleanResponse boolResp = mock(BooleanResponse.class);
+                            when(boolResp.value()).thenReturn(true);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(boolResp);
+                        })) {
+
+            // 1. Set HTTPS URL and authentication credentials
+            // This will cover the code paths for SSL handling and setDefaultCredentialsProvider in
+            // the ElasticsearchStore constructor
+            ElasticsearchStore httpsStore =
+                    ElasticsearchStore.builder()
+                            .url("https://localhost:9200")
+                            .indexName(TEST_INDEX)
+                            .dimensions(TEST_DIMENSIONS)
+                            .username("admin")
+                            .password("secret")
+                            .disableSslVerification(true)
+                            .build();
+
+            assertNotNull(httpsStore);
+            httpsStore.close();
+        }
+    }
+
+    @Test
+    @DisplayName("Should create index with correct mappings when index does not exist")
+    void testEnsureIndexCreatesIndex() throws VectorStoreException, IOException {
+        // Use MockedConstruction to intercept the creation of ElasticsearchClient
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+
+                            // 1. Mock exists() to return false, forcing entry into the index
+                            // creation branch
+                            BooleanResponse existsResp = mock(BooleanResponse.class);
+                            when(existsResp.value()).thenReturn(false);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(existsResp);
+
+                            // 2. Mock create() call to prevent NullPointerException
+                            CreateIndexResponse createResp = mock(CreateIndexResponse.class);
+                            when(indicesClient.create(any(CreateIndexRequest.class)))
+                                    .thenReturn(createResp);
+                        })) {
+
+            // Initialize Store, which triggers ensureIndex() in the constructor
+            ElasticsearchStore newStore =
+                    ElasticsearchStore.builder()
+                            .url(TEST_URL)
+                            .indexName(TEST_INDEX)
+                            .dimensions(TEST_DIMENSIONS)
+                            .build();
+
+            // Get the Mock object for verification
+            ElasticsearchClient mockClient = ignored.constructed().get(0);
+            ElasticsearchIndicesClient indicesClient = mockClient.indices();
+
+            // 3. Capture CreateIndexRequest parameters to verify Mapping settings
+            ArgumentCaptor captor =
+                    ArgumentCaptor.forClass(CreateIndexRequest.class);
+            verify(indicesClient).create(captor.capture());
+
+            CreateIndexRequest request = captor.getValue();
+
+            // Verify index name
+            assertEquals(TEST_INDEX, request.index());
+
+            // Verify key properties (Coverage for lines 154-160)
+            Map props = request.mappings().properties();
+
+            // Verify Vector field
+            assertTrue(props.containsKey("vector"), "Should contain vector field");
+            Property vectorProp = props.get("vector");
+            assertTrue(vectorProp.isDenseVector());
+            assertEquals(TEST_DIMENSIONS, vectorProp.denseVector().dims());
+            assertEquals("cosine", vectorProp.denseVector().similarity());
+            assertTrue(vectorProp.denseVector().index());
+
+            // Verify Content field
+            assertTrue(props.containsKey("content"), "Should contain content field");
+            assertTrue(props.get("content").isText());
+            assertEquals(Boolean.FALSE, props.get("content").text().index());
+
+            // Verify ID field
+            assertTrue(props.containsKey("id"), "Should contain id field");
+            assertTrue(props.get("id").isKeyword());
+
+            newStore.close();
+        }
+    }
+
+    // ==================== Add Method Tests ====================
+
+    private ElasticsearchStore createMockStoreForAdd(boolean success) throws VectorStoreException {
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            // Handle ensureIndex
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+                            BooleanResponse boolResp = mock(BooleanResponse.class);
+                            when(boolResp.value()).thenReturn(true);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(boolResp);
+
+                            // Handle Bulk
+                            BulkResponse bulkResp = mock(BulkResponse.class);
+                            when(bulkResp.errors()).thenReturn(!success);
+                            // If failure, the store iterates items, but for simple test we just
+                            // verify exception on error
+                            when(bulkResp.items()).thenReturn(Collections.emptyList());
+                            when(mock.bulk(any(BulkRequest.class))).thenReturn(bulkResp);
+                        })) {
+            return ElasticsearchStore.builder()
+                    .url(TEST_URL)
+                    .indexName(TEST_INDEX)
+                    .dimensions(TEST_DIMENSIONS)
+                    .build();
+        }
+    }
+
+    @Test
+    @DisplayName("Should complete for empty documents list")
+    void testAddEmptyDocuments() throws VectorStoreException {
+        store = createMockStoreForAdd(true);
+        StepVerifier.create(store.add(List.of())).verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Should add documents successfully")
+    void testAddSuccess() throws VectorStoreException {
+        store = createMockStoreForAdd(true);
+
+        TextBlock content = TextBlock.builder().text("Test content").build();
+        DocumentMetadata metadata = new DocumentMetadata(content, "doc-1", "chunk-1");
+        Document doc = new Document(metadata);
+        doc.setEmbedding(new double[TEST_DIMENSIONS]);
+
+        StepVerifier.create(store.add(List.of(doc))).verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Should throw exception on bulk error")
+    void testAddFailure() throws VectorStoreException {
+        store = createMockStoreForAdd(false); // Simulated failure
+
+        TextBlock content = TextBlock.builder().text("Test content").build();
+        DocumentMetadata metadata = new DocumentMetadata(content, "doc-1", "chunk-1");
+        Document doc = new Document(metadata);
+        doc.setEmbedding(new double[TEST_DIMENSIONS]);
+
+        StepVerifier.create(store.add(List.of(doc)))
+                .expectError(VectorStoreException.class)
+                .verify();
+    }
+
+    @Test
+    @DisplayName("Should validate document dimensions")
+    void testAddDimensionMismatch() throws VectorStoreException {
+        store = createMockStoreForAdd(true);
+
+        TextBlock content = TextBlock.builder().text("Test").build();
+        DocumentMetadata metadata = new DocumentMetadata(content, "doc-1", "0");
+        Document doc = new Document(metadata);
+        doc.setEmbedding(new double[1]); // Wrong dimension
+
+        StepVerifier.create(store.add(List.of(doc)))
+                .expectError(VectorStoreException.class)
+                .verify();
+    }
+
+    // ==================== Search Method Tests ====================
+
+    @SuppressWarnings("unchecked")
+    private ElasticsearchStore createMockStoreForSearch(List> mockHits)
+            throws VectorStoreException {
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            // Handle ensureIndex
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+                            BooleanResponse boolResp = mock(BooleanResponse.class);
+                            when(boolResp.value()).thenReturn(true);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(boolResp);
+
+                            // Handle Search
+                            SearchResponse searchResp = mock(SearchResponse.class);
+                            HitsMetadata hitsMetadata = mock(HitsMetadata.class);
+                            List> hitList = new ArrayList<>();
+
+                            for (Map source : mockHits) {
+                                Hit hit = mock(Hit.class);
+                                when(hit.source()).thenReturn(source);
+                                when(hit.score()).thenReturn(0.95);
+                                hitList.add(hit);
+                            }
+
+                            when(hitsMetadata.hits()).thenReturn(hitList);
+                            when(searchResp.hits()).thenReturn(hitsMetadata);
+
+                            // Mocking the generic search call
+                            when(mock.search(any(SearchRequest.class), eq(Map.class)))
+                                    .thenReturn(searchResp);
+                        })) {
+            return ElasticsearchStore.builder()
+                    .url(TEST_URL)
+                    .indexName(TEST_INDEX)
+                    .dimensions(TEST_DIMENSIONS)
+                    .build();
+        }
+    }
+
+    @Test
+    @DisplayName("Should search successfully")
+    void testSearchSuccess() throws VectorStoreException {
+        // Prepare mock result
+        Map source = new HashMap<>();
+        source.put("doc_id", "doc-1");
+        source.put("chunk_id", "0");
+        source.put("content", "{\"type\":\"text\",\"text\":\"content\"}");
+        // Mock vector return
+        List vector = new ArrayList<>();
+        for (int i = 0; i < TEST_DIMENSIONS; i++) vector.add(0.0);
+        source.put("vector", vector);
+
+        store = createMockStoreForSearch(List.of(source));
+
+        double[] query = new double[TEST_DIMENSIONS];
+        StepVerifier.create(
+                        store.search(
+                                SearchDocumentDto.builder()
+                                        .queryEmbedding(query)
+                                        .limit(5)
+                                        .scoreThreshold(0.5)
+                                        .build()))
+                .assertNext(
+                        results -> {
+                            assertNotNull(results);
+                            assertEquals(1, results.size());
+                            assertEquals("doc-1", results.get(0).getMetadata().getDocId());
+                            assertEquals(0.95, results.get(0).getScore());
+                        })
+                .verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Should throw exception for dimension mismatch in query")
+    void testSearchDimensionMismatch() throws VectorStoreException {
+        store = createMockStoreForSearch(Collections.emptyList());
+        double[] query = new double[1]; // Wrong dimension
+
+        StepVerifier.create(
+                        store.search(
+                                SearchDocumentDto.builder()
+                                        .queryEmbedding(query)
+                                        .limit(5)
+                                        .scoreThreshold(null)
+                                        .build()))
+                .expectError(VectorStoreException.class)
+                .verify();
+    }
+
+    // ==================== Delete Method Tests ====================
+
+    private ElasticsearchStore createMockStoreForDelete(boolean deleted)
+            throws VectorStoreException {
+        try (MockedConstruction ignored =
+                mockConstruction(
+                        ElasticsearchClient.class,
+                        (mock, context) -> {
+                            // Handle ensureIndex
+                            ElasticsearchIndicesClient indicesClient =
+                                    mock(ElasticsearchIndicesClient.class);
+                            when(mock.indices()).thenReturn(indicesClient);
+                            BooleanResponse boolResp = mock(BooleanResponse.class);
+                            when(boolResp.value()).thenReturn(true);
+                            when(indicesClient.exists(any(ExistsRequest.class)))
+                                    .thenReturn(boolResp);
+
+                            // Handle Delete
+                            DeleteResponse deleteResp = mock(DeleteResponse.class);
+                            Result result = deleted ? Result.Deleted : Result.NotFound;
+                            when(deleteResp.result()).thenReturn(result);
+
+                            // when(mock.delete(any(DeleteRequest.class))).thenReturn(deleteResp);
+                            when(mock.delete(any(Function.class))).thenReturn(deleteResp);
+                        })) {
+            return ElasticsearchStore.builder()
+                    .url(TEST_URL)
+                    .indexName(TEST_INDEX)
+                    .dimensions(TEST_DIMENSIONS)
+                    .build();
+        }
+    }
+
+    @Test
+    @DisplayName("Should delete document successfully")
+    void testDeleteSuccess() throws VectorStoreException {
+        store = createMockStoreForDelete(true);
+        StepVerifier.create(store.delete("doc-1"))
+                .assertNext(Assertions::assertTrue)
+                .verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Should return false when document not found")
+    void testDeleteNotFound() throws VectorStoreException {
+        store = createMockStoreForDelete(false);
+        StepVerifier.create(store.delete("doc-1"))
+                .assertNext(Assertions::assertFalse)
+                .verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Should throw exception for null ID")
+    void testDeleteNullId() throws VectorStoreException {
+        store = createMockStoreForDelete(true);
+        StepVerifier.create(store.delete(null))
+                .expectError(IllegalArgumentException.class)
+                .verify();
+    }
+}
diff --git a/docs/en/quickstart/installation.md b/docs/en/quickstart/installation.md
index 781a9edab..80249f395 100644
--- a/docs/en/quickstart/installation.md
+++ b/docs/en/quickstart/installation.md
@@ -57,6 +57,7 @@ When using other models or features, add the corresponding dependencies:
 | **Dify RAG**              | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
 | **RAGFlow RAG**           | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
 | **HayStack RAG**          | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
+| **Elasticsearch RAG** | [Elasticsearch Java Client](https://www.elastic.co/docs/reference/elasticsearch/clients/java)   |`co.elastic.clients:elasticsearch-java` |
 | **MySQL Session**         | [MySQL Connector](https://central.sonatype.com/artifact/com.mysql/mysql-connector-j)     | `com.mysql:mysql-connector-j`    |
 | **Redis Session**         | [Jedis](https://central.sonatype.com/artifact/redis.clients/jedis)                       | `redis.clients:jedis`            |
 | **PDF Processing**        | [Apache PDFBox](https://central.sonatype.com/artifact/org.apache.pdfbox/pdfbox)          | `org.apache.pdfbox:pdfbox`       |
@@ -158,7 +159,7 @@ implementation 'io.agentscope:agentscope-core:1.0.7'
 | Module | Feature | Maven Coordinates |
 |--------|---------|-------------------|
 | [agentscope-extensions-rag-bailian](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-bailian) | Bailian RAG | `io.agentscope:agentscope-extensions-rag-bailian` |
-| [agentscope-extensions-rag-simple](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-simple) | Simple RAG (Qdrant, Milvus, PgVector, InMemory) | `io.agentscope:agentscope-extensions-rag-simple` |
+| [agentscope-extensions-rag-simple](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-simple) | Simple RAG (Qdrant, Milvus, PgVector, InMemory, Elasticsearch) | `io.agentscope:agentscope-extensions-rag-simple` |
 | [agentscope-extensions-rag-dify](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-dify) | Dify RAG | `io.agentscope:agentscope-extensions-rag-dify` |
 | [agentscope-extensions-rag-ragflow](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-ragflow) | RAGFlow RAG | `io.agentscope:agentscope-extensions-rag-ragflow` |
 | [agentscope-extensions-rag-haystack](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-haystack) | HayStack RAG | `io.agentscope:agentscope-extensions-rag-haystack` |
diff --git a/docs/en/task/rag.md b/docs/en/task/rag.md
index 246e1507f..503960953 100644
--- a/docs/en/task/rag.md
+++ b/docs/en/task/rag.md
@@ -540,7 +540,7 @@ public class CustomReader implements Reader {
 6. **Vector Store Selection**:
    - Use **InMemoryStore**: Development, testing, small datasets (<10K documents)
    - Use **QdrantStore**: Production, large datasets, persistence required
-
+   - Use **ElasticsearchStore**: Production environments, large-scale datasets, and self-hosted (private deployment) services.
 
 ## Complete Examples
 
@@ -548,4 +548,6 @@ public class CustomReader implements Reader {
 - **Bailian Knowledge Base Example**: [BailianRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/BailianRAGExample.java)
 - **Dify Knowledge Base Example**: [DifyRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/DifyRAGExample.java)
 - **RAGFlow Knowledge Base Example**: [RAGFlowRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/RAGFlowRAGExample.java)
-- **PgVector Knowledge Base Example**: [PgVectorRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/PgVectorRAGExample.java)
\ No newline at end of file
+- **Elasticsearch Knowledge Base Example**: [ElasticsearchRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java)
+- **PgVector Knowledge Base Example**: [PgVectorRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/PgVectorRAGExample.java)
+- 
\ No newline at end of file
diff --git a/docs/zh/quickstart/installation.md b/docs/zh/quickstart/installation.md
index 4d841500b..30558a905 100644
--- a/docs/zh/quickstart/installation.md
+++ b/docs/zh/quickstart/installation.md
@@ -59,6 +59,7 @@ All-in-one 包默认带以下依赖，不用额外配置：
 | **Dify RAG**         | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
 | **RAGFlow RAG**      | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
 | **HayStack RAG**     | [OkHttp](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp)              | `com.squareup.okhttp3:okhttp`    |
+| **Elasticsearch RAG** | [Elasticsearch Java Client](https://www.elastic.co/docs/reference/elasticsearch/clients/java)   |`co.elastic.clients:elasticsearch-java` |
 | **MySQL Session**    | [MySQL Connector](https://central.sonatype.com/artifact/com.mysql/mysql-connector-j)     | `com.mysql:mysql-connector-j`    |
 | **Redis Session**    | [Jedis](https://central.sonatype.com/artifact/redis.clients/jedis)                       | `redis.clients:jedis`            |
 | **PDF 处理**           | [Apache PDFBox](https://central.sonatype.com/artifact/org.apache.pdfbox/pdfbox)          | `org.apache.pdfbox:pdfbox`       |
@@ -162,7 +163,7 @@ implementation 'io.agentscope:agentscope-core:1.0.7'
 | 模块 | 功能 | Maven 坐标 |
 |-----|------|-----------|
 | [agentscope-extensions-rag-bailian](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-bailian) | 百炼 RAG | `io.agentscope:agentscope-extensions-rag-bailian` |
-| [agentscope-extensions-rag-simple](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-simple) | 简单 RAG (Qdrant, Milvus, PgVector, 内存存储) | `io.agentscope:agentscope-extensions-rag-simple` |
+| [agentscope-extensions-rag-simple](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-simple) | 简单 RAG (Qdrant, Milvus, PgVector, 内存存储, Elasticsearch) | `io.agentscope:agentscope-extensions-rag-simple` |
 | [agentscope-extensions-rag-dify](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-dify) | Dify RAG | `io.agentscope:agentscope-extensions-rag-dify` |
 | [agentscope-extensions-rag-ragflow](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-ragflow) | RAGFlow RAG | `io.agentscope:agentscope-extensions-rag-ragflow` |
 | [agentscope-extensions-rag-haystack](https://central.sonatype.com/artifact/io.agentscope/agentscope-extensions-rag-haystack) | HayStack RAG | `io.agentscope:agentscope-extensions-rag-haystack` |
diff --git a/docs/zh/task/rag.md b/docs/zh/task/rag.md
index f86b0ff4e..9a40f25b1 100644
--- a/docs/zh/task/rag.md
+++ b/docs/zh/task/rag.md
@@ -540,7 +540,7 @@ public class CustomReader implements Reader {
 6. **向量存储选择**：
    - 使用 **InMemoryStore**：开发、测试、小型数据集（<10K 文档）
    - 使用 **QdrantStore**：生产环境、大型数据集、需要持久化
-
+   - 使用 **ElasticsearchStore**: 生产环境、大型数据集、私有部署服务。
 
 ## 完整示例
 
@@ -548,4 +548,5 @@ public class CustomReader implements Reader {
 - **百炼知识库示例**: [BailianRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/BailianRAGExample.java)
 - **Dify 知识库示例**: [DifyRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/DifyRAGExample.java)
 - **RAGFlow 知识库示例**: [RAGFlowRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/RAGFlowRAGExample.java)
+- **Elasticsearch 知识库实例**: [ElasticsearchRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/ElasticsearchRAGExample.java)
 - **PgVector 知识库示例**: [PgVectorRAGExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/PgVectorRAGExample.java)

From 7fff15e4fec175c6856d9b3c7c336e78c0fa0384 Mon Sep 17 00:00:00 2001
From: guanxu <86234262+guanxuc@users.noreply.github.com>
Date: Wed, 21 Jan 2026 11:06:40 +0800
Subject: [PATCH 26/53] feat(model): Support response_format for dashscope
 model (#564)

## AgentScope-Java Version

1.0.8

## Description

* Closes: #523
* Support response_format for dashscope model

## Key Changes
* Support response_format by add response_format for
GenerateOptions#additionalBodyParams.
* Move io.agentscope.core.formatter.openai.dto.ResponseFormat to
io.agentscope.core.formatter.ResponseFormat for both openai and
dashscope.
* Fix dashscope build requestBody method, the additional params should
be added to dashscope parameters instead of request.

## Checklist

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

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review
---
 .../{openai/dto => }/ResponseFormat.java      |  3 +-
 .../dashscope/dto/DashScopeParameters.java    | 18 ++++++
 .../formatter/openai/OpenAIChatFormatter.java |  6 ++
 .../formatter/openai/dto/OpenAIRequest.java   |  2 +-
 .../core/model/DashScopeHttpClient.java       | 15 +++--
 .../core/model/OpenAIChatModel.java           |  4 +-
 .../{openai/dto => }/ResponseFormatTest.java  |  3 +-
 .../openai/OpenAIChatFormatterTest.java       | 52 ++++++++++++++++
 .../core/model/DashScopeHttpClientTest.java   | 60 +++++++++++++++++++
 9 files changed, 154 insertions(+), 9 deletions(-)
 rename agentscope-core/src/main/java/io/agentscope/core/formatter/{openai/dto => }/ResponseFormat.java (97%)
 rename agentscope-core/src/test/java/io/agentscope/core/formatter/{openai/dto => }/ResponseFormatTest.java (99%)

diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/ResponseFormat.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/ResponseFormat.java
similarity index 97%
rename from agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/ResponseFormat.java
rename to agentscope-core/src/main/java/io/agentscope/core/formatter/ResponseFormat.java
index 30e44200b..361a2db7e 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/ResponseFormat.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/ResponseFormat.java
@@ -13,10 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.agentscope.core.formatter.openai.dto;
+package io.agentscope.core.formatter;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.agentscope.core.formatter.openai.dto.JsonSchema;
 
 /**
  * Response format configuration for OpenAI API.
diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/dto/DashScopeParameters.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/dto/DashScopeParameters.java
index fefd4beec..520b9632b 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/dto/DashScopeParameters.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/dto/DashScopeParameters.java
@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.agentscope.core.formatter.ResponseFormat;
 import java.util.List;
 
 /**
@@ -94,6 +95,10 @@ public class DashScopeParameters {
     @JsonProperty("repetition_penalty")
     private Double repetitionPenalty;
 
+    /** The configuration for the llm response format. */
+    @JsonProperty("response_format")
+    ResponseFormat responseFormat;
+
     public DashScopeParameters() {}
 
     public String getResultFormat() {
@@ -224,6 +229,14 @@ public void setRepetitionPenalty(Double repetitionPenalty) {
         this.repetitionPenalty = repetitionPenalty;
     }
 
+    public ResponseFormat getResponseFormat() {
+        return responseFormat;
+    }
+
+    public void setResponseFormat(ResponseFormat responseFormat) {
+        this.responseFormat = responseFormat;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -306,6 +319,11 @@ public Builder repetitionPenalty(Double repetitionPenalty) {
             return this;
         }
 
+        public Builder responseFormat(ResponseFormat responseFormat) {
+            params.setResponseFormat(responseFormat);
+            return this;
+        }
+
         public DashScopeParameters build() {
             return params;
         }
diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIChatFormatter.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIChatFormatter.java
index f891183f7..6155fd313 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIChatFormatter.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIChatFormatter.java
@@ -15,6 +15,7 @@
  */
 package io.agentscope.core.formatter.openai;
 
+import io.agentscope.core.formatter.ResponseFormat;
 import io.agentscope.core.formatter.openai.dto.OpenAIMessage;
 import io.agentscope.core.formatter.openai.dto.OpenAIRequest;
 import io.agentscope.core.formatter.openai.dto.OpenAITool;
@@ -240,6 +241,11 @@ protected void applyAdditionalBodyParams(OpenAIRequest request, GenerateOptions
                             Map formatMap = (Map) value;
                             request.setResponseFormat(formatMap);
                         }
+
+                        if (value instanceof ResponseFormat responseFormat) {
+                            request.setResponseFormat(responseFormat);
+                        }
+
                         break;
                     default:
                         // Add unknown parameters to extraParams
diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/OpenAIRequest.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/OpenAIRequest.java
index 89bc9121d..e007a46a2 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/OpenAIRequest.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/openai/dto/OpenAIRequest.java
@@ -165,7 +165,7 @@ public class OpenAIRequest {
      * Example: ["text", "audio"]
      */
     @JsonProperty("modalities")
-    private java.util.List modalities;
+    private List modalities;
 
     /**
      * Audio output configuration.
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java b/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java
index 04ffce909..5c2689fb1 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/DashScopeHttpClient.java
@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import io.agentscope.core.Version;
+import io.agentscope.core.formatter.dashscope.dto.DashScopeParameters;
 import io.agentscope.core.formatter.dashscope.dto.DashScopePublicKeyResponse;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeRequest;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeResponse;
@@ -476,12 +477,18 @@ private String buildRequestBody(
         }
 
         // Deserialize to Map, merge additional params, re-serialize
+        // The additional params should be added to dashscope parameters
+        DashScopeParameters parameters = request.getParameters();
+        String parametersJson = JsonUtils.getJsonCodec().toJson(parameters);
+        Map parametersMap =
+                JsonUtils.getJsonCodec().fromJson(parametersJson, new TypeReference<>() {});
+        parametersMap.putAll(additionalBodyParams);
+
+        // Set the merged parameters to dashscope request body map
         Map bodyMap =
-                JsonUtils.getJsonCodec()
-                        .fromJson(requestBody, new TypeReference>() {});
-        bodyMap.putAll(additionalBodyParams);
+                JsonUtils.getJsonCodec().fromJson(requestBody, new TypeReference<>() {});
+        bodyMap.put("parameters", parametersMap);
         requestBody = JsonUtils.getJsonCodec().toJson(bodyMap);
-
         return requestBody;
     }
 
diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/OpenAIChatModel.java b/agentscope-core/src/main/java/io/agentscope/core/model/OpenAIChatModel.java
index 2d22f01f0..9f3391fbe 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/model/OpenAIChatModel.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/model/OpenAIChatModel.java
@@ -20,6 +20,7 @@
 import io.agentscope.core.formatter.openai.dto.OpenAIMessage;
 import io.agentscope.core.formatter.openai.dto.OpenAIRequest;
 import io.agentscope.core.formatter.openai.dto.OpenAIResponse;
+import io.agentscope.core.formatter.openai.dto.OpenAIStreamOptions;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.model.transport.HttpTransport;
 import io.agentscope.core.model.transport.HttpTransportFactory;
@@ -122,8 +123,7 @@ protected Flux doStream0(
         // This ensures token usage information is available in the final response chunk
         // Required by OpenAI-compatible APIs like DashScope, Bailian, etc.
         if (stream) {
-            requestBuilder.streamOptions(
-                    new io.agentscope.core.formatter.openai.dto.OpenAIStreamOptions(true));
+            requestBuilder.streamOptions(new OpenAIStreamOptions(true));
         }
 
         OpenAIRequest request = requestBuilder.build();
diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/dto/ResponseFormatTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ResponseFormatTest.java
similarity index 99%
rename from agentscope-core/src/test/java/io/agentscope/core/formatter/openai/dto/ResponseFormatTest.java
rename to agentscope-core/src/test/java/io/agentscope/core/formatter/ResponseFormatTest.java
index 58f005aad..eed58593b 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/dto/ResponseFormatTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ResponseFormatTest.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.agentscope.core.formatter.openai.dto;
+package io.agentscope.core.formatter;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -21,6 +21,7 @@
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import io.agentscope.core.formatter.openai.dto.JsonSchema;
 import io.agentscope.core.util.JsonCodec;
 import io.agentscope.core.util.JsonUtils;
 import java.util.Arrays;
diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIChatFormatterTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIChatFormatterTest.java
index be42ba16f..a6425aa48 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIChatFormatterTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/openai/OpenAIChatFormatterTest.java
@@ -16,10 +16,15 @@
 package io.agentscope.core.formatter.openai;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
+import io.agentscope.core.formatter.ResponseFormat;
+import io.agentscope.core.formatter.openai.dto.JsonSchema;
 import io.agentscope.core.formatter.openai.dto.OpenAIMessage;
 import io.agentscope.core.formatter.openai.dto.OpenAIRequest;
 import io.agentscope.core.formatter.openai.dto.OpenAIResponse;
@@ -33,6 +38,7 @@
 import io.agentscope.core.model.GenerateOptions;
 import io.agentscope.core.model.ToolChoice;
 import io.agentscope.core.model.ToolSchema;
+import io.agentscope.core.util.JsonSchemaUtils;
 import java.time.Instant;
 import java.util.List;
 import java.util.Map;
@@ -491,6 +497,42 @@ void testApplyResponseFormat() {
             assertEquals("json_object", format.get("type"));
         }
 
+        @Test
+        @DisplayName("Should apply response_format parameter with ResponseFormat class")
+        void testApplyResponseFormatWithClass() {
+            OpenAIRequest request =
+                    OpenAIRequest.builder().model("gpt-4").messages(List.of()).build();
+
+            Map schema = JsonSchemaUtils.generateSchemaFromType(User.class);
+            ResponseFormat responseFormat =
+                    ResponseFormat.jsonSchema(
+                            JsonSchema.builder()
+                                    .name("user_info")
+                                    .description("The user information")
+                                    .strict(true)
+                                    .schema(schema)
+                                    .build());
+            GenerateOptions options =
+                    GenerateOptions.builder()
+                            .additionalBodyParam("response_format", responseFormat)
+                            .build();
+
+            formatter.applyOptions(request, options, null);
+
+            assertNotNull(request.getResponseFormat());
+            assertInstanceOf(ResponseFormat.class, request.getResponseFormat());
+            ResponseFormat format = (ResponseFormat) request.getResponseFormat();
+            assertEquals("json_schema", format.getType());
+            assertEquals("user_info", format.getJsonSchema().getName());
+            assertEquals("The user information", format.getJsonSchema().getDescription());
+            assertTrue(format.getJsonSchema().getStrict());
+            @SuppressWarnings("unchecked")
+            Map properties =
+                    (Map) format.getJsonSchema().getSchema().get("properties");
+            assertTrue(properties.containsKey("name"));
+            assertTrue(properties.containsKey("age"));
+        }
+
         @Test
         @DisplayName("Should add unknown parameters to extraParams")
         void testApplyUnknownParams() {
@@ -541,6 +583,16 @@ void testApplyWithNullOptions() {
             // Should not throw, request should remain unchanged
             assertNull(request.getReasoningEffort());
         }
+
+        private record User(
+                @JsonPropertyDescription("The user name")
+                        @JsonProperty(value = "name", required = true)
+                        String name,
+                @JsonPropertyDescription("The user age")
+                        @JsonProperty(value = "age", required = true)
+                        int age,
+                @JsonPropertyDescription("The user email address") @JsonProperty("email")
+                        String email) {}
     }
 
     @Nested
diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/DashScopeHttpClientTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/DashScopeHttpClientTest.java
index 2b70d84a0..d91cce636 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/model/DashScopeHttpClientTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/model/DashScopeHttpClientTest.java
@@ -23,12 +23,17 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 import com.fasterxml.jackson.core.type.TypeReference;
+import io.agentscope.core.formatter.ResponseFormat;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeInput;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeMessage;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeParameters;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeRequest;
 import io.agentscope.core.formatter.dashscope.dto.DashScopeResponse;
+import io.agentscope.core.formatter.openai.dto.JsonSchema;
+import io.agentscope.core.util.JsonSchemaUtils;
 import io.agentscope.core.util.JsonUtils;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
@@ -1248,6 +1253,53 @@ void testBuildUrlWithNullKeyOrValueInQueryParams() throws Exception {
         assertFalse(path.contains("key=null"));
     }
 
+    @Test
+    void testBuildRequestBodyWithAdditionalBodyParams() throws Exception {
+        mockServer.enqueue(
+                new MockResponse()
+                        .setResponseCode(200)
+                        .setBody("{\"request_id\":\"test\",\"output\":{\"choices\":[]}}")
+                        .setHeader("Content-Type", "application/json"));
+
+        DashScopeRequest request = createTestRequest("qwen-plus", "test");
+
+        Map schema = JsonSchemaUtils.generateSchemaFromType(User.class);
+        ResponseFormat responseFormat =
+                ResponseFormat.jsonSchema(
+                        JsonSchema.builder()
+                                .name("user_info")
+                                .description("The user information")
+                                .strict(true)
+                                .schema(schema)
+                                .build());
+
+        Map additionalBodyParams = new HashMap<>();
+        additionalBodyParams.put("enable_search", true);
+        additionalBodyParams.put("response_format", responseFormat);
+
+        client.call(request, null, additionalBodyParams, null);
+
+        RecordedRequest recorded = mockServer.takeRequest();
+        String body = recorded.getBody().readUtf8();
+
+        DashScopeRequest dashScopeRequest =
+                JsonUtils.getJsonCodec().fromJson(body, DashScopeRequest.class);
+        assertNotNull(dashScopeRequest);
+        assertNotNull(dashScopeRequest.getParameters());
+        assertTrue(dashScopeRequest.getParameters().getEnableSearch());
+        ResponseFormat format = dashScopeRequest.getParameters().getResponseFormat();
+        assertNotNull(format);
+        assertEquals("json_schema", format.getType());
+        assertEquals("user_info", format.getJsonSchema().getName());
+        assertEquals("The user information", format.getJsonSchema().getDescription());
+        assertTrue(format.getJsonSchema().getStrict());
+        @SuppressWarnings("unchecked")
+        Map properties =
+                (Map) format.getJsonSchema().getSchema().get("properties");
+        assertTrue(properties.containsKey("name"));
+        assertTrue(properties.containsKey("age"));
+    }
+
     @Test
     void testEncryptionHeaderAbsentWhenNoInput() throws Exception {
         java.security.KeyPair keyPair = generateRsaKeyPair();
@@ -1446,4 +1498,12 @@ private Map parseEncryptionHeader(RecordedRequest request) throw
         return JsonUtils.getJsonCodec()
                 .fromJson(encryptionHeader, new TypeReference>() {});
     }
+
+    private record User(
+            @JsonPropertyDescription("The user name") @JsonProperty(value = "name", required = true)
+                    String name,
+            @JsonPropertyDescription("The user age") @JsonProperty(value = "age", required = true)
+                    int age,
+            @JsonPropertyDescription("The user email address") @JsonProperty("email")
+                    String email) {}
 }

From ff3abab6cb21db4cdb3761563a388db817ea2239 Mon Sep 17 00:00:00 2001
From: Karson 
Date: Wed, 21 Jan 2026 11:08:12 +0800
Subject: [PATCH 27/53] feat: Support LLM thinking mode output in AG-UI (#574)

---
 .../agui/src/main/resources/application.yml   |   1 +
 .../agui/src/main/resources/static/index.html |  50 +-
 .../main/resources/static/js/agui-client.js   |  20 +
 .../core/agui/adapter/AguiAdapterConfig.java  |  31 ++
 .../core/agui/adapter/AguiAgentAdapter.java   |  76 ++-
 .../agentscope/core/agui/event/AguiEvent.java | 235 +++++++++-
 .../core/agui/event/AguiEventType.java        |  32 +-
 .../agui/adapter/AguiAdapterConfigTest.java   |   3 +
 .../agui/adapter/AguiAgentAdapterTest.java    | 434 ++++++++++++++++++
 .../core/agui/event/AguiEventTest.java        |   2 +-
 .../boot/agui/common/AguiProperties.java      |  18 +
 .../AgentscopeAguiMvcAutoConfiguration.java   |   1 +
 ...gentscopeAguiWebFluxAutoConfiguration.java |   1 +
 13 files changed, 898 insertions(+), 6 deletions(-)

diff --git a/agentscope-examples/agui/src/main/resources/application.yml b/agentscope-examples/agui/src/main/resources/application.yml
index 4cdf53c0e..8443b62a7 100644
--- a/agentscope-examples/agui/src/main/resources/application.yml
+++ b/agentscope-examples/agui/src/main/resources/application.yml
@@ -44,6 +44,7 @@ agentscope:
     server-side-memory: true
     max-thread-sessions: 1000
     session-timeout-minutes: 30
+    enable-reasoning: false
 
 # Logging
 logging:
diff --git a/agentscope-examples/agui/src/main/resources/static/index.html b/agentscope-examples/agui/src/main/resources/static/index.html
index c20e15636..97c72c425 100644
--- a/agentscope-examples/agui/src/main/resources/static/index.html
+++ b/agentscope-examples/agui/src/main/resources/static/index.html
@@ -117,10 +117,19 @@
         .message.tool {
             background: rgba(255, 158, 100, 0.1);
             border-left: 3px solid var(--accent-orange);
-            margin: 0 60px;
+            margin: 0 60px 16px 60px;
             font-size: 0.85rem;
         }
 
+        .message.reasoning {
+            background: rgba(158, 206, 106, 0.08);
+            border-left: 3px solid var(--accent-green);
+            margin: 0 60px 16px 60px;
+            font-size: 0.85rem;
+            font-style: italic;
+            opacity: 0.9;
+        }
+
         .message.error {
             background: rgba(247, 118, 142, 0.1);
             border-left: 3px solid var(--accent-red);
@@ -137,6 +146,7 @@
         .message.user .message-role { color: var(--text-secondary); }
         .message.assistant .message-role { color: var(--accent-blue); }
         .message.tool .message-role { color: var(--accent-orange); }
+        .message.reasoning .message-role { color: var(--accent-green); }
 
         .message-content {
             white-space: pre-wrap;
@@ -327,6 +337,14 @@ 
    AgentScope AG-UI Demo
    
                 return;
             }
 
+            if (append && role === 'reasoning' && currentReasoningDiv) {
+                // Append to current reasoning message
+                const contentEl = currentReasoningDiv.querySelector('.message-content');
+                contentEl.textContent += content;
+                messages.scrollTop = messages.scrollHeight;
+                return;
+            }
+
             const div = document.createElement('div');
             div.className = `message ${role}`;
             div.innerHTML = `
@@ -338,6 +356,8 @@ 
    AgentScope AG-UI Demo
    
 
             if (role === 'assistant') {
                 currentAssistantDiv = div;
+            } else if (role === 'reasoning') {
+                currentReasoningDiv = div;
             }
         }
 
@@ -380,6 +400,9 @@ 
    AgentScope AG-UI Demo
    
 
             let assistantContent = '';
             let currentMessageId = null;
+            let reasoningContent = '';
+            let currentReasoningMessageId = null;
+            let currentReasoningDiv = null;
 
             try {
                 await client.run({
@@ -390,6 +413,29 @@ 
    AgentScope AG-UI Demo
    
                     onRunStarted: () => {
                         console.log('Run started');
                         currentAssistantDiv = null;
+                        currentReasoningDiv = null;
+                        reasoningContent = '';
+                    },
+                    onReasoningMessageStart: (messageId, role) => {
+                        console.log('Reasoning message start:', messageId, role);
+                        hideTypingIndicator();
+                        currentReasoningMessageId = messageId;
+                        reasoningContent = '';
+                        currentReasoningDiv = null;
+                    },
+                    onReasoningContent: (delta, messageId) => {
+                        console.log('Reasoning content delta:', delta);
+                        if (reasoningContent === '') {
+                            appendMessage('reasoning', delta);
+                        } else {
+                            appendMessage('reasoning', delta, true);
+                        }
+                        reasoningContent += delta;
+                    },
+                    onReasoningMessageEnd: (messageId) => {
+                        console.log('Reasoning message end:', messageId);
+                        currentReasoningDiv = null;
+                        reasoningContent = '';
                     },
                     onTextMessageStart: (messageId, role) => {
                         console.log('Text message start:', messageId, role);
@@ -463,6 +509,8 @@ 
    AgentScope AG-UI Demo
    
                 stopBtn.style.display = 'none';
                 hideTypingIndicator();
                 currentAssistantDiv = null;
+                currentReasoningDiv = null;
+                reasoningContent = '';
                 if (statusText.textContent === 'Running...') {
                     setStatus('ready', 'Ready');
                 }
diff --git a/agentscope-examples/agui/src/main/resources/static/js/agui-client.js b/agentscope-examples/agui/src/main/resources/static/js/agui-client.js
index d094df577..58dc260d5 100644
--- a/agentscope-examples/agui/src/main/resources/static/js/agui-client.js
+++ b/agentscope-examples/agui/src/main/resources/static/js/agui-client.js
@@ -27,6 +27,7 @@
  *     messages: [{ id: 'msg-1', role: 'user', content: 'Hello!' }]
  * }, {
  *     onTextContent: (delta) => console.log(delta),
+ *     onReasoningContent: (delta) => console.log('Reasoning:', delta),
  *     onRunFinished: () => console.log('Done')
  * });
  */
@@ -71,6 +72,9 @@ class AguiClient {
      * @param {Object} [input.state] - Optional state
      * @param {Object} [input.forwardedProps] - Optional forwarded properties
      * @param {Object} callbacks - Event callbacks
+     * @param {Function} [callbacks.onReasoningMessageStart] - Called when reasoning message starts
+     * @param {Function} [callbacks.onReasoningContent] - Called with reasoning content delta
+     * @param {Function} [callbacks.onReasoningMessageEnd] - Called when reasoning message ends
      * @returns {Promise} Resolves when the run completes
      */
     async run(input, callbacks = {}) {
@@ -220,6 +224,22 @@ class AguiClient {
                     callbacks.onTextMessageEnd?.(event.messageId);
                     break;
 
+                case 'REASONING_MESSAGE_START':
+                    callbacks.onReasoningMessageStart?.(event.messageId, event.role);
+                    break;
+
+                case 'REASONING_MESSAGE_CONTENT':
+                    // Ensure delta is not null/undefined
+                    const reasoningDelta = event.delta || '';
+                    if (reasoningDelta) {
+                        callbacks.onReasoningContent?.(reasoningDelta, event.messageId);
+                    }
+                    break;
+
+                case 'REASONING_MESSAGE_END':
+                    callbacks.onReasoningMessageEnd?.(event.messageId);
+                    break;
+
                 case 'TOOL_CALL_START':
                     callbacks.onToolCallStart?.(event.toolCallId, event.toolCallName);
                     break;
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAdapterConfig.java b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAdapterConfig.java
index 29ca0306f..8870e2689 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAdapterConfig.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAdapterConfig.java
@@ -29,6 +29,7 @@ public class AguiAdapterConfig {
     private final ToolMergeMode toolMergeMode;
     private final boolean emitStateEvents;
     private final boolean emitToolCallArgs;
+    private final boolean enableReasoning;
     private final Duration runTimeout;
     private final String defaultAgentId;
 
@@ -36,6 +37,7 @@ private AguiAdapterConfig(Builder builder) {
         this.toolMergeMode = builder.toolMergeMode;
         this.emitStateEvents = builder.emitStateEvents;
         this.emitToolCallArgs = builder.emitToolCallArgs;
+        this.enableReasoning = builder.enableReasoning;
         this.runTimeout = builder.runTimeout;
         this.defaultAgentId = builder.defaultAgentId;
     }
@@ -67,6 +69,19 @@ public boolean isEmitToolCallArgs() {
         return emitToolCallArgs;
     }
 
+    /**
+     * Check if reasoning/thinking content should be emitted.
+     *
+     * 
    When enabled, ThinkingBlock content will be converted to REASONING_* events
+     * according to the AG-UI Reasoning draft specification. When disabled (default),
+     * ThinkingBlock content is ignored and no reasoning events are emitted.
+     *
+     * @return true if reasoning events should be emitted
+     */
+    public boolean isEnableReasoning() {
+        return enableReasoning;
+    }
+
     /**
      * Get the run timeout duration.
      *
@@ -111,6 +126,7 @@ public static class Builder {
         private ToolMergeMode toolMergeMode = ToolMergeMode.MERGE_FRONTEND_PRIORITY;
         private boolean emitStateEvents = true;
         private boolean emitToolCallArgs = true;
+        private boolean enableReasoning = false;
         private Duration runTimeout = Duration.ofMinutes(10);
         private String defaultAgentId;
 
@@ -147,6 +163,21 @@ public Builder emitToolCallArgs(boolean emitToolCallArgs) {
             return this;
         }
 
+        /**
+         * Set whether to enable reasoning/thinking content output.
+         *
+         * 
    When enabled, ThinkingBlock content will be converted to REASONING_* events
+         * according to the AG-UI Reasoning draft specification. Default is false to ensure
+         * backward compatibility and privacy compliance.
+         *
+         * @param enableReasoning true to enable reasoning events
+         * @return This builder
+         */
+        public Builder enableReasoning(boolean enableReasoning) {
+            this.enableReasoning = enableReasoning;
+            return this;
+        }
+
         /**
          * Set the run timeout duration.
          *
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java
index 30a83fcee..175e120be 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java
@@ -25,6 +25,7 @@
 import io.agentscope.core.message.ContentBlock;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.message.ThinkingBlock;
 import io.agentscope.core.message.ToolResultBlock;
 import io.agentscope.core.message.ToolUseBlock;
 import io.agentscope.core.util.JsonException;
@@ -46,10 +47,18 @@
  *
  * 
    Event Mapping:
  * 
      
- *   
    • AgentScope REASONING events → AG-UI TEXT_MESSAGE_* events
      • 
+ *   
    • AgentScope REASONING events → AG-UI TEXT_MESSAGE_* events (for TextBlock)
      • 
+ *   
    • AgentScope REASONING events → AG-UI REASONING_* events (for ThinkingBlock, when enabled)
      • 
  *   
    • AgentScope TOOL_RESULT events → AG-UI TOOL_CALL_END events
      • 
  *   
    • ToolUseBlock content → AG-UI TOOL_CALL_START events
      • 
  * 
    
+ *
+ * 
    Reasoning Support:
+ * 
      
+ *   
    • ThinkingBlock content is converted to REASONING_* events according to AG-UI Reasoning draft
      • 
+ *   
    • Reasoning output is disabled by default (enableReasoning=false) for backward compatibility
      • 
+ *   
    • Set enableReasoning=true in AguiAdapterConfig to enable reasoning events
      • 
+ * 
    
  */
 public class AguiAgentAdapter {
 
@@ -156,6 +165,41 @@ private List convertEvent(Event event, EventConversionState state) {
                             state.endMessage(messageId);
                         }
                     }
+                } else if (block instanceof ThinkingBlock thinkingBlock) {
+                    // Handle thinking blocks - convert to REASONING_* events (only if enabled)
+                    // According to AG-UI Reasoning draft: https://docs.ag-ui.com/drafts/reasoning
+                    if (config.isEnableReasoning()) {
+                        String thinking = thinkingBlock.getThinking();
+                        if (thinking != null && !thinking.isEmpty()) {
+                            String messageId = msg.getId();
+
+                            // Start reasoning message if not started
+                            if (!state.hasStartedReasoningMessage(messageId)) {
+                                events.add(
+                                        new AguiEvent.ReasoningMessageStart(
+                                                state.threadId,
+                                                state.runId,
+                                                messageId,
+                                                "assistant"));
+                                state.startReasoningMessage(messageId);
+                            }
+
+                            if (!event.isLast()) {
+                                // In incremental mode, thinking is already the delta
+                                events.add(
+                                        new AguiEvent.ReasoningMessageContent(
+                                                state.threadId, state.runId, messageId, thinking));
+                            } else {
+                                // End reasoning message if this is the last event
+                                events.add(
+                                        new AguiEvent.ReasoningMessageEnd(
+                                                state.threadId, state.runId, messageId));
+                                state.endReasoningMessage(messageId);
+                            }
+                        }
+                    }
+                    // If reasoning is disabled, ThinkingBlock content is ignored (backward
+                    // compatibility)
                 } else if (block instanceof ToolUseBlock toolUse) {
                     // End any active text message before starting tool call
                     if (state.hasActiveTextMessage()) {
@@ -242,6 +286,14 @@ private Flux finishRun(EventConversionState state) {
             }
         }
 
+        // End any reasoning messages that weren't properly ended
+        for (String messageId : state.getStartedReasoningMessages()) {
+            if (!state.hasEndedReasoningMessage(messageId)) {
+                events.add(
+                        new AguiEvent.ReasoningMessageEnd(state.threadId, state.runId, messageId));
+            }
+        }
+
         // Emit RUN_FINISHED
         events.add(new AguiEvent.RunFinished(state.threadId, state.runId));
 
@@ -300,6 +352,8 @@ private static class EventConversionState {
         private final Set endedMessages = new LinkedHashSet<>();
         private final Set startedToolCalls = new LinkedHashSet<>();
         private final Set endedToolCalls = new LinkedHashSet<>();
+        private final Set startedReasoningMessages = new LinkedHashSet<>();
+        private final Set endedReasoningMessages = new LinkedHashSet<>();
         private String currentTextMessageId = null;
 
         EventConversionState(String threadId, String runId) {
@@ -358,5 +412,25 @@ boolean hasEndedToolCall(String toolCallId) {
         Set getStartedToolCalls() {
             return startedToolCalls;
         }
+
+        boolean hasStartedReasoningMessage(String messageId) {
+            return startedReasoningMessages.contains(messageId);
+        }
+
+        void startReasoningMessage(String messageId) {
+            startedReasoningMessages.add(messageId);
+        }
+
+        void endReasoningMessage(String messageId) {
+            endedReasoningMessages.add(messageId);
+        }
+
+        boolean hasEndedReasoningMessage(String messageId) {
+            return endedReasoningMessages.contains(messageId);
+        }
+
+        Set getStartedReasoningMessages() {
+            return startedReasoningMessages;
+        }
     }
 }
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEvent.java b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEvent.java
index dbc335a66..0cf34a775 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEvent.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEvent.java
@@ -48,7 +48,19 @@
     @JsonSubTypes.Type(value = AguiEvent.ToolCallResult.class, name = "TOOL_CALL_RESULT"),
     @JsonSubTypes.Type(value = AguiEvent.StateSnapshot.class, name = "STATE_SNAPSHOT"),
     @JsonSubTypes.Type(value = AguiEvent.StateDelta.class, name = "STATE_DELTA"),
-    @JsonSubTypes.Type(value = AguiEvent.Raw.class, name = "RAW")
+    @JsonSubTypes.Type(value = AguiEvent.Raw.class, name = "RAW"),
+    @JsonSubTypes.Type(value = AguiEvent.ReasoningStart.class, name = "REASONING_START"),
+    @JsonSubTypes.Type(
+            value = AguiEvent.ReasoningMessageStart.class,
+            name = "REASONING_MESSAGE_START"),
+    @JsonSubTypes.Type(
+            value = AguiEvent.ReasoningMessageContent.class,
+            name = "REASONING_MESSAGE_CONTENT"),
+    @JsonSubTypes.Type(value = AguiEvent.ReasoningMessageEnd.class, name = "REASONING_MESSAGE_END"),
+    @JsonSubTypes.Type(
+            value = AguiEvent.ReasoningMessageChunk.class,
+            name = "REASONING_MESSAGE_CHUNK"),
+    @JsonSubTypes.Type(value = AguiEvent.ReasoningEnd.class, name = "REASONING_END")
 })
 public sealed interface AguiEvent
         permits AguiEvent.RunStarted,
@@ -62,7 +74,13 @@ public sealed interface AguiEvent
                 AguiEvent.ToolCallResult,
                 AguiEvent.StateSnapshot,
                 AguiEvent.StateDelta,
-                AguiEvent.Raw {
+                AguiEvent.Raw,
+                AguiEvent.ReasoningStart,
+                AguiEvent.ReasoningMessageStart,
+                AguiEvent.ReasoningMessageContent,
+                AguiEvent.ReasoningMessageEnd,
+                AguiEvent.ReasoningMessageChunk,
+                AguiEvent.ReasoningEnd {
 
     /**
      * Get the event type.
@@ -512,6 +530,219 @@ public String getRunId() {
         }
     }
 
+    /**
+     * Event indicating the start of a reasoning/thinking phase. This event is emitted
+     * when the agent begins its internal reasoning process.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningStart(String threadId, String runId, String messageId, String encryptedContent)
+            implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningStart(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId,
+                @JsonProperty("encryptedContent") String encryptedContent) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = Objects.requireNonNull(messageId, "messageId cannot be null");
+            this.encryptedContent = encryptedContent; // Optional
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_START;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
+    /**
+     * Event signaling the start of a reasoning message.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningMessageStart(String threadId, String runId, String messageId, String role)
+            implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningMessageStart(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId,
+                @JsonProperty("role") String role) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = Objects.requireNonNull(messageId, "messageId cannot be null");
+            this.role = Objects.requireNonNull(role, "role cannot be null");
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_MESSAGE_START;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
+    /**
+     * Event containing a chunk of content in a streaming reasoning message.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningMessageContent(String threadId, String runId, String messageId, String delta)
+            implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningMessageContent(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId,
+                @JsonProperty("delta") String delta) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = Objects.requireNonNull(messageId, "messageId cannot be null");
+            this.delta = Objects.requireNonNull(delta, "delta cannot be null");
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_MESSAGE_CONTENT;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
+    /**
+     * Event signaling the end of a reasoning message.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningMessageEnd(String threadId, String runId, String messageId)
+            implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningMessageEnd(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = Objects.requireNonNull(messageId, "messageId cannot be null");
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_MESSAGE_END;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
+    /**
+     * A convenience event to auto start/close reasoning messages.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningMessageChunk(String threadId, String runId, String messageId, String delta)
+            implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningMessageChunk(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId,
+                @JsonProperty("delta") String delta) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = messageId; // Optional
+            this.delta = delta; // Optional
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_MESSAGE_CHUNK;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
+    /**
+     * Event indicating the end of a reasoning/thinking phase. This event is emitted
+     * when the agent has finished its internal reasoning process.
+     *
+     * 
    According to AG-UI Reasoning draft specification.
+     */
+    record ReasoningEnd(String threadId, String runId, String messageId) implements AguiEvent {
+
+        @JsonCreator
+        public ReasoningEnd(
+                @JsonProperty("threadId") String threadId,
+                @JsonProperty("runId") String runId,
+                @JsonProperty("messageId") String messageId) {
+            this.threadId = Objects.requireNonNull(threadId, "threadId cannot be null");
+            this.runId = Objects.requireNonNull(runId, "runId cannot be null");
+            this.messageId = Objects.requireNonNull(messageId, "messageId cannot be null");
+        }
+
+        @Override
+        public AguiEventType getType() {
+            return AguiEventType.REASONING_END;
+        }
+
+        @Override
+        public String getThreadId() {
+            return threadId;
+        }
+
+        @Override
+        public String getRunId() {
+            return runId;
+        }
+    }
+
     /**
      * Represents a JSON Patch operation (RFC 6902). Used in {@link StateDelta}
      * events for
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEventType.java b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEventType.java
index c6d532eeb..60cb17ff0 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEventType.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/event/AguiEventType.java
@@ -77,5 +77,35 @@ public enum AguiEventType {
     /**
      * A raw event with custom data.
      */
-    RAW
+    RAW,
+
+    /**
+     * Indicates the start of a reasoning/thinking phase.
+     */
+    REASONING_START,
+
+    /**
+     * Signals the start of a reasoning message.
+     */
+    REASONING_MESSAGE_START,
+
+    /**
+     * Contains a chunk of content in a streaming reasoning message.
+     */
+    REASONING_MESSAGE_CONTENT,
+
+    /**
+     * Signals the end of a reasoning message.
+     */
+    REASONING_MESSAGE_END,
+
+    /**
+     * A convenience event to auto start/close reasoning messages.
+     */
+    REASONING_MESSAGE_CHUNK,
+
+    /**
+     * Indicates the end of a reasoning/thinking phase.
+     */
+    REASONING_END
 }
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAdapterConfigTest.java b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAdapterConfigTest.java
index 74c0fb0f1..f33eb70ff 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAdapterConfigTest.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAdapterConfigTest.java
@@ -38,6 +38,7 @@ void testDefaultConfig() {
         assertEquals(ToolMergeMode.MERGE_FRONTEND_PRIORITY, config.getToolMergeMode());
         assertTrue(config.isEmitStateEvents());
         assertTrue(config.isEmitToolCallArgs());
+        assertFalse(config.isEnableReasoning()); // Default should be false
         assertEquals(Duration.ofMinutes(10), config.getRunTimeout());
         assertNull(config.getDefaultAgentId());
     }
@@ -131,6 +132,7 @@ void testBuilderFullConfiguration() {
                         .toolMergeMode(ToolMergeMode.AGENT_ONLY)
                         .emitStateEvents(false)
                         .emitToolCallArgs(false)
+                        .enableReasoning(true)
                         .runTimeout(Duration.ofHours(1))
                         .defaultAgentId("my-agent")
                         .build();
@@ -138,6 +140,7 @@ void testBuilderFullConfiguration() {
         assertEquals(ToolMergeMode.AGENT_ONLY, config.getToolMergeMode());
         assertFalse(config.isEmitStateEvents());
         assertFalse(config.isEmitToolCallArgs());
+        assertTrue(config.isEnableReasoning());
         assertEquals(Duration.ofHours(1), config.getRunTimeout());
         assertEquals("my-agent", config.getDefaultAgentId());
     }
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java
index 2e0b6917f..21a62ac66 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java
@@ -34,6 +34,7 @@
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.MsgRole;
 import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.message.ThinkingBlock;
 import io.agentscope.core.message.ToolResultBlock;
 import io.agentscope.core.message.ToolUseBlock;
 import java.util.List;
@@ -508,4 +509,437 @@ void testReactiveStreamCompletion() {
                 .expectNextMatches(e -> e instanceof AguiEvent.RunFinished)
                 .verifyComplete();
     }
+
+    @Test
+    void testRunWithThinkingBlockDefaultDisabled() {
+        // Test that reasoning is disabled by default
+        Msg reasoningMsg =
+                Msg.builder()
+                        .id("msg-r1")
+                        .role(MsgRole.ASSISTANT)
+                        .content(
+                                ThinkingBlock.builder()
+                                        .thinking("Let me think about this problem step by step...")
+                                        .build())
+                        .build();
+
+        Event reasoningEvent = new Event(EventType.REASONING, reasoningMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(reasoningEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hello")))
+                        .build();
+
+        List events = adapter.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should NOT have any reasoning events when disabled (default)
+        boolean hasReasoningMessageStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageStart);
+        boolean hasReasoningMessageContent =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageContent);
+
+        assertTrue(
+                !hasReasoningMessageStart, "Should NOT have ReasoningMessageStart when disabled");
+        assertTrue(
+                !hasReasoningMessageContent,
+                "Should NOT have ReasoningMessageContent when disabled");
+    }
+
+    @Test
+    void testRunWithThinkingBlockEvent() {
+        // Test reasoning events when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg reasoningMsg =
+                Msg.builder()
+                        .id("msg-r1")
+                        .role(MsgRole.ASSISTANT)
+                        .content(
+                                ThinkingBlock.builder()
+                                        .thinking("Let me think about this problem step by step...")
+                                        .build())
+                        .build();
+
+        Event reasoningEvent = new Event(EventType.REASONING, reasoningMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(reasoningEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hello")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Find reasoning events
+        AguiEvent.ReasoningMessageStart reasoningMessageStart =
+                events.stream()
+                        .filter(e -> e instanceof AguiEvent.ReasoningMessageStart)
+                        .map(e -> (AguiEvent.ReasoningMessageStart) e)
+                        .findFirst()
+                        .orElse(null);
+
+        assertNotNull(reasoningMessageStart, "Should have ReasoningMessageStart");
+        assertEquals("msg-r1", reasoningMessageStart.messageId());
+        assertEquals("assistant", reasoningMessageStart.role());
+
+        AguiEvent.ReasoningMessageContent reasoningMessageContent =
+                events.stream()
+                        .filter(e -> e instanceof AguiEvent.ReasoningMessageContent)
+                        .map(e -> (AguiEvent.ReasoningMessageContent) e)
+                        .findFirst()
+                        .orElse(null);
+
+        assertNotNull(reasoningMessageContent, "Should have ReasoningMessageContent");
+        assertTrue(
+                reasoningMessageContent.delta().contains("think about this problem"),
+                "Should contain thinking content");
+    }
+
+    @Test
+    void testRunWithStreamingThinkingBlockEvents() {
+        // Test streaming reasoning events when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        // Simulate streaming thinking: multiple events with same message ID
+        Msg thinkingChunk1 =
+                Msg.builder()
+                        .id("msg-thinking")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("First thought").build())
+                        .build();
+
+        Msg thinkingChunk2 =
+                Msg.builder()
+                        .id("msg-thinking")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("Second thought").build())
+                        .build();
+
+        Event event1 = new Event(EventType.REASONING, thinkingChunk1, false);
+        Event event2 = new Event(EventType.REASONING, thinkingChunk2, false);
+
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(event1, event2));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hi")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Count ReasoningMessageContent events - should have 2 (one for each chunk)
+        long reasoningMessageContentCount =
+                events.stream().filter(e -> e instanceof AguiEvent.ReasoningMessageContent).count();
+        assertEquals(
+                2,
+                reasoningMessageContentCount,
+                "Should have 2 reasoning message content events for streaming");
+
+        // Should only have 1 ReasoningMessageStart (same message ID)
+        long reasoningMessageStartCount =
+                events.stream().filter(e -> e instanceof AguiEvent.ReasoningMessageStart).count();
+        assertEquals(
+                1,
+                reasoningMessageStartCount,
+                "Should have only 1 start event for same reasoning message ID");
+    }
+
+    @Test
+    void testRunWithThinkingAndTextMixedContent() {
+        // Test reasoning and text mixed content when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        // Message with both thinking and text
+        Msg mixedMsg =
+                Msg.builder()
+                        .id("msg-mixed")
+                        .role(MsgRole.ASSISTANT)
+                        .content(
+                                List.of(
+                                        ThinkingBlock.builder()
+                                                .thinking("I need to analyze this carefully.")
+                                                .build(),
+                                        TextBlock.builder()
+                                                .text("Based on my analysis, here's the answer.")
+                                                .build()))
+                        .build();
+
+        Event mixedEvent = new Event(EventType.REASONING, mixedMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(mixedEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Question?")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should have reasoning events
+        boolean hasReasoningMessageStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageStart);
+        boolean hasReasoningMessageContent =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageContent);
+
+        // Should have regular text message events
+        boolean hasTextStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.TextMessageStart);
+        boolean hasTextContent =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.TextMessageContent);
+
+        assertTrue(hasReasoningMessageStart, "Should have ReasoningMessageStart");
+        assertTrue(hasReasoningMessageContent, "Should have ReasoningMessageContent");
+        assertTrue(hasTextStart, "Should have TextMessageStart for text");
+        assertTrue(hasTextContent, "Should have TextMessageContent for text");
+    }
+
+    @Test
+    void testRunWithEmptyThinkingBlock() {
+        // Empty thinking block should be skipped even when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg reasoningMsg =
+                Msg.builder()
+                        .id("msg-r1")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("").build())
+                        .build();
+
+        Event reasoningEvent = new Event(EventType.REASONING, reasoningMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(reasoningEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hello")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should NOT have any reasoning events for empty thinking
+        boolean hasReasoningMessageStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageStart);
+
+        assertTrue(
+                !hasReasoningMessageStart,
+                "Should NOT have ReasoningMessageStart for empty thinking");
+    }
+
+    @Test
+    void testRunWithThinkingBlockLastEvent() {
+        // Test the isLast() == true branch for ThinkingBlock when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg reasoningMsg =
+                Msg.builder()
+                        .id("msg-r1")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("Final thinking content").build())
+                        .build();
+
+        Event reasoningEvent = new Event(EventType.REASONING, reasoningMsg, true); // isLast = true
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(reasoningEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hello")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should have ReasoningMessageStart and ReasoningMessageEnd
+        AguiEvent.ReasoningMessageStart reasoningMessageStart =
+                events.stream()
+                        .filter(e -> e instanceof AguiEvent.ReasoningMessageStart)
+                        .map(e -> (AguiEvent.ReasoningMessageStart) e)
+                        .findFirst()
+                        .orElse(null);
+
+        assertNotNull(reasoningMessageStart, "Should have ReasoningMessageStart");
+
+        AguiEvent.ReasoningMessageEnd reasoningMessageEnd =
+                events.stream()
+                        .filter(e -> e instanceof AguiEvent.ReasoningMessageEnd)
+                        .map(e -> (AguiEvent.ReasoningMessageEnd) e)
+                        .findFirst()
+                        .orElse(null);
+
+        assertNotNull(reasoningMessageEnd, "Should have ReasoningMessageEnd when isLast=true");
+
+        // Should NOT have ReasoningMessageContent when isLast=true (content is empty)
+        boolean hasContent =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageContent);
+
+        assertTrue(!hasContent, "Should NOT have ReasoningMessageContent when isLast=true");
+    }
+
+    @Test
+    void testRunWithThinkingAndToolCallMixed() {
+        // Test thinking content mixed with tool call when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg mixedMsg =
+                Msg.builder()
+                        .id("msg-mixed")
+                        .role(MsgRole.ASSISTANT)
+                        .content(
+                                List.of(
+                                        ThinkingBlock.builder()
+                                                .thinking("I need to use a tool to get the answer.")
+                                                .build(),
+                                        ToolUseBlock.builder()
+                                                .id("tc-1")
+                                                .name("get_weather")
+                                                .input(Map.of("city", "Beijing"))
+                                                .build()))
+                        .build();
+
+        Event mixedEvent = new Event(EventType.REASONING, mixedMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(mixedEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Weather?")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should have reasoning events
+        boolean hasReasoningMessageStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageStart);
+
+        // Should have tool call events
+        boolean hasToolStart = events.stream().anyMatch(e -> e instanceof AguiEvent.ToolCallStart);
+
+        assertTrue(hasReasoningMessageStart, "Should have reasoning message start event");
+        assertTrue(hasToolStart, "Should have tool call");
+    }
+
+    @Test
+    void testRunWithStreamingThinkingBlockLastEvent() {
+        // Test streaming with last event (isLast=true) when enabled
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg thinkingChunk1 =
+                Msg.builder()
+                        .id("msg-thinking")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("First thought").build())
+                        .build();
+
+        Msg thinkingChunk2 =
+                Msg.builder()
+                        .id("msg-thinking")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking("Second thought").build())
+                        .build();
+
+        Event event1 = new Event(EventType.REASONING, thinkingChunk1, false);
+        Event event2 = new Event(EventType.REASONING, thinkingChunk2, true); // Last event
+
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(event1, event2));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hi")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should have ReasoningMessageContent for first chunk
+        long messageContentCount =
+                events.stream().filter(e -> e instanceof AguiEvent.ReasoningMessageContent).count();
+        assertEquals(
+                1,
+                messageContentCount,
+                "Should have 1 reasoning message content event for first chunk");
+
+        // Should have ReasoningMessageEnd for last event
+        boolean hasMessageEnd =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageEnd);
+        assertTrue(hasMessageEnd, "Should have ReasoningMessageEnd for last event");
+    }
+
+    @Test
+    void testRunWithNullThinkingBlock() {
+        // ThinkingBlock with null thinking should be converted to empty string and skipped
+        AguiAdapterConfig config = AguiAdapterConfig.builder().enableReasoning(true).build();
+        AguiAgentAdapter adapterWithReasoning = new AguiAgentAdapter(mockAgent, config);
+
+        Msg reasoningMsg =
+                Msg.builder()
+                        .id("msg-r1")
+                        .role(MsgRole.ASSISTANT)
+                        .content(ThinkingBlock.builder().thinking(null).build())
+                        .build();
+
+        Event reasoningEvent = new Event(EventType.REASONING, reasoningMsg, false);
+        when(mockAgent.stream(anyList(), any(StreamOptions.class)))
+                .thenReturn(Flux.just(reasoningEvent));
+
+        RunAgentInput input =
+                RunAgentInput.builder()
+                        .threadId("thread-1")
+                        .runId("run-1")
+                        .messages(List.of(AguiMessage.userMessage("msg-1", "Hello")))
+                        .build();
+
+        List events = adapterWithReasoning.run(input).collectList().block();
+
+        assertNotNull(events);
+
+        // Should NOT have any reasoning events for null/empty thinking
+        boolean hasReasoningMessageStart =
+                events.stream().anyMatch(e -> e instanceof AguiEvent.ReasoningMessageStart);
+
+        assertTrue(
+                !hasReasoningMessageStart,
+                "Should NOT have ReasoningMessageStart for null thinking");
+    }
 }
diff --git a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/event/AguiEventTest.java b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/event/AguiEventTest.java
index ff50da789..e47dbc2e4 100644
--- a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/event/AguiEventTest.java
+++ b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/event/AguiEventTest.java
@@ -758,7 +758,7 @@ void testAllEventTypesExist() {
 
         @Test
         void testEventTypeCount() {
-            assertEquals(12, AguiEventType.values().length);
+            assertEquals(18, AguiEventType.values().length);
         }
 
         @Test
diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/common/AguiProperties.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/common/AguiProperties.java
index 4ea2226d3..a2edda5af 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/common/AguiProperties.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/common/AguiProperties.java
@@ -37,6 +37,7 @@
  *     default-agent-id: default
  *     agent-id-header: X-Agent-Id
  *     enable-path-routing: true
+ *     enable-reasoning: false
  *
    */ @ConfigurationProperties(prefix = "agentscope.agui") @@ -63,6 +64,15 @@ public class AguiProperties { /** Whether to emit tool call argument events. */ private boolean emitToolCallArgs = true; + /** + * Whether to enable reasoning/thinking content output. + * + *

    When enabled, ThinkingBlock content will be converted to REASONING_* events + * according to the AG-UI Reasoning draft specification. Default is false to ensure + * backward compatibility and privacy compliance. + */ + private boolean enableReasoning = false; + /** Default agent ID to use when not specified in the request. */ private String defaultAgentId = "default"; @@ -158,6 +168,14 @@ public void setEmitToolCallArgs(boolean emitToolCallArgs) { this.emitToolCallArgs = emitToolCallArgs; } + public boolean isEnableReasoning() { + return enableReasoning; + } + + public void setEnableReasoning(boolean enableReasoning) { + this.enableReasoning = enableReasoning; + } + public String getDefaultAgentId() { return defaultAgentId; } diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/mvc/AgentscopeAguiMvcAutoConfiguration.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/mvc/AgentscopeAguiMvcAutoConfiguration.java index 05cdc4232..250ecd3b1 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/mvc/AgentscopeAguiMvcAutoConfiguration.java +++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/mvc/AgentscopeAguiMvcAutoConfiguration.java @@ -89,6 +89,7 @@ public AguiMvcController aguiMvcController( .runTimeout(props.getRunTimeout()) .emitStateEvents(props.isEmitStateEvents()) .emitToolCallArgs(props.isEmitToolCallArgs()) + .enableReasoning(props.isEnableReasoning()) .defaultAgentId(props.getDefaultAgentId()) .build(); diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/webflux/AgentscopeAguiWebFluxAutoConfiguration.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/webflux/AgentscopeAguiWebFluxAutoConfiguration.java index 882fb933e..09c21082b 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/webflux/AgentscopeAguiWebFluxAutoConfiguration.java +++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-agui-spring-boot-starter/src/main/java/io/agentscope/spring/boot/agui/webflux/AgentscopeAguiWebFluxAutoConfiguration.java @@ -92,6 +92,7 @@ public AguiWebFluxHandler aguiWebFluxHandler( .runTimeout(props.getRunTimeout()) .emitStateEvents(props.isEmitStateEvents()) .emitToolCallArgs(props.isEmitToolCallArgs()) + .enableReasoning(props.isEnableReasoning()) .defaultAgentId(props.getDefaultAgentId()) .build(); From b278ecea90b69eb821e49b1a51738cd9b40c84ca Mon Sep 17 00:00:00 2001 From: feelshana <151412598@qq.com> Date: Wed, 21 Jan 2026 11:12:48 +0800 Subject: [PATCH 28/53] fix(core):Add the correct reason for the stop agent behavior (#606) ## AgentScope-Java Version main branch ## Description Add the correct reason for the stop agent behavior(#602) ## 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 --- .../src/main/java/io/agentscope/core/ReActAgent.java | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java index bd5fe0562..c6b7ab8af 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java @@ -454,7 +454,9 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { // HITL stop if (event.isStopRequested()) { - return Mono.just(msg); + return Mono.just( + msg.withGenerateReason( + GenerateReason.REASONING_STOP_REQUESTED)); } // gotoReasoning requested (e.g., by StructuredOutputHook) @@ -543,7 +545,11 @@ private Mono acting(int iter) { // HITL stop (also triggered by // StructuredOutputHook when completed) if (event.isStopRequested()) { - return Mono.just(event.getToolResultMsg()); + return Mono.just( + event.getToolResultMsg() + .withGenerateReason( + GenerateReason + .ACTING_STOP_REQUESTED)); } // If there are pending results, build suspended Msg From 2f7d122143a261fbf9c4566149520fa57e147378 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 22 Jan 2026 11:21:47 +0800 Subject: [PATCH 29/53] chore(deps): bump io.milvus:milvus-sdk-java from 2.6.12 to 2.6.13 (#622) Bumps [io.milvus:milvus-sdk-java](https://github.com/milvus-io/milvus-sdk-java) from 2.6.12 to 2.6.13.

    Release notes

    Sourced from io.milvus:milvus-sdk-java's releases.

    milvus-sdk-java-2.6.13

    Release date: 2026-01-13

    Compatible with Milvus v2.6.x

    Feature

    • Support search by id
    • Support highlighter for search results
    Changelog

    Sourced from io.milvus:milvus-sdk-java's changelog.

    milvus-sdk-java 2.6.13 (2026-01-21)

    Feature

    • Support search by id
    • Support highlighter for search results
    Commits

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=io.milvus:milvus-sdk-java&package-manager=maven&previous-version=2.6.12&new-version=2.6.13)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-dependencies-bom/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml index eea23cb0c..806576aa9 100644 --- a/agentscope-dependencies-bom/pom.xml +++ b/agentscope-dependencies-bom/pom.xml @@ -82,7 +82,7 @@ 0.17.0 2.0.17 1.16.2 - 2.6.12 + 2.6.13 8.12.0 42.7.9 0.1.6 From e3670f6fa7144888289ce84bffe79ab4ec45c16e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 22 Jan 2026 15:06:06 +0800 Subject: [PATCH 30/53] chore(deps): bump lodash-es from 4.17.21 to 4.17.23 in /agentscope-examples/boba-tea-shop/frontend in the npm_and_yarn group across 1 directory (#624) Bumps the npm_and_yarn group with 1 update in the /agentscope-examples/boba-tea-shop/frontend directory: [lodash-es](https://github.com/lodash/lodash). Updates `lodash-es` from 4.17.21 to 4.17.23
    Commits

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=lodash-es&package-manager=npm_and_yarn&previous-version=4.17.21&new-version=4.17.23)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore ` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore ` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore ` will remove the ignore condition of the specified dependency and ignore conditions You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/agentscope-ai/agentscope-java/network/alerts).
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .../boba-tea-shop/frontend/package-lock.json | 93 ++++++++++--------- 1 file changed, 49 insertions(+), 44 deletions(-) diff --git a/agentscope-examples/boba-tea-shop/frontend/package-lock.json b/agentscope-examples/boba-tea-shop/frontend/package-lock.json index 0ac0bfa50..e618344a3 100644 --- a/agentscope-examples/boba-tea-shop/frontend/package-lock.json +++ b/agentscope-examples/boba-tea-shop/frontend/package-lock.json @@ -2773,6 +2773,19 @@ "node": ">= 8" } }, + "node_modules/anymatch/node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmmirror.com/argparse/-/argparse-2.0.1.tgz", @@ -5742,9 +5755,10 @@ "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" }, "node_modules/lodash-es": { - "version": "4.17.21", - "resolved": "https://registry.npmmirror.com/lodash-es/-/lodash-es-4.17.21.tgz", - "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==" + "version": "4.17.23", + "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.23.tgz", + "integrity": "sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==", + "license": "MIT" }, "node_modules/lodash.merge": { "version": "4.6.2", @@ -5866,6 +5880,19 @@ "node": ">=8.6" } }, + "node_modules/micromatch/node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, "node_modules/mime": { "version": "1.6.0", "resolved": "https://registry.npmmirror.com/mime/-/mime-1.6.0.tgz", @@ -6409,12 +6436,13 @@ "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==" }, "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmmirror.com/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", + "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, + "license": "MIT", "engines": { - "node": ">=8.6" + "node": ">=12" }, "funding": { "url": "https://github.com/sponsors/jonschlinkert" @@ -6638,6 +6666,19 @@ "node": ">=8.10.0" } }, + "node_modules/readdirp/node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, "node_modules/reflect.getprototypeof": { "version": "1.0.10", "resolved": "https://registry.npmmirror.com/reflect.getprototypeof/-/reflect.getprototypeof-1.0.10.tgz", @@ -7474,18 +7515,6 @@ "url": "https://github.com/sponsors/SuperchupuDev" } }, - "node_modules/tinyglobby/node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", - "dev": true, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, "node_modules/tinypool": { "version": "1.1.1", "resolved": "https://registry.npmmirror.com/tinypool/-/tinypool-1.1.1.tgz", @@ -7711,7 +7740,7 @@ "version": "5.3.3", "resolved": "https://registry.npmmirror.com/typescript/-/typescript-5.3.3.tgz", "integrity": "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==", - "dev": true, + "devOptional": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -7997,18 +8026,6 @@ "node": ">=8" } }, - "node_modules/vite/node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", - "dev": true, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, "node_modules/vitest": { "version": "3.2.4", "resolved": "https://registry.npmmirror.com/vitest/-/vitest-3.2.4.tgz", @@ -8081,18 +8098,6 @@ } } }, - "node_modules/vitest/node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", - "dev": true, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, "node_modules/vscode-jsonrpc": { "version": "6.0.0", "resolved": "https://registry.npmmirror.com/vscode-jsonrpc/-/vscode-jsonrpc-6.0.0.tgz", From a3462fd91940b30515b41dc3626d3d2dee17fa71 Mon Sep 17 00:00:00 2001 From: LearningGp Date: Thu, 22 Jan 2026 15:06:44 +0800 Subject: [PATCH 31/53] fix(werewolf): update vote message metadata structure (#625) ## AgentScope-Java Version 1.0.8 ## Description fix(werewolf): update vote message metadata structure ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../werewolf/web/WerewolfWebGame.java | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/agentscope-examples/werewolf-hitl/src/main/java/io/agentscope/examples/werewolf/web/WerewolfWebGame.java b/agentscope-examples/werewolf-hitl/src/main/java/io/agentscope/examples/werewolf/web/WerewolfWebGame.java index 0fbb4211d..d883d52a4 100644 --- a/agentscope-examples/werewolf-hitl/src/main/java/io/agentscope/examples/werewolf/web/WerewolfWebGame.java +++ b/agentscope-examples/werewolf-hitl/src/main/java/io/agentscope/examples/werewolf/web/WerewolfWebGame.java @@ -23,6 +23,7 @@ import io.agentscope.core.agent.user.UserAgent; import io.agentscope.core.formatter.dashscope.DashScopeMultiAgentFormatter; import io.agentscope.core.memory.InMemoryMemory; +import io.agentscope.core.message.MessageMetadataKeys; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; @@ -437,7 +438,14 @@ private Player werewolvesKill() { .name(werewolf.getName()) .role(MsgRole.USER) .content(TextBlock.builder().text(voteTarget).build()) - .metadata(Map.of("targetPlayer", voteTarget, "reason", "")) + .metadata( + Map.of( + MessageMetadataKeys.STRUCTURED_OUTPUT, + Map.of( + "targetPlayer", + voteTarget, + "reason", + ""))) .build(); votes.add(voteMsg); } else { @@ -921,7 +929,14 @@ private Player votingPhase() { .name(player.getName()) .role(MsgRole.USER) .content(TextBlock.builder().text(voteTarget).build()) - .metadata(Map.of("targetPlayer", voteTarget, "reason", "")) + .metadata( + Map.of( + MessageMetadataKeys.STRUCTURED_OUTPUT, + Map.of( + "targetPlayer", + voteTarget, + "reason", + ""))) .build(); votes.add(voteMsg); } else { From d792df5843e1c3938766ffdc70f97f2f81f52ceb Mon Sep 17 00:00:00 2001 From: fang-tech Date: Thu, 22 Jan 2026 15:07:57 +0800 Subject: [PATCH 32/53] fix(tool): prevent pipe buffer deadlock in ShellCommandTool (#619) ## 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 - Fixed deadlock issue when executing commands with large output (>4-64KB) - Implemented asynchronous stream reading using CompletableFuture to prevent pipe buffer from filling up and blocking child process - Added getOutputWithTimeout() helper method for safe retrieval of async stream reader results with proper timeout and error handling - All existing tests pass without regression close #617 ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../core/tool/coding/ShellCommandTool.java | 148 ++- .../tool/coding/ShellCommandToolTest.java | 148 +++ .../src/test/resources/large_output_test.txt | 1000 +++++++++++++++++ 3 files changed, 1269 insertions(+), 27 deletions(-) create mode 100644 agentscope-core/src/test/resources/large_output_test.txt diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java index 1909c71bb..46e0f305a 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java @@ -21,6 +21,7 @@ import io.agentscope.core.tool.ToolCallParam; import java.io.BufferedReader; import java.io.IOException; +import java.io.InputStream; import java.io.InputStreamReader; import java.nio.charset.StandardCharsets; import java.time.Duration; @@ -29,9 +30,16 @@ import java.util.List; import java.util.Map; import java.util.Set; +import java.util.concurrent.Callable; import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.ThreadFactory; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; +import java.util.concurrent.atomic.AtomicInteger; import java.util.function.Function; import java.util.stream.Collectors; import org.slf4j.Logger; @@ -58,6 +66,28 @@ public class ShellCommandTool implements AgentTool { private static final Logger logger = LoggerFactory.getLogger(ShellCommandTool.class); private static final int DEFAULT_TIMEOUT = 300; + /** + * Shared thread pool for asynchronous stream reading. + * Uses cached thread pool for dynamic scaling with 60s idle timeout. + * Daemon threads ensure they don't prevent JVM shutdown. + */ + private static final ExecutorService STREAM_READER_POOL = + Executors.newCachedThreadPool( + new ThreadFactory() { + private final AtomicInteger counter = new AtomicInteger(0); + + @Override + public Thread newThread(Runnable r) { + Thread t = + new Thread( + r, + "ShellCommand-StreamReader-" + + counter.incrementAndGet()); + t.setDaemon(true); // Daemon thread won't prevent JVM shutdown + return t; + } + }); + private final Set allowedCommands; private final Function approvalCallback; private final CommandValidator commandValidator; @@ -337,6 +367,9 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { } Process process = null; + Future stdoutFuture = null; + Future stderrFuture = null; + try { long startTime = System.currentTimeMillis(); logger.debug("Starting command execution: {}", command); @@ -344,6 +377,21 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { // Start the process process = processBuilder.start(); + // CRITICAL FIX: Start asynchronous stream readers immediately to prevent pipe buffer + // deadlock + // When a child process writes more data than the pipe buffer can hold (typically + // 4-64KB), + // it will block waiting for the parent process to read the data. If the parent is + // blocked + // in waitFor(), this creates a deadlock. By reading streams asynchronously in + // background + // threads from the thread pool, we ensure the pipe buffers are continuously drained, + // preventing the deadlock. + stdoutFuture = + STREAM_READER_POOL.submit(new StreamReader(process.getInputStream(), "stdout")); + stderrFuture = + STREAM_READER_POOL.submit(new StreamReader(process.getErrorStream(), "stderr")); + // Wait for the process to complete with timeout logger.debug("Waiting for process with timeout: {} seconds", timeoutSeconds); boolean completed = process.waitFor(timeoutSeconds, TimeUnit.SECONDS); @@ -359,13 +407,13 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { timeoutSeconds, waitElapsed); - // Try to capture partial output before terminating - String stdout = readStream(process.getInputStream()); - String stderr = readStream(process.getErrorStream()); - // Terminate the process process.destroyForcibly(); + // Get partial output from async readers with short timeout + String stdout = getOutputWithTimeout(stdoutFuture, 1, TimeUnit.SECONDS); + String stderr = getOutputWithTimeout(stderrFuture, 1, TimeUnit.SECONDS); + String timeoutMessage = String.format( "TimeoutError: The command execution exceeded the timeout of %d" @@ -384,8 +432,11 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { // Process completed normally int returnCode = process.exitValue(); - String stdout = readStream(process.getInputStream()); - String stderr = readStream(process.getErrorStream()); + + // Get complete output from async readers + // Process has finished, so readers should complete quickly + String stdout = getOutputWithTimeout(stdoutFuture, 5, TimeUnit.SECONDS); + String stderr = getOutputWithTimeout(stderrFuture, 5, TimeUnit.SECONDS); logger.debug("Command '{}' completed with return code: {}", command, returnCode); @@ -411,37 +462,40 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { // Clean up process resources if (process != null && process.isAlive()) { // Destroy the process if still alive - // Note: Streams are already closed by try-with-resources in readStream() + // Note: Streams are already closed by try-with-resources in StreamReader process.destroyForcibly(); } } } /** - * Read all content from an input stream. + * Get output from a Future with timeout. * - * @param inputStream The input stream to read from - * @return The content as a string + *

    This helper method safely retrieves the output from an asynchronous stream reader, + * with proper timeout and error handling. If the future times out or fails, it will be + * cancelled and an empty string will be returned. + * + * @param future The Future containing the output string + * @param timeout The timeout value + * @param unit The timeout unit + * @return The output string, or empty string if timeout or error occurs */ - private String readStream(java.io.InputStream inputStream) { - if (inputStream == null) { + private String getOutputWithTimeout(Future future, long timeout, TimeUnit unit) { + try { + return future.get(timeout, unit); + } catch (TimeoutException e) { + logger.warn("Timeout waiting for stream reader to complete"); + future.cancel(true); // Cancel the task + return ""; + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + logger.warn("Interrupted while waiting for stream reader"); + future.cancel(true); // Cancel the task + return ""; + } catch (ExecutionException e) { + logger.error("Error in stream reader: {}", e.getCause().getMessage(), e.getCause()); return ""; } - - StringBuilder output = new StringBuilder(); - try (BufferedReader reader = - new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) { - String line; - while ((line = reader.readLine()) != null) { - if (output.length() > 0) { - output.append("\n"); - } - output.append(line); - } - } catch (IOException e) { - logger.error("Error reading stream: {}", e.getMessage(), e); - } - return output.toString(); } /** @@ -491,4 +545,44 @@ private boolean requestUserApproval(String command) { return false; } } + + /** + * Callable task for reading process output streams asynchronously. + * This prevents pipe buffer deadlock by continuously draining stdout/stderr. + */ + private static class StreamReader implements Callable { + private final InputStream inputStream; + private final String streamType; + + StreamReader(InputStream inputStream, String streamType) { + this.inputStream = inputStream; + this.streamType = streamType; + } + + @Override + public String call() throws Exception { + if (inputStream == null) { + return ""; + } + + logger.debug("StreamReader [{}] started", streamType); + StringBuilder output = new StringBuilder(); + try (BufferedReader reader = + new BufferedReader( + new InputStreamReader(inputStream, StandardCharsets.UTF_8))) { + String line; + while ((line = reader.readLine()) != null) { + if (output.length() > 0) { + output.append("\n"); + } + output.append(line); + } + } catch (IOException e) { + logger.error("Error reading {} stream: {}", streamType, e.getMessage(), e); + throw e; + } + logger.debug("StreamReader [{}] completed, read {} bytes", streamType, output.length()); + return output.toString(); + } + } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java index 370a71815..e4a75b19d 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java @@ -780,4 +780,152 @@ void testConcurrentDescriptionGeneration() throws InterruptedException { assertEquals(threadCount, successCount.get()); } } + + @Nested + @DisplayName("Buffer Deadlock Fix Tests (Issue #617)") + class BufferDeadlockTests { + + @Test + @DisplayName("Should handle large output without deadlock using seq command") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void reproducePipeBufferDeadlockWithSeq() { + // Generate ~8KB output using seq command, which exceeds typical pipe buffer + // (4-8KB) + // This command completes in milliseconds with the fix (Apache Commons Exec's + // PumpStreamHandler) + String command = "seq 1 20000"; // Approximately 8000 bytes + + // Set a reasonable timeout - should complete quickly now + Mono result = tool.executeShellCommand(command, 60); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + // Expected: Should complete successfully without timeout + // The fix uses PumpStreamHandler to consume output in separate + // threads + assertFalse( + text.contains("TimeoutError"), + "Should not timeout with Apache Commons Exec fix, but got: " + + text); + assertTrue( + text.contains("0"), + "Expected successful execution"); + assertTrue( + text.contains("20000"), + "Expected output to contain the last number"); + }) + .verifyComplete(); + } + + @Test + @DisplayName("Should handle large file cat without deadlock") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void reproduceLargeFileCatDeadlock() throws Exception { + // Create a temporary large file + java.nio.file.Path tempFile = java.nio.file.Files.createTempFile("test_large_", ".txt"); + try { + // Write 20KB of data (far exceeds typical pipe buffer size) + StringBuilder content = new StringBuilder(); + for (int i = 0; i < 2000; i++) { + content.append("Line ") + .append(i) + .append(": ") + .append("Some test content to fill the buffer\n"); + } + java.nio.file.Files.writeString(tempFile, content.toString()); + + String command = "cat " + tempFile.toString(); + + // Set a reasonable timeout - should complete quickly with the fix + Mono result = tool.executeShellCommand(command, 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + // Expected: Should complete successfully and return the file + // content + assertFalse( + text.contains("TimeoutError"), + "Should not timeout with Apache Commons Exec fix, but" + + " got: " + + text); + assertTrue( + text.contains("0"), + "Expected successful execution"); + assertTrue( + text.contains("Line 1999"), + "Expected output to contain last line"); + }) + .verifyComplete(); + } finally { + java.nio.file.Files.deleteIfExists(tempFile); + } + } + + @Test + @DisplayName("Should handle pre-created large test file without deadlock") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void reproduceLargeFileCatDeadlockWithTestResource() { + // Use the pre-created test resource file (20KB) + String resourcePath = + getClass().getClassLoader().getResource("large_output_test.txt").getPath(); + String command = "cat " + resourcePath; + + // Set a reasonable timeout - should complete quickly with the fix + Mono result = tool.executeShellCommand(command, 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + // Expected: Should complete successfully and return the file + // content + assertFalse( + text.contains("TimeoutError"), + "Should not timeout with Apache Commons Exec fix, but got: " + + text); + assertTrue( + text.contains("0"), + "Expected successful execution"); + assertTrue( + text.contains("This is test content"), + "Expected output to contain file content"); + }) + .verifyComplete(); + } + + @Test + @DisplayName("Should handle yes command piped to head without deadlock") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void reproducePipeBufferDeadlockWithYesCommand() { + // Generate large output using yes command + // This produces continuous output that will definitely fill the buffer + String command = "yes 'This is a test line with some content' | head -n 1000"; + + // Set a reasonable timeout - should complete quickly with the fix + Mono result = tool.executeShellCommand(command, 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + // Expected: Should complete successfully without timeout + // PumpStreamHandler consumes output in separate threads + assertFalse( + text.contains("TimeoutError"), + "Should not timeout with Apache Commons Exec fix, but got: " + + text); + assertTrue( + text.contains("0"), + "Expected successful execution"); + assertTrue( + text.contains("This is a test line"), + "Expected output to contain the repeated line"); + }) + .verifyComplete(); + } + } } diff --git a/agentscope-core/src/test/resources/large_output_test.txt b/agentscope-core/src/test/resources/large_output_test.txt new file mode 100644 index 000000000..2ee4d374c --- /dev/null +++ b/agentscope-core/src/test/resources/large_output_test.txt @@ -0,0 +1,1000 @@ +Line 0: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 1: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 2: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 3: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 4: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 5: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 6: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 7: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 8: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 9: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 10: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 11: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 12: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 13: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 14: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 15: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 16: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 17: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 18: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 19: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 20: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 21: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 22: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 23: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 24: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 25: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 26: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 27: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 28: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 29: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 30: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 31: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 32: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 33: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 34: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 35: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 36: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 37: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 38: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 39: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 40: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 41: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 42: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 43: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 44: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 45: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 46: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 47: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 48: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 49: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 50: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 51: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 52: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 53: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 54: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 55: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 56: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 57: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 58: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 59: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 60: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 61: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 62: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 63: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 64: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 65: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 66: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 67: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 68: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 69: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 70: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 71: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 72: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 73: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 74: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 75: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 76: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 77: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 78: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 79: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 80: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 81: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 82: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 83: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 84: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 85: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 86: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 87: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 88: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 89: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 90: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 91: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 92: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 93: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 94: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 95: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 96: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 97: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 98: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 99: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 100: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 101: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 102: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 103: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 104: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 105: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 106: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 107: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 108: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 109: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 110: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 111: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 112: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 113: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 114: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 115: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 116: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 117: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 118: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 119: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 120: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 121: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 122: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 123: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 124: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 125: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 126: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 127: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 128: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 129: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 130: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 131: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 132: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 133: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 134: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 135: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 136: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 137: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 138: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 139: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 140: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 141: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 142: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 143: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 144: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 145: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 146: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 147: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 148: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 149: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 150: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 151: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 152: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 153: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 154: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 155: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 156: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 157: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 158: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 159: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 160: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 161: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 162: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 163: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 164: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 165: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 166: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 167: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 168: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 169: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 170: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 171: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 172: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 173: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 174: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 175: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 176: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 177: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 178: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 179: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 180: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 181: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 182: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 183: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 184: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 185: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 186: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 187: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 188: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 189: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 190: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 191: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 192: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 193: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 194: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 195: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 196: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 197: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 198: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 199: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 200: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 201: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 202: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 203: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 204: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 205: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 206: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 207: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 208: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 209: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 210: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 211: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 212: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 213: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 214: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 215: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 216: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 217: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 218: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 219: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 220: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 221: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 222: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 223: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 224: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 225: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 226: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 227: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 228: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 229: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 230: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 231: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 232: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 233: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 234: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 235: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 236: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 237: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 238: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 239: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 240: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 241: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 242: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 243: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 244: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 245: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 246: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 247: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 248: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 249: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 0: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 1: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 2: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 3: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 4: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 5: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 6: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 7: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 8: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 9: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 10: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 11: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 12: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 13: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 14: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 15: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 16: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 17: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 18: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 19: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 20: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 21: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 22: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 23: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 24: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 25: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 26: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 27: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 28: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 29: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 30: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 31: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 32: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 33: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 34: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 35: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 36: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 37: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 38: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 39: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 40: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 41: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 42: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 43: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 44: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 45: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 46: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 47: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 48: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 49: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 50: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 51: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 52: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 53: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 54: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 55: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 56: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 57: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 58: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 59: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 60: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 61: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 62: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 63: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 64: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 65: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 66: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 67: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 68: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 69: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 70: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 71: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 72: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 73: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 74: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 75: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 76: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 77: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 78: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 79: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 80: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 81: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 82: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 83: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 84: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 85: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 86: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 87: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 88: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 89: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 90: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 91: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 92: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 93: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 94: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 95: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 96: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 97: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 98: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 99: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 100: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 101: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 102: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 103: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 104: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 105: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 106: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 107: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 108: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 109: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 110: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 111: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 112: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 113: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 114: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 115: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 116: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 117: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 118: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 119: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 120: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 121: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 122: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 123: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 124: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 125: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 126: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 127: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 128: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 129: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 130: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 131: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 132: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 133: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 134: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 135: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 136: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 137: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 138: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 139: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 140: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 141: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 142: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 143: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 144: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 145: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 146: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 147: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 148: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 149: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 150: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 151: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 152: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 153: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 154: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 155: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 156: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 157: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 158: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 159: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 160: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 161: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 162: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 163: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 164: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 165: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 166: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 167: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 168: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 169: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 170: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 171: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 172: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 173: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 174: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 175: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 176: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 177: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 178: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 179: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 180: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 181: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 182: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 183: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 184: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 185: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 186: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 187: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 188: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 189: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 190: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 191: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 192: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 193: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 194: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 195: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 196: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 197: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 198: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 199: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 200: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 201: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 202: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 203: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 204: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 205: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 206: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 207: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 208: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 209: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 210: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 211: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 212: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 213: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 214: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 215: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 216: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 217: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 218: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 219: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 220: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 221: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 222: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 223: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 224: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 225: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 226: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 227: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 228: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 229: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 230: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 231: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 232: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 233: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 234: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 235: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 236: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 237: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 238: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 239: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 240: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 241: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 242: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 243: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 244: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 245: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 246: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 247: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 248: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 249: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 0: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 1: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 2: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 3: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 4: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 5: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 6: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 7: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 8: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 9: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 10: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 11: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 12: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 13: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 14: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 15: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 16: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 17: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 18: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 19: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 20: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 21: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 22: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 23: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 24: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 25: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 26: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 27: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 28: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 29: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 30: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 31: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 32: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 33: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 34: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 35: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 36: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 37: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 38: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 39: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 40: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 41: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 42: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 43: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 44: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 45: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 46: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 47: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 48: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 49: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 50: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 51: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 52: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 53: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 54: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 55: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 56: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 57: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 58: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 59: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 60: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 61: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 62: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 63: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 64: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 65: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 66: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 67: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 68: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 69: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 70: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 71: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 72: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 73: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 74: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 75: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 76: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 77: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 78: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 79: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 80: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 81: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 82: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 83: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 84: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 85: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 86: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 87: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 88: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 89: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 90: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 91: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 92: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 93: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 94: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 95: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 96: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 97: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 98: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 99: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 100: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 101: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 102: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 103: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 104: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 105: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 106: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 107: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 108: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 109: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 110: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 111: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 112: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 113: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 114: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 115: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 116: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 117: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 118: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 119: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 120: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 121: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 122: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 123: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 124: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 125: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 126: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 127: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 128: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 129: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 130: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 131: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 132: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 133: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 134: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 135: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 136: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 137: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 138: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 139: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 140: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 141: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 142: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 143: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 144: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 145: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 146: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 147: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 148: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 149: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 150: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 151: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 152: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 153: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 154: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 155: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 156: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 157: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 158: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 159: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 160: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 161: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 162: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 163: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 164: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 165: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 166: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 167: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 168: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 169: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 170: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 171: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 172: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 173: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 174: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 175: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 176: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 177: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 178: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 179: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 180: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 181: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 182: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 183: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 184: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 185: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 186: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 187: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 188: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 189: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 190: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 191: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 192: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 193: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 194: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 195: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 196: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 197: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 198: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 199: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 200: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 201: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 202: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 203: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 204: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 205: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 206: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 207: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 208: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 209: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 210: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 211: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 212: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 213: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 214: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 215: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 216: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 217: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 218: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 219: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 220: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 221: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 222: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 223: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 224: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 225: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 226: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 227: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 228: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 229: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 230: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 231: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 232: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 233: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 234: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 235: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 236: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 237: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 238: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 239: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 240: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 241: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 242: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 243: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 244: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 245: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 246: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 247: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 248: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 249: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 0: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 1: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 2: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 3: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 4: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 5: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 6: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 7: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 8: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 9: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 10: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 11: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 12: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 13: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 14: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 15: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 16: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 17: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 18: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 19: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 20: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 21: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 22: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 23: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 24: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 25: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 26: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 27: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 28: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 29: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 30: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 31: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 32: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 33: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 34: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 35: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 36: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 37: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 38: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 39: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 40: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 41: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 42: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 43: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 44: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 45: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 46: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 47: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 48: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 49: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 50: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 51: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 52: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 53: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 54: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 55: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 56: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 57: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 58: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 59: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 60: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 61: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 62: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 63: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 64: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 65: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 66: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 67: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 68: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 69: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 70: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 71: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 72: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 73: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 74: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 75: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 76: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 77: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 78: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 79: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 80: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 81: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 82: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 83: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 84: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 85: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 86: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 87: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 88: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 89: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 90: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 91: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 92: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 93: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 94: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 95: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 96: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 97: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 98: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 99: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 100: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 101: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 102: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 103: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 104: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 105: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 106: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 107: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 108: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 109: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 110: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 111: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 112: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 113: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 114: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 115: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 116: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 117: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 118: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 119: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 120: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 121: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 122: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 123: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 124: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 125: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 126: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 127: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 128: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 129: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 130: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 131: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 132: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 133: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 134: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 135: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 136: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 137: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 138: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 139: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 140: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 141: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 142: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 143: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 144: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 145: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 146: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 147: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 148: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 149: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 150: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 151: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 152: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 153: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 154: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 155: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 156: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 157: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 158: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 159: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 160: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 161: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 162: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 163: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 164: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 165: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 166: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 167: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 168: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 169: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 170: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 171: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 172: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 173: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 174: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 175: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 176: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 177: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 178: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 179: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 180: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 181: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 182: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 183: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 184: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 185: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 186: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 187: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 188: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 189: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 190: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 191: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 192: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 193: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 194: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 195: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 196: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 197: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 198: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 199: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 200: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 201: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 202: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 203: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 204: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 205: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 206: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 207: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 208: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 209: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 210: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 211: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 212: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 213: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 214: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 215: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 216: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 217: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 218: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 219: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 220: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 221: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 222: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 223: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 224: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 225: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 226: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 227: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 228: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 229: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 230: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 231: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 232: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 233: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 234: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 235: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 236: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 237: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 238: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 239: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 240: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 241: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 242: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 243: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 244: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 245: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 246: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 247: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 248: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. +Line 249: This is test content to fill the pipe buffer and trigger deadlock when cat is executed. From 3b2130d0022915c69b1005e55686321c1e7b7a1f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 22 Jan 2026 15:08:35 +0800 Subject: [PATCH 33/53] chore(deps): bump lodash from 4.17.21 to 4.17.23 in /agentscope-examples/boba-tea-shop/frontend in the npm_and_yarn group across 1 directory (#629) Bumps the npm_and_yarn group with 1 update in the /agentscope-examples/boba-tea-shop/frontend directory: [lodash](https://github.com/lodash/lodash). Updates `lodash` from 4.17.21 to 4.17.23

    Commits

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=lodash&package-manager=npm_and_yarn&previous-version=4.17.21&new-version=4.17.23)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore ` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore ` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore ` will remove the ignore condition of the specified dependency and ignore conditions You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/agentscope-ai/agentscope-java/network/alerts).
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .../boba-tea-shop/frontend/package-lock.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/agentscope-examples/boba-tea-shop/frontend/package-lock.json b/agentscope-examples/boba-tea-shop/frontend/package-lock.json index e618344a3..a7f36ab96 100644 --- a/agentscope-examples/boba-tea-shop/frontend/package-lock.json +++ b/agentscope-examples/boba-tea-shop/frontend/package-lock.json @@ -5750,9 +5750,10 @@ } }, "node_modules/lodash": { - "version": "4.17.21", - "resolved": "https://registry.npmmirror.com/lodash/-/lodash-4.17.21.tgz", - "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" + "version": "4.17.23", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz", + "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==", + "license": "MIT" }, "node_modules/lodash-es": { "version": "4.17.23", From da6bd15d535596025e7af38ec75a7421a7aa13f5 Mon Sep 17 00:00:00 2001 From: fang-tech Date: Thu, 22 Jan 2026 15:09:48 +0800 Subject: [PATCH 34/53] refactor(skill): simplify skill lifecycle and improve tool group activation (#615) ## AgentScope-Java Version 1.0.7 ## Description refactor(skill): simplify skill lifecycle and improve tool group activation BREAKING CHANGE: Skill tool groups now persist across conversation turns Changes: - Remove skill deactivation logic from SkillHook's PreCallEvent/PostCallEvent handlers - Move tool group activation from SkillHook to SkillToolFactory - Add Toolkit binding to SkillToolFactory for direct tool group management - Simplify SkillHook to only handle skill prompt injection in PreReasoningEvent Test improvements: - Refactor SkillHookTest to focus on unit testing hook responsibilities - Add SkillRuntimeIntegrationTest for end-to-end skill activation flow - Add tests for SkillBox.bindToolkit() method - Add tests for tool group activation when loading skills - Remove redundant integration tests from SkillHookTest This change ensures that once a skill is loaded, its associated tools remain available throughout the conversation, eliminating the need to reload skills in each turn. The tool group is now automatically activated when a skill is loaded through the load_skill_through_path tool. Fixes: Tool groups being deactivated between conversation turns relate #584 ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../io/agentscope/core/skill/SkillBox.java | 11 +- .../io/agentscope/core/skill/SkillHook.java | 16 - .../core/skill/SkillToolFactory.java | 41 +- .../agentscope/core/skill/SkillBoxTest.java | 58 +++ .../core/skill/SkillBoxToolsTest.java | 97 ++++- .../agentscope/core/skill/SkillHookTest.java | 329 ++++------------ .../skill/SkillRuntimeIntegrationTest.java | 369 ++++++++++++++++++ 7 files changed, 641 insertions(+), 280 deletions(-) create mode 100644 agentscope-core/src/test/java/io/agentscope/core/skill/SkillRuntimeIntegrationTest.java diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java index c7fb46d38..fd400cdc4 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java @@ -43,7 +43,7 @@ public SkillBox() { public SkillBox(Toolkit toolkit) { this.skillPromptProvider = new AgentSkillPromptProvider(skillRegistry); - this.skillToolFactory = new SkillToolFactory(skillRegistry); + this.skillToolFactory = new SkillToolFactory(skillRegistry, toolkit); this.toolkit = toolkit; } @@ -85,6 +85,13 @@ public SkillRegistration registration() { /** * Binds a toolkit to the skill box. * + *

    + * This method binds the toolkit to both the skill box and its internal skill + * tool factory. + * Since ReActAgent uses a deep copy of the Toolkit, rebinding is necessary to + * ensure the + * skill tool factory references the correct toolkit instance. + * * @param toolkit The toolkit to bind to the skill box * @throws IllegalArgumentException if the toolkit is null */ @@ -93,6 +100,8 @@ public void bindToolkit(Toolkit toolkit) { throw new IllegalArgumentException("Toolkit cannot be null"); } this.toolkit = toolkit; + // ReActAgent uses a deep copy of Toolkit, so we need to rebind it here + this.skillToolFactory.bindToolkit(toolkit); } /** diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillHook.java b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillHook.java index bcee48bb9..09bb2481e 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillHook.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillHook.java @@ -17,8 +17,6 @@ import io.agentscope.core.hook.Hook; import io.agentscope.core.hook.HookEvent; -import io.agentscope.core.hook.PostCallEvent; -import io.agentscope.core.hook.PreCallEvent; import io.agentscope.core.hook.PreReasoningEvent; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; @@ -36,22 +34,8 @@ public SkillHook(SkillBox skillBox) { @Override public Mono onEvent(T event) { - // Reset skill state and skill tool group before and after calls - if (event instanceof PreCallEvent preCallEvent) { - skillBox.deactivateAllSkills(); - skillBox.syncToolGroupStates(); - return Mono.just(event); - } - - if (event instanceof PostCallEvent postCallEvent) { - skillBox.deactivateAllSkills(); - skillBox.syncToolGroupStates(); - return Mono.just(event); - } - // Inject skill prompts if (event instanceof PreReasoningEvent preReasoningEvent) { - skillBox.syncToolGroupStates(); String skillPrompt = skillBox.getSkillPrompt(); if (skillPrompt != null && !skillPrompt.isEmpty()) { List inputMessages = new ArrayList<>(preReasoningEvent.getInputMessages()); diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillToolFactory.java b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillToolFactory.java index 3f6da1edc..35681f6ea 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillToolFactory.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillToolFactory.java @@ -18,6 +18,7 @@ import io.agentscope.core.message.ToolResultBlock; import io.agentscope.core.tool.AgentTool; import io.agentscope.core.tool.ToolCallParam; +import io.agentscope.core.tool.Toolkit; import java.util.ArrayList; import java.util.List; import java.util.Map; @@ -33,9 +34,27 @@ class SkillToolFactory { private static final Logger logger = LoggerFactory.getLogger(SkillToolFactory.class); private final SkillRegistry skillRegistry; + private Toolkit toolkit; - SkillToolFactory(SkillRegistry skillRegistry) { + SkillToolFactory(SkillRegistry skillRegistry, Toolkit toolkit) { this.skillRegistry = skillRegistry; + this.toolkit = toolkit; + } + + /** + * Binds a toolkit to the skill tool factory. + * + *

    + * This method binds the toolkit to skill tool factory. + * Since ReActAgent uses a deep copy of the Toolkit, rebinding is necessary to + * ensure the + * skill tool factory references the correct toolkit instance. + * + * @param toolkit The toolkit to bind to the skill tool factory + * @throws IllegalArgumentException if the toolkit is null + */ + void bindToolkit(Toolkit toolkit) { + this.toolkit = toolkit; } /** @@ -228,7 +247,7 @@ private String buildResourceNotFoundMessage( } /** - * Validate skill exists and activate it. + * Validate skill exists and activate it and its tool group. * * @param skillId The unique identifier of the skill * @return The skill instance @@ -239,11 +258,6 @@ private AgentSkill validatedActiveSkill(String skillId) { throw new IllegalArgumentException( String.format("Skill not found: '%s'. Please check the skill ID.", skillId)); } - - // Set skill as active - skillRegistry.setSkillActive(skillId, true); - logger.debug("Activated skill: {}", skillId); - // Get skill AgentSkill skill = skillRegistry.getSkill(skillId); if (skill == null) { @@ -253,6 +267,19 @@ private AgentSkill validatedActiveSkill(String skillId) { + " error.", skillId)); } + // Set skill as active + skillRegistry.setSkillActive(skillId, true); + logger.info("Activated skill: {}", skillId); + + String toolsGroupName = skillRegistry.getRegisteredSkill(skillId).getToolsGroupName(); + if (toolkit.getToolGroup(toolsGroupName) != null) { + toolkit.updateToolGroups(List.of(toolsGroupName), true); + logger.info( + "Activated skill tool group: {} and its tools: {}", + toolsGroupName, + toolkit.getToolGroup(toolsGroupName).getTools()); + } + return skill; } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java index 474cf4d58..b8354a54e 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java @@ -26,6 +26,7 @@ import io.agentscope.core.message.TextBlock; import io.agentscope.core.message.ToolResultBlock; +import io.agentscope.core.message.ToolUseBlock; import io.agentscope.core.tool.AgentTool; import io.agentscope.core.tool.Tool; import io.agentscope.core.tool.ToolCallParam; @@ -238,6 +239,63 @@ void testGetAllSkillIdsWithMultipleSkills() { assertTrue(skillIds.contains(skill3.getSkillId()), "Should contain third skill ID"); } + @Test + @DisplayName("Should bind toolkit and propagate to SkillToolFactory") + void testBindToolkitUpdatesSkillToolFactory() { + // Arrange: Create a new toolkit + Toolkit newToolkit = new Toolkit(); + + // Register a skill with tools + AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); + AgentTool tool = createTestTool("test_tool"); + + skillBox.registration().skill(skill).agentTool(tool).apply(); + skillBox.registerSkillLoadTool(); + + // Act: Bind new toolkit + skillBox.bindToolkit(newToolkit); + + // Register skill load tool to new toolkit + skillBox.registerSkillLoadTool(); + + // Load skill through the new toolkit + AgentTool skillLoader = newToolkit.getTool("load_skill_through_path"); + assertNotNull(skillLoader, "Skill loader should be available in new toolkit"); + + Map loadParams = new HashMap<>(); + loadParams.put("skillId", skill.getSkillId()); + loadParams.put("path", "SKILL.md"); + + ToolCallParam callParam = + ToolCallParam.builder() + .toolUseBlock( + ToolUseBlock.builder() + .id("call-001") + .name("load_skill_through_path") + .input(loadParams) + .build()) + .input(loadParams) + .build(); + + ToolResultBlock result = skillLoader.callAsync(callParam).block(); + + // Assert: Should successfully activate skill through new toolkit + assertNotNull(result, "Should successfully load skill through new toolkit"); + assertFalse(result.getOutput().isEmpty(), "Should have output"); + assertTrue( + skillBox.isSkillActive(skill.getSkillId()), + "Skill should be activated through new toolkit"); + } + + @Test + @DisplayName("Should throw exception when binding null toolkit") + void testBindToolkitWithNullThrowsException() { + assertThrows( + IllegalArgumentException.class, + () -> skillBox.bindToolkit(null), + "Should throw exception when binding null toolkit"); + } + /** * Helper method to create a simple test tool. */ diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxToolsTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxToolsTest.java index 0d51f1d2b..23246a1c2 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxToolsTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxToolsTest.java @@ -18,6 +18,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertTrue; import io.agentscope.core.message.TextBlock; @@ -33,6 +34,7 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import reactor.core.publisher.Mono; class SkillBoxToolsTest { @@ -63,7 +65,9 @@ void setUp() { AgentSkill skill1 = new AgentSkill("test_skill", "Test Skill", "# Test Content", resources1); - skillBox.registerSkill(skill1); + // Register skill1 with a dummy tool to create tool group + AgentTool dummyTool = createDummyTool("test_skill_tool"); + skillBox.registration().skill(skill1).agentTool(dummyTool).apply(); AgentSkill skill2 = new AgentSkill("empty_skill", "Empty Skill", "# Empty", new HashMap<>()); @@ -73,6 +77,30 @@ void setUp() { skillBox.registerSkillLoadTool(); } + private AgentTool createDummyTool(String name) { + return new AgentTool() { + @Override + public String getName() { + return name; + } + + @Override + public String getDescription() { + return "Dummy tool for testing"; + } + + @Override + public Map getParameters() { + return Map.of("type", "object", "properties", Map.of()); + } + + @Override + public Mono callAsync(ToolCallParam param) { + return Mono.just(ToolResultBlock.text("dummy result")); + } + }; + } + @Test @DisplayName("Should create load skill resource tool") void testCreateLoadSkillResourceTool() { @@ -135,13 +163,16 @@ void testLoadSkillMarkdownSuccessfully() { } @Test - @DisplayName("Should activate skill when loading markdown") - void testActivateSkillWhenLoadingMarkdown() { + @DisplayName("Should activate skill and tool group when loading markdown") + void testActivateSkillAndToolGroupWhenLoadingMarkdown() { AgentTool tool = toolkit.getTool("load_skill_through_path"); - assertFalse(skillBox.isSkillActive("test_skill_custom")); + String skillId = "test_skill_custom"; + String toolGroupName = skillId + "_skill_tools"; - Map input = Map.of("skillId", "test_skill_custom", "path", "SKILL.md"); + assertFalse(skillBox.isSkillActive(skillId)); + + Map input = Map.of("skillId", skillId, "path", "SKILL.md"); ToolUseBlock toolUseBlock = ToolUseBlock.builder() .id("test-call-002") @@ -152,7 +183,12 @@ void testActivateSkillWhenLoadingMarkdown() { ToolCallParam.builder().toolUseBlock(toolUseBlock).input(input).build(); tool.callAsync(param).block(TIMEOUT); - assertTrue(skillBox.isSkillActive("test_skill_custom")); + assertTrue(skillBox.isSkillActive(skillId), "Skill should be activated"); + // Tool group should also be activated when skill is loaded + assertNotNull(toolkit.getToolGroup(toolGroupName), "Tool group should exist"); + assertTrue( + toolkit.getToolGroup(toolGroupName).isActive(), + "Tool group should be activated when skill is loaded"); } @Test @@ -247,13 +283,16 @@ void testLoadSkillResourceSuccessfully() { } @Test - @DisplayName("Should activate skill when loading resource") - void testActivateSkillWhenLoadingResource() { + @DisplayName("Should activate skill and tool group when loading resource") + void testActivateSkillAndToolGroupWhenLoadingResource() { AgentTool tool = toolkit.getTool("load_skill_through_path"); - assertFalse(skillBox.isSkillActive("test_skill_custom")); + String skillId = "test_skill_custom"; + String toolGroupName = skillId + "_skill_tools"; + + assertFalse(skillBox.isSkillActive(skillId)); - Map input = Map.of("skillId", "test_skill_custom", "path", "data.txt"); + Map input = Map.of("skillId", skillId, "path", "data.txt"); ToolUseBlock toolUseBlock = ToolUseBlock.builder() .id("test-call-007") @@ -264,7 +303,12 @@ void testActivateSkillWhenLoadingResource() { ToolCallParam.builder().toolUseBlock(toolUseBlock).input(input).build(); tool.callAsync(param).block(TIMEOUT); - assertTrue(skillBox.isSkillActive("test_skill_custom")); + assertTrue(skillBox.isSkillActive(skillId), "Skill should be activated"); + // Tool group should also be activated when skill is loaded + assertNotNull(toolkit.getToolGroup(toolGroupName), "Tool group should exist"); + assertTrue( + toolkit.getToolGroup(toolGroupName).isActive(), + "Tool group should be activated when skill is loaded"); } @Test @@ -408,4 +452,35 @@ void testHandleWhitespaceInResourcePath() { assertNotNull(result); assertTrue(isErrorResult(result)); } + + @Test + @DisplayName("Should handle skill with no tools gracefully") + void testLoadSkillWithNoToolsDoesNotFail() { + // Skill without tools - tool group won't exist + AgentSkill emptySkill = new AgentSkill("no_tools_skill", "No Tools", "# Empty", null); + skillBox.registerSkill(emptySkill); + + String skillId = emptySkill.getSkillId(); + + // Load skill + AgentTool loader = toolkit.getTool("load_skill_through_path"); + Map input = Map.of("skillId", skillId, "path", "SKILL.md"); + ToolUseBlock toolUseBlock = + ToolUseBlock.builder() + .id("test-call-015") + .name("load_skill_through_path") + .input(input) + .build(); + ToolCallParam param = + ToolCallParam.builder().toolUseBlock(toolUseBlock).input(input).build(); + + ToolResultBlock result = loader.callAsync(param).block(TIMEOUT); + + // Should succeed even without tool group + assertNotNull(result); + assertFalse(isErrorResult(result), "Should not fail when skill has no tools"); + assertTrue(skillBox.isSkillActive(skillId), "Skill should still be activated"); + assertNull( + toolkit.getToolGroup(skillId + "_skill_tools"), "Tool group should not be created"); + } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillHookTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillHookTest.java index c844fb21e..dbd72778d 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillHookTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillHookTest.java @@ -16,31 +16,23 @@ package io.agentscope.core.skill; import static org.junit.jupiter.api.Assertions.assertEquals; -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.agent.Agent; import io.agentscope.core.agent.AgentBase; import io.agentscope.core.hook.Hook; -import io.agentscope.core.hook.PostCallEvent; -import io.agentscope.core.hook.PreCallEvent; import io.agentscope.core.hook.PreReasoningEvent; import io.agentscope.core.interruption.InterruptContext; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; -import io.agentscope.core.message.ToolResultBlock; import io.agentscope.core.message.ToolUseBlock; import io.agentscope.core.model.GenerateOptions; -import io.agentscope.core.tool.AgentTool; import io.agentscope.core.tool.ToolCallParam; import io.agentscope.core.tool.Toolkit; import java.util.ArrayList; -import java.util.Collections; -import java.util.HashMap; import java.util.List; -import java.util.Map; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Tag; @@ -50,7 +42,9 @@ /** * Unit tests for SkillHook. * - *

    These tests verify Hook lifecycle. + *

    + * These tests verify that SkillHook correctly injects skill prompts during + * PreReasoningEvent. */ @Tag("unit") class SkillHookTest { @@ -64,183 +58,103 @@ void setUp() { toolkit = new Toolkit(); skillBox = new SkillBox(toolkit); skillHook = new SkillHook(skillBox); - skillBox.registerSkillLoadTool(); + skillBox.registerSkillLoadTool(); // Register skill loader tool testAgent = new TestAgent("test-agent"); - AgentSkill skill = new AgentSkill("empty_skill", "Empty Skill", "# Empty", null); - skillBox.registration().skill(skill).apply(); // Should handle skill with no tools correctly } - // ==================== Hook Lifecycle Tests ==================== - @Test - @DisplayName("Step 0: Initial state - skill and toolGroup should be inactive") - void testStep0_InitialState() { - // Arrange: Setup skill with tools - AgentTool skillTool1 = createTestTool("calculator_add"); - AgentTool skillTool2 = createTestTool("calculator_multiply"); - - AgentSkill calculatorSkill = - new AgentSkill( - "calculator", - "Calculator Skill", - "# Calculator\nProvides math operations", - null); - - // Register skill with its tools - skillBox.registration().skill(calculatorSkill).agentTool(skillTool1).apply(); - skillBox.registration().skill(calculatorSkill).agentTool(skillTool2).apply(); - - String skillId = calculatorSkill.getSkillId(); - String toolGroupName = skillId + "_skill_tools"; + @DisplayName("Should inject skill prompt when skills are active") + void testInjectSkillPromptWhenSkillsActive() { + // Arrange: Register a skill and activate it using the loader tool + AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Test Content", null); + skillBox.registerSkill(skill); - // Assert: Verify initial state - assertFalse(skillBox.isSkillActive(skillId), "Skill should be inactive initially"); - assertNotNull( - toolkit.getToolGroup(toolGroupName), "ToolGroup should exist after registration"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be inactive initially"); - assertEquals("calculator_add", toolkit.getTool("calculator_add").getName()); - assertEquals("calculator_multiply", toolkit.getTool("calculator_multiply").getName()); - } - - @Test - @DisplayName("Step 1: PreCallEvent should not change inactive state") - void testStep1_PreCallEventOnInactiveState() { - // Arrange: Setup skill - AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); - AgentTool skillTool = createTestTool("test_tool"); + // Activate skill by calling the loader tool (this is how skills are activated + // in practice) + activateSkill(skill.getSkillId()); - skillBox.registration().skill(skill).agentTool(skillTool).apply(); + // Verify skill is now active + assertTrue(skillBox.isSkillActive(skill.getSkillId()), "Skill should be active"); - String skillId = skill.getSkillId(); - String toolGroupName = skillId + "_skill_tools"; + // Create PreReasoningEvent with one user message + List messages = new ArrayList<>(); + messages.add( + Msg.builder() + .role(MsgRole.USER) + .content(TextBlock.builder().text("User query").build()) + .build()); - // Verify pre-state - assertFalse(skillBox.isSkillActive(skillId), "Skill should be inactive before PreCall"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be inactive before PreCall"); + PreReasoningEvent event = + new PreReasoningEvent( + testAgent, "test-model", GenerateOptions.builder().build(), messages); - // Act: Trigger PreCallEvent - PreCallEvent preCallEvent = new PreCallEvent(testAgent, Collections.emptyList()); - skillHook.onEvent(preCallEvent).block(); + // Act: Process event through hook + PreReasoningEvent result = skillHook.onEvent(event).block(); - // Assert: State should remain inactive - assertFalse( - skillBox.isSkillActive(skillId), "Skill should remain inactive after PreCallEvent"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should remain inactive after PreCallEvent"); + // Assert: Skill prompt should be injected + assertNotNull(result, "Event should be processed"); + assertEquals(2, result.getInputMessages().size(), "Should add skill prompt message"); + assertEquals( + MsgRole.SYSTEM, + result.getInputMessages().get(1).getRole(), + "Skill prompt should be SYSTEM message"); + assertTrue( + result.getInputMessages().get(1).getContent().toString().contains("test_skill"), + "Skill prompt should contain skill information"); } - @Test - @DisplayName("Step 2: SkillLoaderTool should activate skill but not toolGroup") - void testStep2_SkillLoaderActivatesSkillOnly() { - // Arrange: Setup skill with tools - AgentTool skillTool = createTestTool("test_tool"); - AgentSkill skill = new AgentSkill("calculator", "Calculator", "# Calc", null); - - skillBox.registration().skill(skill).agentTool(skillTool).apply(); - - String skillId = skill.getSkillId(); - String toolGroupName = skillId + "_skill_tools"; - - // Verify pre-state - assertFalse(skillBox.isSkillActive(skillId), "Skill should be inactive before loading"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be inactive before loading"); - - // Act: Mock LLM calling skill loader tool - AgentTool skillLoader = toolkit.getTool("load_skill_through_path"); - Map loadParams = new HashMap<>(); - loadParams.put("skillId", skillId); - loadParams.put("path", "SKILL.md"); - - ToolUseBlock toolUseBlock = - ToolUseBlock.builder() - .id("call-001") - .name("load_skill_through_path") - .input(loadParams) - .build(); - - ToolCallParam callParam = - ToolCallParam.builder().toolUseBlock(toolUseBlock).input(loadParams).build(); - - ToolResultBlock result = skillLoader.callAsync(callParam).block(); - - // Assert: Skill activated, but toolGroup still inactive - assertNotNull(result, "SkillLoader should return result"); - assertTrue( - skillBox.isSkillActive(skillId), - "Skill should be activated after loader tool call"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should still be inactive (not activated until PreReasoning)"); + /** + * Helper method to activate a skill using the loader tool. + */ + private void activateSkill(String skillId) { + toolkit.getTool("load_skill_through_path") + .callAsync( + ToolCallParam.builder() + .toolUseBlock( + ToolUseBlock.builder() + .id("test-call") + .name("load_skill_through_path") + .input( + java.util.Map.of( + "skillId", + skillId, + "path", + "SKILL.md")) + .build()) + .input(java.util.Map.of("skillId", skillId, "path", "SKILL.md")) + .build()) + .block(); } @Test - @DisplayName("Step 3: PreReasoningEvent should activate toolGroup for active skills") - void testStep3_PreReasoningEventActivatesToolGroup() { - // Arrange: Setup skill and activate it - AgentTool skillTool = createTestTool("calc_tool"); - AgentSkill skill = new AgentSkill("math", "Math Skill", "# Math", null); - - skillBox.registration().skill(skill).agentTool(skillTool).apply(); - - String skillId = skill.getSkillId(); - String toolGroupName = skillId + "_skill_tools"; - - // Load skill via loader tool (simulate LLM) - AgentTool skillLoader = toolkit.getTool("load_skill_through_path"); - Map loadParams = new HashMap<>(); - loadParams.put("skillId", skillId); - loadParams.put("path", "SKILL.md"); - - ToolCallParam callParam = - ToolCallParam.builder() - .toolUseBlock( - ToolUseBlock.builder() - .id("call-001") - .name("load_skill_through_path") - .input(loadParams) - .build()) - .input(loadParams) - .build(); + @DisplayName("Should inject prompt even when skills are registered but not active") + void testInjectPromptForRegisteredSkills() { + // Arrange: Register skill but don't activate it + // Note: SkillPromptProvider returns prompt for all registered skills, not just + // active ones + AgentSkill skill = new AgentSkill("inactive_skill", "Inactive Skill", "# Inactive", null); + skillBox.registerSkill(skill); - skillLoader.callAsync(callParam).block(); - - // Verify skill is active, toolGroup is not - assertTrue(skillBox.isSkillActive(skillId), "Skill should be active before PreReasoning"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be inactive before PreReasoning"); - - // Act: Trigger PreReasoningEvent List messages = new ArrayList<>(); messages.add( Msg.builder() .role(MsgRole.USER) - .content(TextBlock.builder().text("Calculate").build()) + .content(TextBlock.builder().text("User query").build()) .build()); - PreReasoningEvent preReasoningEvent = + PreReasoningEvent event = new PreReasoningEvent( testAgent, "test-model", GenerateOptions.builder().build(), messages); - PreReasoningEvent result = skillHook.onEvent(preReasoningEvent).block(); - // Assert: ToolGroup should now be activated - assertNotNull(result, "PreReasoningEvent should be processed"); - assertTrue( - skillBox.isSkillActive(skillId), "Skill should remain active after PreReasoning"); - assertTrue( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be activated after PreReasoningEvent"); + // Act: Process event through hook + PreReasoningEvent result = skillHook.onEvent(event).block(); - // Verify skill prompt was added + // Assert: Skill prompt should be added for registered skills + assertNotNull(result, "Event should be processed"); assertEquals( - 2, result.getInputMessages().size(), "Should add skill prompt to input messages"); + 2, + result.getInputMessages().size(), + "Should add skill prompt for registered skills"); assertEquals( MsgRole.SYSTEM, result.getInputMessages().get(1).getRole(), @@ -248,74 +162,30 @@ void testStep3_PreReasoningEventActivatesToolGroup() { } @Test - @DisplayName("Step 4: PostCallEvent should deactivate both skill and toolGroup") - void testStep4_PostCallEventDeactivatesAll() { - // Arrange: Setup and activate skill - AgentTool skillTool = createTestTool("tool1"); - AgentSkill skill = new AgentSkill("weather", "Weather Skill", "# Weather", null); - - skillBox.registration().skill(skill).agentTool(skillTool).apply(); - - String skillId = skill.getSkillId(); - String toolGroupName = skillId + "_skill_tools"; - - // Activate skill via loader tool - AgentTool skillLoader = toolkit.getTool("load_skill_through_path"); - Map loadParams = new HashMap<>(); - loadParams.put("skillId", skillId); - loadParams.put("path", "SKILL.md"); - - ToolCallParam callParam = - ToolCallParam.builder() - .toolUseBlock( - ToolUseBlock.builder() - .id("call-001") - .name("load_skill_through_path") - .input(loadParams) - .build()) - .input(loadParams) - .build(); - - skillLoader.callAsync(callParam).block(); - - // Activate toolGroup via PreReasoningEvent + @DisplayName("Should handle empty skill prompt gracefully") + void testHandleEmptySkillPromptGracefully() { + // Arrange: No skills registered at all List messages = new ArrayList<>(); messages.add( Msg.builder() .role(MsgRole.USER) - .content(TextBlock.builder().text("Weather query").build()) + .content(TextBlock.builder().text("User query").build()) .build()); - PreReasoningEvent preReasoningEvent = + PreReasoningEvent event = new PreReasoningEvent( testAgent, "test-model", GenerateOptions.builder().build(), messages); - skillHook.onEvent(preReasoningEvent).block(); - // Verify both are active - assertTrue(skillBox.isSkillActive(skillId), "Skill should be active before PostCallEvent"); - assertTrue( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be active before PostCallEvent"); + // Act: Process event through hook + PreReasoningEvent result = skillHook.onEvent(event).block(); - // Act: Trigger PostCallEvent - Msg responseMsg = - Msg.builder() - .role(MsgRole.ASSISTANT) - .content(TextBlock.builder().text("Weather response").build()) - .build(); - PostCallEvent postCallEvent = new PostCallEvent(testAgent, responseMsg); - skillHook.onEvent(postCallEvent).block(); - - // Assert: Both should be deactivated - assertFalse( - skillBox.isSkillActive(skillId), "Skill should be deactivated after PostCallEvent"); - assertFalse( - toolkit.getToolGroup(toolGroupName).isActive(), - "ToolGroup should be deactivated after PostCallEvent"); + // Assert: Should handle gracefully without adding prompt + assertNotNull(result, "Event should be processed"); + assertEquals(1, result.getInputMessages().size(), "Should not add empty skill prompt"); } @Test - @DisplayName("Should verify Hook priority") + @DisplayName("Should return correct hook priority") void testHookPriority() { assertEquals(10, skillHook.priority(), "Skill hook should have high priority (10)"); } @@ -353,35 +223,4 @@ protected Mono handleInterrupt(InterruptContext context, Msg... originalArg .build()); } } - - /** - * Helper method to create a simple test tool. - */ - private AgentTool createTestTool(String name) { - return new AgentTool() { - @Override - public String getName() { - return name; - } - - @Override - public String getDescription() { - return "Test tool: " + name; - } - - @Override - public Map getParameters() { - Map schema = new HashMap<>(); - schema.put("type", "object"); - schema.put("properties", new HashMap()); - return schema; - } - - @Override - public Mono callAsync(ToolCallParam param) { - return Mono.just( - ToolResultBlock.of(TextBlock.builder().text("Test result").build())); - } - }; - } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillRuntimeIntegrationTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillRuntimeIntegrationTest.java new file mode 100644 index 000000000..fdcd409f9 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillRuntimeIntegrationTest.java @@ -0,0 +1,369 @@ +/* + * 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.skill; + +import static org.junit.jupiter.api.Assertions.assertEquals; +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.agent.Agent; +import io.agentscope.core.agent.AgentBase; +import io.agentscope.core.hook.Hook; +import io.agentscope.core.hook.PreReasoningEvent; +import io.agentscope.core.interruption.InterruptContext; +import io.agentscope.core.message.Msg; +import io.agentscope.core.message.MsgRole; +import io.agentscope.core.message.TextBlock; +import io.agentscope.core.message.ToolResultBlock; +import io.agentscope.core.message.ToolUseBlock; +import io.agentscope.core.model.GenerateOptions; +import io.agentscope.core.tool.AgentTool; +import io.agentscope.core.tool.ToolCallParam; +import io.agentscope.core.tool.Toolkit; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import reactor.core.publisher.Mono; + +/** + * Integration tests for Skill runtime flow. + * + *

    + * These tests verify the complete skill activation and usage flow, including: + *

      + *
    • Skill and tool group activation when loading skills
      • + *
    • Tool availability after skill activation
      • + *
    • Multi-turn conversation with persistent tool activation
      • + *
    • Integration with ReActAgent
      • + *
    + */ +@Tag("integration") +class SkillRuntimeIntegrationTest { + private SkillBox skillBox; + private Toolkit toolkit; + private Agent testAgent; + private Hook skillHook; + + @BeforeEach + void setUp() { + toolkit = new Toolkit(); + skillBox = new SkillBox(toolkit); + skillHook = new SkillHook(skillBox); + skillBox.registerSkillLoadTool(); + testAgent = new TestAgent("test-agent"); + } + + // ==================== Simulated Integration Tests ==================== + + @Test + @DisplayName("Complete skill activation flow without real agent") + void testCompleteSkillActivationFlow() { + // Step 1: Setup skill with tools + AgentTool calculatorAdd = createCalculatorTool("calculator_add", "Add two numbers"); + AgentTool calculatorMultiply = + createCalculatorTool("calculator_multiply", "Multiply two numbers"); + + AgentSkill calculatorSkill = + new AgentSkill( + "calculator", + "Calculator Skill", + "# Calculator\nProvides math operations", + null); + + skillBox.registration().skill(calculatorSkill).agentTool(calculatorAdd).apply(); + skillBox.registration().skill(calculatorSkill).agentTool(calculatorMultiply).apply(); + + String skillId = calculatorSkill.getSkillId(); + String toolGroupName = skillId + "_skill_tools"; + + // Step 2: Verify initial state - skill and tool group inactive + assertFalse(skillBox.isSkillActive(skillId), "Skill should be inactive initially"); + assertNotNull(toolkit.getToolGroup(toolGroupName), "ToolGroup should exist"); + assertFalse( + toolkit.getToolGroup(toolGroupName).isActive(), + "ToolGroup should be inactive initially"); + + // Step 3: Simulate LLM calling load_skill_through_path + AgentTool skillLoader = toolkit.getTool("load_skill_through_path"); + Map loadParams = new HashMap<>(); + loadParams.put("skillId", skillId); + loadParams.put("path", "SKILL.md"); + + ToolCallParam callParam = + ToolCallParam.builder() + .toolUseBlock( + ToolUseBlock.builder() + .id("call-001") + .name("load_skill_through_path") + .input(loadParams) + .build()) + .input(loadParams) + .build(); + + ToolResultBlock loadResult = skillLoader.callAsync(callParam).block(); + + // Step 4: Verify skill and tool group are both activated + assertNotNull(loadResult, "Load result should not be null"); + assertFalse(loadResult.getOutput().isEmpty(), "Load should succeed"); + assertTrue(skillBox.isSkillActive(skillId), "Skill should be activated after loading"); + assertTrue( + toolkit.getToolGroup(toolGroupName).isActive(), + "ToolGroup should be activated when skill is loaded"); + + // Step 5: Verify tools are accessible + assertNotNull(toolkit.getTool("calculator_add"), "calculator_add should be accessible"); + assertNotNull( + toolkit.getTool("calculator_multiply"), "calculator_multiply should be accessible"); + + // Step 6: Trigger PreReasoningEvent to inject skill prompt + List messages = new ArrayList<>(); + messages.add( + Msg.builder() + .role(MsgRole.USER) + .content(TextBlock.builder().text("Calculate 2 + 3").build()) + .build()); + + PreReasoningEvent preReasoningEvent = + new PreReasoningEvent( + testAgent, "test-model", GenerateOptions.builder().build(), messages); + PreReasoningEvent result = skillHook.onEvent(preReasoningEvent).block(); + + // Step 7: Verify skill prompt was injected + assertNotNull(result, "PreReasoningEvent should be processed"); + assertEquals( + 2, result.getInputMessages().size(), "Should add skill prompt to input messages"); + assertEquals( + MsgRole.SYSTEM, + result.getInputMessages().get(1).getRole(), + "Skill prompt should be SYSTEM message"); + + // Step 8: Verify skill and tool group remain active + assertTrue(skillBox.isSkillActive(skillId), "Skill should remain active"); + assertTrue( + toolkit.getToolGroup(toolGroupName).isActive(), "ToolGroup should remain active"); + } + + @Test + @DisplayName("Multiple skills activation in sequence") + void testMultipleSkillsActivationSequence() { + // Setup multiple skills + AgentSkill mathSkill = new AgentSkill("math", "Math Skill", "# Math", null); + AgentSkill weatherSkill = new AgentSkill("weather", "Weather Skill", "# Weather", null); + + AgentTool mathTool = createCalculatorTool("math_add", "Math addition"); + AgentTool weatherTool = createCalculatorTool("get_weather", "Get weather"); + + skillBox.registration().skill(mathSkill).agentTool(mathTool).apply(); + skillBox.registration().skill(weatherSkill).agentTool(weatherTool).apply(); + + String mathSkillId = mathSkill.getSkillId(); + String weatherSkillId = weatherSkill.getSkillId(); + String mathToolGroupName = mathSkillId + "_skill_tools"; + String weatherToolGroupName = weatherSkillId + "_skill_tools"; + + // Load first skill + loadSkill(mathSkillId); + + // Verify first skill activated + assertTrue(skillBox.isSkillActive(mathSkillId), "Math skill should be activated"); + assertTrue( + toolkit.getToolGroup(mathToolGroupName).isActive(), + "Math tool group should be activated"); + assertFalse( + skillBox.isSkillActive(weatherSkillId), "Weather skill should still be inactive"); + assertFalse( + toolkit.getToolGroup(weatherToolGroupName).isActive(), + "Weather tool group should still be inactive"); + + // Load second skill + loadSkill(weatherSkillId); + + // Verify both skills activated + assertTrue(skillBox.isSkillActive(mathSkillId), "Math skill should remain activated"); + assertTrue(skillBox.isSkillActive(weatherSkillId), "Weather skill should be activated"); + assertTrue( + toolkit.getToolGroup(mathToolGroupName).isActive(), + "Math tool group should remain activated"); + assertTrue( + toolkit.getToolGroup(weatherToolGroupName).isActive(), + "Weather tool group should be activated"); + assertTrue( + toolkit.getActiveGroups().contains(mathToolGroupName), + "Math tool group should be activated"); + assertTrue( + toolkit.getActiveGroups().contains(weatherToolGroupName), + "Weather tool group should be activated"); + } + + @Test + @DisplayName("Skill with actual tools integration") + void testSkillWithActualToolsIntegration() { + // Create a skill with a functional tool + AgentTool counterTool = + new AgentTool() { + private int count = 0; + + @Override + public String getName() { + return "increment_counter"; + } + + @Override + public String getDescription() { + return "Increment a counter"; + } + + @Override + public Map getParameters() { + return Map.of("type", "object", "properties", Map.of()); + } + + @Override + public Mono callAsync(ToolCallParam param) { + count++; + return Mono.just(ToolResultBlock.text("Counter: " + count)); + } + }; + + AgentSkill counterSkill = new AgentSkill("counter", "Counter Skill", "# Counter", null); + skillBox.registration().skill(counterSkill).agentTool(counterTool).apply(); + + String skillId = counterSkill.getSkillId(); + + // Load skill + loadSkill(skillId); + + // Verify skill activated + assertTrue(skillBox.isSkillActive(skillId), "Skill should be activated"); + + // Call the tool multiple times + AgentTool tool = toolkit.getTool("increment_counter"); + assertNotNull(tool, "Tool should be accessible"); + + ToolCallParam callParam = + ToolCallParam.builder() + .toolUseBlock( + ToolUseBlock.builder() + .id("call-001") + .name("increment_counter") + .input(Map.of()) + .build()) + .input(Map.of()) + .build(); + + ToolResultBlock result1 = tool.callAsync(callParam).block(); + assertTrue(result1.getOutput().get(0).toString().contains("Counter: 1")); + + ToolResultBlock result2 = tool.callAsync(callParam).block(); + assertTrue(result2.getOutput().get(0).toString().contains("Counter: 2")); + } + + // ==================== Helper Methods ==================== + + /** + * Helper method to load a skill by calling the load_skill_through_path tool. + */ + private void loadSkill(String skillId) { + AgentTool skillLoader = toolkit.getTool("load_skill_through_path"); + Map loadParams = new HashMap<>(); + loadParams.put("skillId", skillId); + loadParams.put("path", "SKILL.md"); + + ToolCallParam callParam = + ToolCallParam.builder() + .toolUseBlock( + ToolUseBlock.builder() + .id("call-" + System.currentTimeMillis()) + .name("load_skill_through_path") + .input(loadParams) + .build()) + .input(loadParams) + .build(); + + skillLoader.callAsync(callParam).block(); + } + + /** + * Helper method to create a simple calculator tool. + */ + private AgentTool createCalculatorTool(String name, String description) { + return new AgentTool() { + @Override + public String getName() { + return name; + } + + @Override + public String getDescription() { + return description; + } + + @Override + public Map getParameters() { + Map schema = new HashMap<>(); + schema.put("type", "object"); + schema.put("properties", new HashMap()); + return schema; + } + + @Override + public Mono callAsync(ToolCallParam param) { + return Mono.just( + ToolResultBlock.of(TextBlock.builder().text("Result: 42").build())); + } + }; + } + + /** + * Simple test agent for testing Hook events. + */ + private static class TestAgent extends AgentBase { + TestAgent(String name) { + super(name); + } + + @Override + protected Mono doCall(List msgs) { + return Mono.just( + Msg.builder() + .name(getName()) + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Test response").build()) + .build()); + } + + @Override + protected Mono doObserve(Msg msg) { + return Mono.empty(); + } + + @Override + protected Mono handleInterrupt(InterruptContext context, Msg... originalArgs) { + return Mono.just( + Msg.builder() + .name(getName()) + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Interrupted").build()) + .build()); + } + } +} From 4a1c0943e0a9b885ef0e90471c9d29440aa6bdda Mon Sep 17 00:00:00 2001 From: fang-tech Date: Thu, 22 Jan 2026 15:11:23 +0800 Subject: [PATCH 35/53] feat(skill): Add code execution capabilities to SkillBox (#614) ## AgentScope-Java Version 1.0.7 ## Description - Add enableCodeExecution() methods to SkillBox supporting both temporary and custom working directories - Implement automatic script extraction and organization by skill ID (workDir/skillId/script.py) - Enhance ShellCommandTool with baseDir support to prevent command escape - Add getScriptResources() method to AgentSkill for identifying executable scripts (.py, .js, .sh) - Register three sandboxed tools: ShellCommandTool, ReadFileTool, WriteFileTool in skill_code_execution_tool_group - Implement lazy directory creation: directories created on write, not on enable - Add comprehensive test coverage with 21 tests for code execution scenarios ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../java/io/agentscope/core/ReActAgent.java | 6 + .../io/agentscope/core/skill/AgentSkill.java | 38 ++ .../io/agentscope/core/skill/SkillBox.java | 251 ++++++++ .../core/tool/coding/ShellCommandTool.java | 58 +- .../agentscope/core/skill/AgentSkillTest.java | 85 +++ .../agentscope/core/skill/SkillBoxTest.java | 598 +++++++++++++----- 6 files changed, 875 insertions(+), 161 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java index c6b7ab8af..e37ed93bb 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java @@ -1512,6 +1512,7 @@ public Mono onEvent(T event) { *
      *
    • Registers skill load tool to the toolkit *
    • Adds the skill hook to inject skill prompts and manage skill activation + *
    • Writes skill scripts to baseDir if code execution is enabled *
    */ private void configureSkillBox(Toolkit agentToolkit) { @@ -1519,6 +1520,11 @@ private void configureSkillBox(Toolkit agentToolkit) { // Register skill loader tools to toolkit skillBox.registerSkillLoadTool(); + // If code execution is enabled, write skill scripts to workDir + if (skillBox.isCodeExecutionEnabled()) { + skillBox.writeSkillScriptsToWorkDir(); + } + hooks.add(new SkillHook(skillBox)); } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkill.java b/agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkill.java index 43e05fc4b..94dcc3e33 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkill.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkill.java @@ -18,6 +18,7 @@ import java.util.HashMap; import java.util.Map; +import java.util.Set; /** * Represents an agent skill that can be loaded and used by agents. @@ -59,6 +60,8 @@ * @see io.agentscope.core.skill.util.MarkdownSkillParser */ public class AgentSkill { + private static final Set SCRIPT_EXTENSIONS = Set.of(".py", ".js", ".sh"); + private final String name; private final String description; private final String skillContent; @@ -174,6 +177,41 @@ public String getSkillId() { return name + "_" + source; } + /** + * Gets script resources from the skill's resources. + * + *

    + * A resource is considered a script if: + *

      + *
    • It is located in the "scripts/" directory, OR
      • + *
    • It has a script file extension (.py, .js, .sh) + *
      • + *
    + * + * @return Map of script resources (path -> content), never null, may be empty + */ + public Map getScriptResources() { + Map scripts = new HashMap<>(); + for (Map.Entry entry : resources.entrySet()) { + String path = entry.getKey(); + // Check if in scripts/ folder or has script extension + if (path.startsWith("scripts/") || hasScriptExtension(path)) { + scripts.put(path, entry.getValue()); + } + } + return scripts; + } + + /** + * Checks if a file path has a script extension. + * + * @param path The file path to check + * @return true if the path ends with a known script extension + */ + private boolean hasScriptExtension(String path) { + return SCRIPT_EXTENSIONS.stream().anyMatch(path::endsWith); + } + /** * Creates a builder initialized with this skill's values. * diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java index fd400cdc4..478a43afc 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java @@ -19,9 +19,17 @@ import io.agentscope.core.tool.AgentTool; import io.agentscope.core.tool.ExtendedModel; import io.agentscope.core.tool.Toolkit; +import io.agentscope.core.tool.coding.ShellCommandTool; +import io.agentscope.core.tool.file.ReadFileTool; +import io.agentscope.core.tool.file.WriteFileTool; import io.agentscope.core.tool.mcp.McpClientWrapper; import io.agentscope.core.tool.subagent.SubAgentConfig; import io.agentscope.core.tool.subagent.SubAgentProvider; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; import java.util.ArrayList; import java.util.List; import java.util.Map; @@ -36,6 +44,7 @@ public class SkillBox implements StateModule { private final AgentSkillPromptProvider skillPromptProvider; private final SkillToolFactory skillToolFactory; private Toolkit toolkit; + private Path codeExecutionWorkDir; public SkillBox() { this(null); @@ -536,4 +545,246 @@ public void registerSkillLoadTool() { logger.info("Registered skill load tools to toolkit"); } + + // ==================== Code Execution ==================== + + /** + * Enables code execution capabilities for skills with temporary working directory. + * + *

    This method creates a sandboxed environment for executing scripts from skills. + * A temporary directory will be created when scripts are written. + * + * @throws IllegalStateException if toolkit is not bound + */ + public void enableCodeExecution() { + enableCodeExecution(null); + } + + /** + * Enables code execution capabilities for skills. + * + *

    This method creates a sandboxed environment for executing scripts from skills by: + *

      + *
    • Registering ShellCommandTool with allowed commands (python, python3, node, nodejs)
      • + *
    • Registering ReadFileTool and WriteFileTool restricted to the working directory
      • + *
    • Creating and activating the "skill_code_execution_tool_group" tool group
      • + *
    + * + *

    After calling this method, scripts from registered skills will be written to the + * working directory when the agent is configured. + * + *

    + * Note: This method should only be called once. Calling it multiple + * times + * will throw an IllegalStateException. + * + * @param workDir Working directory for code execution. If null or empty, a + * temporary + * directory will be created when scripts are written. + * @throws IllegalStateException if toolkit is not bound or if code execution is + * already enabled + */ + public void enableCodeExecution(String workDir) { + if (toolkit == null) { + throw new IllegalStateException("Must bind toolkit before enabling code execution"); + } + + // Prevent duplicate enablement + if (isCodeExecutionEnabled()) { + throw new IllegalStateException( + "Code execution is already enabled. This method should only be called once."); + } + + // Set workDir (null means temporary directory will be created later) + if (workDir == null || workDir.isEmpty()) { + this.codeExecutionWorkDir = null; + } else { + this.codeExecutionWorkDir = Paths.get(workDir).toAbsolutePath().normalize(); + } + + // Create tool group + if (toolkit.getToolGroup("skill_code_execution_tool_group") == null) { + toolkit.createToolGroup( + "skill_code_execution_tool_group", "Code execution tools for skills", true); + } + + // Create and register three tools + Set allowedCommands = Set.of("python", "python3", "node", "nodejs"); + String workDirStr = codeExecutionWorkDir != null ? codeExecutionWorkDir.toString() : null; + ShellCommandTool shellTool = new ShellCommandTool(workDirStr, allowedCommands, null); + ReadFileTool readTool = new ReadFileTool(workDirStr); + WriteFileTool writeTool = new WriteFileTool(workDirStr); + + toolkit.registration() + .agentTool(shellTool) + .group("skill_code_execution_tool_group") + .apply(); + toolkit.registration().tool(readTool).group("skill_code_execution_tool_group").apply(); + toolkit.registration().tool(writeTool).group("skill_code_execution_tool_group").apply(); + + logger.info( + "Code execution enabled with workDir: {}", + codeExecutionWorkDir != null ? codeExecutionWorkDir : "temporary directory"); + } + + /** + * Checks if code execution is enabled. + * + * @return true if code execution is enabled, false otherwise + */ + public boolean isCodeExecutionEnabled() { + return toolkit != null && toolkit.getToolGroup("skill_code_execution_tool_group") != null; + } + + /** + * Gets the working directory for code execution. + * + * @return The working directory path, or null if using temporary directory + */ + public Path getCodeExecutionWorkDir() { + return codeExecutionWorkDir; + } + + /** + * Ensures the working directory exists, creating it if necessary. + * + * @return The working directory path + * @throws RuntimeException if failed to create the directory + */ + private Path ensureWorkDirExists() { + Path workDir; + + if (codeExecutionWorkDir == null) { + // Create temporary directory + try { + workDir = Files.createTempDirectory("agentscope-code-execution-"); + + // Register shutdown hook to clean up temporary directory + Runtime.getRuntime() + .addShutdownHook( + new Thread( + () -> { + try { + deleteTempDirectory(workDir); + logger.info( + "Cleaned up temporary working directory:" + + " {}", + workDir); + } catch (IOException e) { + logger.warn( + "Failed to clean up temporary directory:" + + " {}", + e.getMessage()); + } + })); + + logger.info("Created temporary working directory: {}", workDir); + } catch (IOException e) { + throw new RuntimeException("Failed to create temporary working directory", e); + } + } else { + workDir = codeExecutionWorkDir; + // Create directory if it doesn't exist + if (!Files.exists(workDir)) { + try { + Files.createDirectories(workDir); + logger.info("Created working directory: {}", workDir); + } catch (IOException e) { + throw new RuntimeException("Failed to create working directory", e); + } + } + } + + return workDir; + } + + /** + * Deletes the temporary working directory if it was created. + * + *

    + * This method only deletes directories that were created as temporary + * directories + * by this SkillBox instance. User-specified directories are never deleted. + * + * @throws IOException if deletion fails + */ + private void deleteTempDirectory(Path temporaryWorkDir) throws IOException { + if (temporaryWorkDir != null && Files.exists(temporaryWorkDir)) { + Files.walk(temporaryWorkDir) + .sorted( + (a, b) -> + -a.compareTo( + b)) // Reverse order to delete files before directories + .forEach( + path -> { + try { + Files.delete(path); + } catch (IOException e) { + logger.warn("Failed to delete: {}", path); + } + }); + } + } + + /** + * Writes all skill scripts to the code execution working directory. + * + *

    This method iterates through all registered skills and writes their script + * resources to the working directory. Scripts are organized by skill ID: + *

      + *
    • Scripts are written to workDir/skillId/relativePath
      • + *
    • Scripts are identified by being in "scripts/" directory OR having script extension (.py, .js, .sh)
      • + *
    + * + *

    If a script file already exists, it will be overwritten. + * + * @throws IllegalStateException if code execution is not enabled + */ + public void writeSkillScriptsToWorkDir() { + if (!isCodeExecutionEnabled()) { + throw new IllegalStateException("Code execution is not enabled"); + } + + Path workDir = ensureWorkDirExists(); + int scriptCount = 0; + + for (String skillId : getAllSkillIds()) { + AgentSkill skill = getSkill(skillId); + Map scripts = skill.getScriptResources(); + + if (scripts.isEmpty()) { + continue; + } + + // Create skill-specific directory + Path skillDir = workDir.resolve(skillId); + + for (Map.Entry entry : scripts.entrySet()) { + String relativePath = entry.getKey(); + String content = entry.getValue(); + Path targetPath = skillDir.resolve(relativePath).normalize(); + + // Security check: Prevent path traversal attacks + if (!targetPath.startsWith(skillDir)) { + logger.warn( + "Skipping script with invalid path (path traversal attempt): {}", + relativePath); + continue; + } + + try { + // Create parent directories if they don't exist + if (targetPath.getParent() != null) { + Files.createDirectories(targetPath.getParent()); + } + Files.writeString(targetPath, content, StandardCharsets.UTF_8); + logger.debug("Wrote script: {}", targetPath); + scriptCount++; + } catch (IOException e) { + logger.error("Failed to write script {}: {}", relativePath, e.getMessage()); + } + } + } + logger.info("Wrote {} skill scripts to workDir: {}", scriptCount, workDir); + } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java index 46e0f305a..b3be297c9 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java @@ -24,6 +24,8 @@ import java.io.InputStream; import java.io.InputStreamReader; import java.nio.charset.StandardCharsets; +import java.nio.file.Path; +import java.nio.file.Paths; import java.time.Duration; import java.util.ArrayList; import java.util.Collections; @@ -91,13 +93,14 @@ public Thread newThread(Runnable r) { private final Set allowedCommands; private final Function approvalCallback; private final CommandValidator commandValidator; + private final Path baseDir; public ShellCommandTool() { - this(null, null); + this(null, null, null, createDefaultValidator()); } public ShellCommandTool(Set allowedCommands) { - this(allowedCommands, null); + this(null, allowedCommands, null, createDefaultValidator()); } /** @@ -108,7 +111,21 @@ public ShellCommandTool(Set allowedCommands) { */ public ShellCommandTool( Set allowedCommands, Function approvalCallback) { - this(allowedCommands, approvalCallback, createDefaultValidator()); + this(null, allowedCommands, approvalCallback, createDefaultValidator()); + } + + /** + * Constructor with base directory, command whitelist, and approval callback. + * + * @param baseDir Base directory for command execution (null to use current directory) + * @param allowedCommands Set of allowed command executables + * @param approvalCallback Callback function to request user approval + */ + public ShellCommandTool( + String baseDir, + Set allowedCommands, + Function approvalCallback) { + this(baseDir, allowedCommands, approvalCallback, createDefaultValidator()); } /** @@ -122,6 +139,22 @@ public ShellCommandTool( Set allowedCommands, Function approvalCallback, CommandValidator commandValidator) { + this(null, allowedCommands, approvalCallback, commandValidator); + } + + /** + * Constructor with base directory, command whitelist, approval callback, and custom validator. + * + * @param baseDir Base directory for command execution (null to use current directory) + * @param allowedCommands Set of allowed command executables (null to allow all commands) + * @param approvalCallback Callback function to request user approval + * @param commandValidator Custom command validator + */ + public ShellCommandTool( + String baseDir, + Set allowedCommands, + Function approvalCallback, + CommandValidator commandValidator) { // Use ConcurrentHashMap.newKeySet() for thread-safe, high-performance concurrent access // Create defensive copy to prevent external modifications if (allowedCommands != null && !allowedCommands.isEmpty()) { @@ -133,6 +166,11 @@ public ShellCommandTool( this.approvalCallback = approvalCallback; this.commandValidator = commandValidator != null ? commandValidator : createDefaultValidator(); + this.baseDir = baseDir != null ? Paths.get(baseDir).toAbsolutePath().normalize() : null; + + if (this.baseDir != null) { + logger.info("ShellCommandTool initialized with base directory: {}", this.baseDir); + } } /** @@ -224,6 +262,14 @@ public String getDescription() { StringBuilder desc = new StringBuilder(); desc.append("Execute a shell command with security validation and return the result."); + // Add base directory information if configured + if (baseDir != null) { + desc.append(" WORKING DIRECTORY: The command will be executed in the directory: "); + desc.append(baseDir.toString()); + desc.append( + ". All relative paths in the command will be resolved from this directory."); + } + // Add whitelist information if configured if (!allowedCommands.isEmpty()) { desc.append(" ALLOWED COMMANDS WHITELIST: ["); @@ -366,6 +412,12 @@ private ToolResultBlock executeCommand(String command, int timeoutSeconds) { processBuilder = new ProcessBuilder("sh", "-c", command); } + // Set working directory if baseDir is specified + if (baseDir != null) { + processBuilder.directory(baseDir.toFile()); + logger.debug("Setting working directory to: {}", baseDir); + } + Process process = null; Future stdoutFuture = null; Future stderrFuture = null; diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/AgentSkillTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/AgentSkillTest.java index 320d4e7c8..db17728f9 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/AgentSkillTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/AgentSkillTest.java @@ -242,4 +242,89 @@ void testEdgeCases() { AgentSkill skill4 = new AgentSkill("name", "desc", "content", manyResources); assertEquals(50, skill4.getResources().size()); } + + @Test + @DisplayName("Should get script resources from scripts folder") + void testGetScriptResourcesFromScriptsFolder() { + Map resources = new HashMap<>(); + resources.put("scripts/process.py", "print('hello')"); + resources.put("scripts/analyze.js", "console.log('test')"); + resources.put("scripts/data.txt", "not a script but in scripts folder"); + resources.put("config.json", "{\"key\": \"value\"}"); + + AgentSkill skill = new AgentSkill("test", "desc", "content", resources); + Map scripts = skill.getScriptResources(); + + assertEquals(3, scripts.size()); + assertTrue(scripts.containsKey("scripts/process.py")); + assertTrue(scripts.containsKey("scripts/analyze.js")); + assertTrue(scripts.containsKey("scripts/data.txt")); + assertTrue(!scripts.containsKey("config.json")); + } + + @Test + @DisplayName("Should get script resources by extension") + void testGetScriptResourcesByExtension() { + Map resources = new HashMap<>(); + resources.put("process.py", "python code"); + resources.put("analyze.js", "javascript code"); + resources.put("Main.java", "java code"); + resources.put("setup.sh", "shell script"); + resources.put("install.bash", "bash script"); + resources.put("script.rb", "ruby code"); + resources.put("util.pl", "perl code"); + resources.put("config.json", "not a script"); + resources.put("data.txt", "not a script"); + + AgentSkill skill = new AgentSkill("test", "desc", "content", resources); + Map scripts = skill.getScriptResources(); + + assertEquals(3, scripts.size()); + assertTrue(scripts.containsKey("process.py")); + assertTrue(scripts.containsKey("analyze.js")); + assertTrue(scripts.containsKey("setup.sh")); + } + + @Test + @DisplayName("Should get script resources mixed cases") + void testGetScriptResourcesMixedCases() { + Map resources = new HashMap<>(); + resources.put("scripts/process.py", "in scripts folder with script extension"); + resources.put("scripts/config.json", "in scripts folder but not script extension"); + resources.put("analyze.js", "not in scripts folder but has script extension"); + resources.put("data/file.txt", "not in scripts folder and no script extension"); + + AgentSkill skill = new AgentSkill("test", "desc", "content", resources); + Map scripts = skill.getScriptResources(); + + assertEquals(3, scripts.size()); + assertTrue(scripts.containsKey("scripts/process.py")); + assertTrue(scripts.containsKey("scripts/config.json")); + assertTrue(scripts.containsKey("analyze.js")); + assertTrue(!scripts.containsKey("data/file.txt")); + } + + @Test + @DisplayName("Should return empty map when no scripts") + void testGetScriptResourcesEmpty() { + Map resources = new HashMap<>(); + resources.put("config.json", "config"); + resources.put("data.txt", "data"); + + AgentSkill skill = new AgentSkill("test", "desc", "content", resources); + Map scripts = skill.getScriptResources(); + + assertNotNull(scripts); + assertTrue(scripts.isEmpty()); + } + + @Test + @DisplayName("Should return empty map when no resources") + void testGetScriptResourcesNoResources() { + AgentSkill skill = new AgentSkill("test", "desc", "content", null); + Map scripts = skill.getScriptResources(); + + assertNotNull(scripts); + assertTrue(scripts.isEmpty()); + } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java index b8354a54e..8de0d8665 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java @@ -15,6 +15,7 @@ */ package io.agentscope.core.skill; +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; @@ -34,19 +35,25 @@ import io.agentscope.core.tool.Toolkit; import io.agentscope.core.tool.mcp.McpClientWrapper; import io.modelcontextprotocol.spec.McpSchema; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.HashMap; import java.util.List; import java.util.Map; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; import reactor.core.publisher.Mono; /** * Unit tests for SkillBox. * - *

    These tests verify skill registration. + *

    + * These tests verify skill registration. */ @Tag("unit") class SkillBoxTest { @@ -61,182 +68,456 @@ void setUp() { toolkit.registerTool(skillBox); } - @Test - @DisplayName("Should get skill by id") - void testGetSkillById() { - AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); - skillBox.registerSkill(skill); + @Nested + @DisplayName("SkillBox Basic Skill Management Test") + class SkillBoxBasic { + @Test + @DisplayName("Should get skill by id") + void testGetSkillById() { + AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); + skillBox.registerSkill(skill); - AgentSkill retrieved = skillBox.getSkill(skill.getSkillId()); + AgentSkill retrieved = skillBox.getSkill(skill.getSkillId()); - assertNotNull(retrieved); - assertEquals("test_skill", retrieved.getName()); - assertEquals("Test Skill", retrieved.getDescription()); - } + assertNotNull(retrieved); + assertEquals("test_skill", retrieved.getName()); + assertEquals("Test Skill", retrieved.getDescription()); + } - @Test - @DisplayName("Should throw exception for null skill id") - void testThrowExceptionForNullSkillId() { - assertThrows(IllegalArgumentException.class, () -> skillBox.getSkill(null)); - } + @Test + @DisplayName("Should throw exception for null skill id") + void testThrowExceptionForNullSkillId() { + assertThrows(IllegalArgumentException.class, () -> skillBox.getSkill(null)); + } - @Test - @DisplayName("Should remove skill") - void testRemoveSkill() { - AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); - skillBox.registerSkill(skill); + @Test + @DisplayName("Should remove skill") + void testRemoveSkill() { + AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); + skillBox.registerSkill(skill); - assertTrue(skillBox.exists("test_skill_custom")); + assertTrue(skillBox.exists("test_skill_custom")); - skillBox.removeSkill("test_skill_custom"); + skillBox.removeSkill("test_skill_custom"); - assertFalse(skillBox.exists(skill.getSkillId())); - } + assertFalse(skillBox.exists(skill.getSkillId())); + } - @Test - @DisplayName("Should check skill exists") - void testCheckSkillExists() { - assertFalse(skillBox.exists("non_existent_skill")); + @Test + @DisplayName("Should check skill exists") + void testCheckSkillExists() { + assertFalse(skillBox.exists("non_existent_skill")); - AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); - skillBox.registerSkill(skill); + AgentSkill skill = new AgentSkill("test_skill", "Test Skill", "# Content", null); + skillBox.registerSkill(skill); - assertTrue(skillBox.exists(skill.getSkillId())); - } + assertTrue(skillBox.exists(skill.getSkillId())); + } - @Test - @DisplayName("Should register skill load tools") - void testRegisterSkillLoadTools() { - // After registerSkillAccessTools is called, the tool should be available - skillBox.registerSkillLoadTool(); - assertNotNull(toolkit.getTool("load_skill_through_path")); - } + @Test + @DisplayName("Should register skill load tools") + void testRegisterSkillLoadTools() { + // After registerSkillAccessTools is called, the tool should be available + skillBox.registerSkillLoadTool(); + assertNotNull(toolkit.getTool("load_skill_through_path")); + } - @Test - @DisplayName("Should create tool group when registering skill") - void testCreateToolGroupWhenRegisteringSkill() { - AgentSkill skill = new AgentSkill("my_skill", "My Skill", "# Content", null); - - // Before registration, the tool group should not exist - String toolsGroupName = skill.getSkillId() + "_skill_tools"; - assertNull( - toolkit.getToolGroup(toolsGroupName), - "Tool group should not exist before skill registration"); - - // Create a simple test tool - AgentTool testTool = createTestTool("test_tool"); - - // Register the skill with tool - skillBox.registration().agentTool(testTool).skill(skill).apply(); - - // After registration, the tool group should be created - assertNotNull( - toolkit.getToolGroup(toolsGroupName), - "Tool group should be created after skill registration"); - - // Verify the tool group properties - var toolGroup = toolkit.getToolGroup(toolsGroupName); - assertEquals(toolsGroupName, toolGroup.getName()); - } + @Test + @DisplayName("Should create tool group when registering skill") + void testCreateToolGroupWhenRegisteringSkill() { + AgentSkill skill = new AgentSkill("my_skill", "My Skill", "# Content", null); - @Test - @DisplayName("Should throw exception for null skill id in operations") - void testThrowExceptionForNullSkillIdInOperations() { - assertThrows(IllegalArgumentException.class, () -> skillBox.removeSkill(null)); - assertThrows(IllegalArgumentException.class, () -> skillBox.exists(null)); - } + // Before registration, the tool group should not exist + String toolsGroupName = skill.getSkillId() + "_skill_tools"; + assertNull( + toolkit.getToolGroup(toolsGroupName), + "Tool group should not exist before skill registration"); - @Test - @DisplayName("Should successfully register when only tool object is provided") - void testSuccessfullyRegisterWhenOnlyToolObjectProvided() { - TestToolObject toolObject = new TestToolObject(); - AgentSkill skill = - new AgentSkill( - "Tool Object Only Skill", - "Skill with only tool object", - "# Tool Object", - null); - - // Should not throw - only one registration type - skillBox.registration().skill(skill).tool(toolObject).apply(); - - assertTrue(skillBox.exists(skill.getSkillId())); - assertNotNull(toolkit.getTool("test_tool_method"), "Tool should be registered"); - } + // Create a simple test tool + AgentTool testTool = createTestTool("test_tool"); - @Test - @DisplayName("Should successfully register when only agent tool is provided") - void testSuccessfullyRegisterWhenOnlyAgentToolProvided() { - AgentTool agentTool = createTestTool("agent_tool_only"); - AgentSkill skill = - new AgentSkill( - "Agent Tool Only Skill", - "Skill with only agent tool", - "# Agent Tool", - null); - - // Should not throw - only one registration type - skillBox.registration().skill(skill).agentTool(agentTool).apply(); - - assertTrue(skillBox.exists(skill.getSkillId())); - assertNotNull(toolkit.getTool("agent_tool_only"), "Agent tool should be registered"); - } + // Register the skill with tool + skillBox.registration().agentTool(testTool).skill(skill).apply(); - @Test - @DisplayName("Should successfully register when only mcp client is provided") - void testSuccessfullyRegisterWhenOnlyMcpClientProvided() { - McpClientWrapper mcpClient = mock(McpClientWrapper.class); - McpSchema.Tool mockToolInfo = - new McpSchema.Tool( - "mcp_only_tool", - null, - "MCP only tool", - new McpSchema.JsonSchema("object", null, null, null, null, null), - null, - null, - null); - when(mcpClient.listTools()).thenReturn(Mono.just(List.of(mockToolInfo))); - when(mcpClient.isInitialized()).thenReturn(true); - when(mcpClient.initialize()).thenReturn(Mono.empty()); - when(mcpClient.getName()).thenReturn("mcp-only-client"); - - AgentSkill skill = - new AgentSkill("MCP Only Skill", "Skill with only MCP client", "# MCP Only", null); - - // Should not throw - only one registration type - skillBox.registration().skill(skill).mcpClient(mcpClient).apply(); - - assertTrue(skillBox.exists(skill.getSkillId())); - assertNotNull(toolkit.getTool("mcp_only_tool"), "MCP tool should be registered"); - } + // After registration, the tool group should be created + assertNotNull( + toolkit.getToolGroup(toolsGroupName), + "Tool group should be created after skill registration"); - @Test - @DisplayName("Should return empty set when no skills are registered") - void testGetAllSkillIdsWhenEmpty() { - var skillIds = skillBox.getAllSkillIds(); + // Verify the tool group properties + var toolGroup = toolkit.getToolGroup(toolsGroupName); + assertEquals(toolsGroupName, toolGroup.getName()); + } + + @Test + @DisplayName("Should throw exception for null skill id in operations") + void testThrowExceptionForNullSkillIdInOperations() { + assertThrows(IllegalArgumentException.class, () -> skillBox.removeSkill(null)); + assertThrows(IllegalArgumentException.class, () -> skillBox.exists(null)); + } - assertNotNull(skillIds, "Skill IDs set should not be null"); - assertTrue(skillIds.isEmpty(), "Skill IDs set should be empty when no skills registered"); + @Test + @DisplayName("Should successfully register when only tool object is provided") + void testSuccessfullyRegisterWhenOnlyToolObjectProvided() { + TestToolObject toolObject = new TestToolObject(); + AgentSkill skill = + new AgentSkill( + "Tool Object Only Skill", + "Skill with only tool object", + "# Tool Object", + null); + + // Should not throw - only one registration type + skillBox.registration().skill(skill).tool(toolObject).apply(); + + assertTrue(skillBox.exists(skill.getSkillId())); + assertNotNull(toolkit.getTool("test_tool_method"), "Tool should be registered"); + } + + @Test + @DisplayName("Should successfully register when only agent tool is provided") + void testSuccessfullyRegisterWhenOnlyAgentToolProvided() { + AgentTool agentTool = createTestTool("agent_tool_only"); + AgentSkill skill = + new AgentSkill( + "Agent Tool Only Skill", + "Skill with only agent tool", + "# Agent Tool", + null); + + // Should not throw - only one registration type + skillBox.registration().skill(skill).agentTool(agentTool).apply(); + + assertTrue(skillBox.exists(skill.getSkillId())); + assertNotNull(toolkit.getTool("agent_tool_only"), "Agent tool should be registered"); + } + + @Test + @DisplayName("Should successfully register when only mcp client is provided") + void testSuccessfullyRegisterWhenOnlyMcpClientProvided() { + McpClientWrapper mcpClient = mock(McpClientWrapper.class); + McpSchema.Tool mockToolInfo = + new McpSchema.Tool( + "mcp_only_tool", + null, + "MCP only tool", + new McpSchema.JsonSchema("object", null, null, null, null, null), + null, + null, + null); + when(mcpClient.listTools()).thenReturn(Mono.just(List.of(mockToolInfo))); + when(mcpClient.isInitialized()).thenReturn(true); + when(mcpClient.initialize()).thenReturn(Mono.empty()); + when(mcpClient.getName()).thenReturn("mcp-only-client"); + + AgentSkill skill = + new AgentSkill( + "MCP Only Skill", "Skill with only MCP client", "# MCP Only", null); + + // Should not throw - only one registration type + skillBox.registration().skill(skill).mcpClient(mcpClient).apply(); + + assertTrue(skillBox.exists(skill.getSkillId())); + assertNotNull(toolkit.getTool("mcp_only_tool"), "MCP tool should be registered"); + } + + @Test + @DisplayName("Should return empty set when no skills are registered") + void testGetAllSkillIdsWhenEmpty() { + var skillIds = skillBox.getAllSkillIds(); + + assertNotNull(skillIds, "Skill IDs set should not be null"); + assertTrue( + skillIds.isEmpty(), "Skill IDs set should be empty when no skills registered"); + } + + @Test + @DisplayName("Should return all skill IDs when multiple skills are registered") + void testGetAllSkillIdsWithMultipleSkills() { + AgentSkill skill1 = new AgentSkill("skill_one", "Skill One", "# Content 1", null); + AgentSkill skill2 = new AgentSkill("skill_two", "Skill Two", "# Content 2", null); + AgentSkill skill3 = new AgentSkill("skill_three", "Skill Three", "# Content 3", null); + + skillBox.registerSkill(skill1); + skillBox.registerSkill(skill2); + skillBox.registerSkill(skill3); + + var skillIds = skillBox.getAllSkillIds(); + + assertNotNull(skillIds, "Skill IDs set should not be null"); + assertEquals(3, skillIds.size(), "Should have exactly three skill IDs"); + assertTrue(skillIds.contains(skill1.getSkillId()), "Should contain first skill ID"); + assertTrue(skillIds.contains(skill2.getSkillId()), "Should contain second skill ID"); + assertTrue(skillIds.contains(skill3.getSkillId()), "Should contain third skill ID"); + } } - @Test - @DisplayName("Should return all skill IDs when multiple skills are registered") - void testGetAllSkillIdsWithMultipleSkills() { - AgentSkill skill1 = new AgentSkill("skill_one", "Skill One", "# Content 1", null); - AgentSkill skill2 = new AgentSkill("skill_two", "Skill Two", "# Content 2", null); - AgentSkill skill3 = new AgentSkill("skill_three", "Skill Three", "# Content 3", null); - - skillBox.registerSkill(skill1); - skillBox.registerSkill(skill2); - skillBox.registerSkill(skill3); - - var skillIds = skillBox.getAllSkillIds(); - - assertNotNull(skillIds, "Skill IDs set should not be null"); - assertEquals(3, skillIds.size(), "Should have exactly three skill IDs"); - assertTrue(skillIds.contains(skill1.getSkillId()), "Should contain first skill ID"); - assertTrue(skillIds.contains(skill2.getSkillId()), "Should contain second skill ID"); - assertTrue(skillIds.contains(skill3.getSkillId()), "Should contain third skill ID"); + @Nested + @DisplayName("SkillBox Code Execution Test") + class CodeExecutionTest { + @TempDir Path tempDir; + + @Test + @DisplayName("Should enable code execution with default temporary directory") + void testEnableCodeExecutionWithDefaultTempDir() { + skillBox.enableCodeExecution(); + + assertTrue(skillBox.isCodeExecutionEnabled()); + // workDir is null, meaning temporary directory will be created later + assertNull(skillBox.getCodeExecutionWorkDir()); + + // Verify tool group is created and activated + assertNotNull(toolkit.getToolGroup("skill_code_execution_tool_group")); + assertTrue(toolkit.getToolGroup("skill_code_execution_tool_group").isActive()); + } + + @Test + @DisplayName("Should enable code execution with custom working directory") + void testEnableCodeExecutionWithCustomWorkDir() { + String customDir = tempDir.resolve("custom-code-exec").toString(); + + skillBox.enableCodeExecution(customDir); + + assertTrue(skillBox.isCodeExecutionEnabled()); + assertEquals( + Path.of(customDir).toAbsolutePath().normalize(), + skillBox.getCodeExecutionWorkDir()); + // Directory should not be created until scripts are written + assertFalse(Files.exists(skillBox.getCodeExecutionWorkDir())); + } + + @Test + @DisplayName( + "Should enable code execution with existing directory and not create until write") + void testEnableCodeExecutionWithExistingDir() throws IOException { + String existingDir = tempDir.resolve("existing-dir").toString(); + Files.createDirectories(Path.of(existingDir)); + + skillBox.enableCodeExecution(existingDir); + + assertTrue(skillBox.isCodeExecutionEnabled()); + assertEquals( + Path.of(existingDir).toAbsolutePath().normalize(), + skillBox.getCodeExecutionWorkDir()); + // Directory exists but should be empty + assertTrue(Files.exists(skillBox.getCodeExecutionWorkDir())); + assertEquals(0, Files.list(skillBox.getCodeExecutionWorkDir()).count()); + } + + @Test + @DisplayName("Should throw exception when enabling code execution without toolkit") + void testEnableCodeExecutionWithoutToolkit() { + SkillBox skillBoxWithoutToolkit = new SkillBox(); + + IllegalStateException exception = + assertThrows( + IllegalStateException.class, + () -> skillBoxWithoutToolkit.enableCodeExecution(null)); + assertEquals( + "Must bind toolkit before enabling code execution", exception.getMessage()); + } + + @Test + @DisplayName("Should write skill scripts to working directory organized by skill ID") + void testWriteSkillScriptsToWorkDir() throws IOException { + String workDir = tempDir.resolve("scripts").toString(); + skillBox.enableCodeExecution(workDir); + + // Verify directory not created yet + assertFalse(Files.exists(Path.of(workDir))); + + // Create skills with scripts + Map resources1 = new HashMap<>(); + resources1.put("scripts/process.py", "print('hello from python')"); + resources1.put("scripts/analyze.js", "console.log('hello from js')"); + resources1.put("config.json", "{}"); // Not a script + + Map resources2 = new HashMap<>(); + resources2.put("main.py", "print('main script')"); + resources2.put("util.sh", "echo 'utility script'"); + + AgentSkill skill1 = new AgentSkill("skill1", "First skill", "content1", resources1); + AgentSkill skill2 = new AgentSkill("skill2", "Second skill", "content2", resources2); + + skillBox.registerSkill(skill1); + skillBox.registerSkill(skill2); + + // Write scripts - directory should be created now + skillBox.writeSkillScriptsToWorkDir(); + + // Verify directory created + Path workPath = Path.of(workDir); + assertTrue(Files.exists(workPath)); + + // Verify scripts are written to workDir/skillId/ + assertTrue(Files.exists(workPath.resolve("skill1_custom/scripts/process.py"))); + assertTrue(Files.exists(workPath.resolve("skill1_custom/scripts/analyze.js"))); + assertTrue(Files.exists(workPath.resolve("skill2_custom/main.py"))); + assertTrue(Files.exists(workPath.resolve("skill2_custom/util.sh"))); + assertFalse( + Files.exists(workPath.resolve("skill1_custom/config.json"))); // Not a script + + // Verify content + String pythonContent = + Files.readString(workPath.resolve("skill1_custom/scripts/process.py")); + assertEquals("print('hello from python')", pythonContent); + } + + @Test + @DisplayName("Should throw exception when writing scripts without enabling code execution") + void testWriteScriptsWithoutEnabling() { + AgentSkill skill = new AgentSkill("skill", "desc", "content", null); + skillBox.registerSkill(skill); + + IllegalStateException exception = + assertThrows( + IllegalStateException.class, + () -> skillBox.writeSkillScriptsToWorkDir()); + assertEquals("Code execution is not enabled", exception.getMessage()); + } + + @Test + @DisplayName("Should handle empty scripts gracefully and not create skill directory") + void testWriteEmptyScripts() throws IOException { + String workDir = tempDir.resolve("empty-scripts").toString(); + skillBox.enableCodeExecution(workDir); + + // Skill with no script resources + Map resources = new HashMap<>(); + resources.put("config.json", "{}"); + resources.put("data.txt", "data"); + + AgentSkill skill = new AgentSkill("skill", "desc", "content", resources); + skillBox.registerSkill(skill); + + // Should not throw exception + assertDoesNotThrow(() -> skillBox.writeSkillScriptsToWorkDir()); + + // Verify workDir is created but skill directory is not (no scripts) + Path workPath = Path.of(workDir); + assertTrue(Files.exists(workPath)); + // No skill directory should be created since there are no scripts + assertFalse(Files.exists(workPath.resolve("skill_custom"))); + } + + @Test + @DisplayName("Should overwrite existing scripts in skill directory") + void testOverwriteExistingScripts() throws IOException { + String workDir = tempDir.resolve("overwrite").toString(); + skillBox.enableCodeExecution(workDir); + + // Create initial script in skill directory + Path scriptPath = Path.of(workDir).resolve("skill_custom/test.py"); + Files.createDirectories(scriptPath.getParent()); + Files.writeString(scriptPath, "print('old content')"); + + // Register skill with same script name + Map resources = new HashMap<>(); + resources.put("test.py", "print('new content')"); + AgentSkill skill = new AgentSkill("skill", "desc", "content", resources); + skillBox.registerSkill(skill); + + skillBox.writeSkillScriptsToWorkDir(); + + // Verify content is overwritten + String content = Files.readString(scriptPath); + assertEquals("print('new content')", content); + } + + @Test + @DisplayName("Should create nested directories for scripts in skill directory") + void testNestedDirectories() throws IOException { + String workDir = tempDir.resolve("nested").toString(); + skillBox.enableCodeExecution(workDir); + + Map resources = new HashMap<>(); + resources.put("scripts/utils/helper.py", "def help(): pass"); + resources.put("scripts/data/loader.js", "function load() {}"); + + AgentSkill skill = new AgentSkill("skill", "desc", "content", resources); + skillBox.registerSkill(skill); + + skillBox.writeSkillScriptsToWorkDir(); + + Path workPath = Path.of(workDir); + assertTrue(Files.exists(workPath.resolve("skill_custom/scripts/utils/helper.py"))); + assertTrue(Files.exists(workPath.resolve("skill_custom/scripts/data/loader.js"))); + } + + @Test + @DisplayName("Should register three tools when code execution is enabled") + void testToolsRegistration() { + String workDir = tempDir.resolve("tools").toString(); + skillBox.enableCodeExecution(workDir); + + var toolGroup = toolkit.getToolGroup("skill_code_execution_tool_group"); + assertNotNull(toolGroup); + assertTrue(toolGroup.isActive()); + + // Verify tools are registered + var toolNames = toolkit.getToolNames(); + assertTrue(toolNames.contains("execute_shell_command")); + assertTrue(toolNames.contains("view_text_file")); + assertTrue(toolNames.contains("write_text_file")); + } + + @Test + @DisplayName("Should create temporary directory when workDir is null and verify it exists") + void testCreateTemporaryDirectory() throws IOException { + skillBox.enableCodeExecution(); // null workDir + + Map resources = new HashMap<>(); + resources.put("test.py", "print('test')"); + AgentSkill skill = new AgentSkill("skill", "desc", "content", resources); + skillBox.registerSkill(skill); + + // Write scripts - should create temporary directory + assertDoesNotThrow(() -> skillBox.writeSkillScriptsToWorkDir()); + + // Verify temporary directory was created and script exists + // We can't get the exact temp dir path, but we can verify the script was + // written + // by checking that no exception was thrown and the operation completed + assertTrue(skillBox.isCodeExecutionEnabled()); + } + + @Test + @DisplayName("Should prevent path traversal attacks") + void testPathTraversalPrevention() throws IOException { + String workDir = tempDir.resolve("secure").toString(); + skillBox.enableCodeExecution(workDir); + + // Create skill with malicious path traversal attempts + Map resources = new HashMap<>(); + resources.put("scripts/../../../test/pwd", "malicious content"); + resources.put("../../outside.py", "print('escaped')"); + resources.put("normal.py", "print('safe')"); + + AgentSkill skill = new AgentSkill("malicious", "desc", "content", resources); + skillBox.registerSkill(skill); + + // Write scripts - malicious paths should be skipped + skillBox.writeSkillScriptsToWorkDir(); + + Path workPath = Path.of(workDir); + // Verify malicious files were NOT created + assertFalse(Files.exists(workPath.resolve("scripts/../../../test/passwd"))); + assertFalse(Files.exists(workPath.resolve("../../outside.py"))); + // Verify safe file WAS created + assertTrue(Files.exists(workPath.resolve("malicious_custom/normal.py"))); + } + + @Test + @DisplayName("Should throw exception when enableCodeExecution called multiple times") + void testDuplicateEnableCodeExecution() { + skillBox.enableCodeExecution(); + + IllegalStateException exception = + assertThrows(IllegalStateException.class, () -> skillBox.enableCodeExecution()); + assertEquals( + "Code execution is already enabled. This method should only be called once.", + exception.getMessage()); + } } @Test @@ -328,7 +609,8 @@ public Mono callAsync(ToolCallParam param) { } /** - * Test tool class with @Tool annotated methods for testing tool object registration. + * Test tool class with @Tool annotated methods for testing tool object + * registration. */ private static class TestToolObject { From 015d72781f7ae067e8b77ce34b52422c64bb16df Mon Sep 17 00:00:00 2001 From: "fish[3]" <745866137@qq.com> Date: Thu, 22 Jan 2026 15:17:18 +0800 Subject: [PATCH 36/53] fix(agui): Fix duplicate TextMessageEnd emission (#562) (#586) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Background: Fix Duplicate AguiEvent.TextMessageEnd Issue ## Problem Description When using AGUI protocol to request a ReActAgent with SKILL and TOOL capabilities, the `AguiAgentAdapter` was emitting duplicate `AguiEvent.TextMessageEnd` events, causing incorrect event closure in the AGUI event stream. ## Root Cause The issue occurs in the `convertEvent` method of `AguiAgentAdapter` when processing `REASONING` events that contain both `TextBlock` and `ToolUseBlock` content blocks: 1. **First emission path**: When processing a `ToolUseBlock` ,checks if there's an active text message and attempts to end it before starting the tool call (lines 162-169). 2. **Second emission path**: When processing a `TextBlock` in the last event (`event.isLast() == true`), the code emits `TextMessageEnd` to close the text message (lines 152-158). 3. **The bug**: If a message contains both text content and tool usage, and the text block is processed as the last event, the `TextMessageEnd` is emitted. However, when the subsequent `ToolUseBlock` is processed, the code doesn't check if the message has already been ended, leading to a duplicate `TextMessageEnd` event. ## Impact - **Issue**: [#562](https://github.com/agentscope-ai/agentscope-java/issues/562) - AGUI方式下请求使用Skill的ReActAgent，返回的AguiEvent存在闭合错误 - **Version affected**: 1.0.8-SNAPSHOT - **Symptoms**: - Duplicate `TextMessageEnd` events in the AGUI event stream - Incorrect event closure state - Potential issues with AGUI clients expecting proper event sequencing ## Solution Added a guard check using `state.hasEndedMessage(messageId)` before emitting `TextMessageEnd` events. This ensures that: 1. The message end event is only emitted once per message 2. The state tracking correctly reflects whether a message has been closed 3. The event stream maintains proper sequencing and closure semantics ## Code Changes The fix adds a conditional check before emitting `TextMessageEnd`: ```java if (!state.hasEndedMessage(messageId)) { events.add( new AguiEvent.TextMessageEnd( state.threadId, state.runId, messageId)); state.endMessage(messageId); } ``` This prevents duplicate emissions while maintaining the existing logic for properly closing messages when tool calls are encountered. --- .../core/agui/adapter/AguiAgentAdapter.java | 10 +- .../agui/adapter/AguiAgentAdapterTest.java | 278 ++++++++++++++++++ 2 files changed, 284 insertions(+), 4 deletions(-) diff --git a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java index 175e120be..66a340593 100644 --- a/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java +++ b/agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java @@ -159,10 +159,12 @@ private List convertEvent(Event event, EventConversionState state) { state.threadId, state.runId, messageId, text)); } else { // End message if this is the last event - events.add( - new AguiEvent.TextMessageEnd( - state.threadId, state.runId, messageId)); - state.endMessage(messageId); + if (!state.hasEndedMessage(messageId)) { + events.add( + new AguiEvent.TextMessageEnd( + state.threadId, state.runId, messageId)); + state.endMessage(messageId); + } } } } else if (block instanceof ThinkingBlock thinkingBlock) { diff --git a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java index 21a62ac66..22b9a3de3 100644 --- a/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java +++ b/agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java @@ -510,6 +510,284 @@ void testReactiveStreamCompletion() { .verifyComplete(); } + @Test + void testTextMessageEndNotDuplicatedWhenLastEventAfterToolCall() { + // Test that when a text message is interrupted by a tool call and then the last event + // contains text blocks with the same message ID, only one TextMessageEnd is emitted + String msgId = "msg-text"; + Msg firstMsg = + Msg.builder() + .id(msgId) + .role(MsgRole.ASSISTANT) + .content(List.of(TextBlock.builder().text("first part").build())) + .build(); + + Msg toolCall1 = + Msg.builder() + .id("msg-tc") + .role(MsgRole.ASSISTANT) + .content( + ToolUseBlock.builder() + .id("tc-1") + .name("tool") + .input(Map.of()) + .build()) + .build(); + Msg lastMsg = + Msg.builder() + .id(msgId) + .role(MsgRole.ASSISTANT) + .content(List.of(TextBlock.builder().text("last part").build())) + .build(); + + Event firstEvent = new Event(EventType.REASONING, firstMsg, false); + Event toolCallEvent = new Event(EventType.REASONING, toolCall1, false); + Event lastEvent = new Event(EventType.REASONING, lastMsg, true); + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(firstEvent, toolCallEvent, lastEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + // Should have exactly one TextMessageEnd for the same message ID + long textEndCount = + events.stream() + .filter(e -> e instanceof AguiEvent.TextMessageEnd) + .filter( + e -> { + AguiEvent.TextMessageEnd end = (AguiEvent.TextMessageEnd) e; + return msgId.equals(end.messageId()); + }) + .count(); + assertEquals(1, textEndCount, "Should have exactly 1 TextMessageEnd per message ID"); + } + + @Test + void testTextMessageEndWithLastEventDirectly() { + // Test that when the last event contains text blocks and the message hasn't been ended, + // the TextMessageEnd is emitted through the new hasEndedMessage check + // This test specifically covers the new code path at lines 153-158 + String msgId = "msg-text"; + Msg textMsg = + Msg.builder() + .id(msgId) + .role(MsgRole.ASSISTANT) + .content(List.of(TextBlock.builder().text("Hello world").build())) + .build(); + + // Create a last event directly (isLast = true) without any prior events + Event lastEvent = new Event(EventType.REASONING, textMsg, true); + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(lastEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + // Verify that TextMessageEnd is emitted exactly once + long textEndCount = + events.stream() + .filter(e -> e instanceof AguiEvent.TextMessageEnd) + .filter( + e -> { + AguiEvent.TextMessageEnd end = (AguiEvent.TextMessageEnd) e; + return msgId.equals(end.messageId()); + }) + .count(); + assertEquals(1, textEndCount, "Should have exactly 1 TextMessageEnd"); + + // Verify the event sequence + assertInstanceOf(AguiEvent.RunStarted.class, events.get(0)); + assertInstanceOf(AguiEvent.TextMessageStart.class, events.get(1)); + assertInstanceOf(AguiEvent.TextMessageEnd.class, events.get(2)); + assertInstanceOf(AguiEvent.RunFinished.class, events.get(3)); + } + + @Test + void testExtractToolResultTextWithMultipleTextBlocks() { + // Test extractToolResultText with multiple TextBlocks (should add newlines) + Msg toolResultMsg = + Msg.builder() + .id("msg-tr1") + .role(MsgRole.TOOL) + .content( + ToolResultBlock.builder() + .id("tc-1") + .output( + List.of( + TextBlock.builder().text("Line 1").build(), + TextBlock.builder().text("Line 2").build(), + TextBlock.builder().text("Line 3").build())) + .build()) + .build(); + + Event toolResultEvent = new Event(EventType.TOOL_RESULT, toolResultMsg, true); + + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(toolResultEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + AguiEvent.ToolCallResult toolResult = + events.stream() + .filter(e -> e instanceof AguiEvent.ToolCallResult) + .map(e -> (AguiEvent.ToolCallResult) e) + .findFirst() + .orElse(null); + + assertNotNull(toolResult, "Should have ToolCallResult"); + // Should contain newlines between text blocks + assertTrue(toolResult.content().contains("\n"), "Should have newlines between text blocks"); + assertTrue(toolResult.content().contains("Line 1"), "Should contain Line 1"); + assertTrue(toolResult.content().contains("Line 2"), "Should contain Line 2"); + assertTrue(toolResult.content().contains("Line 3"), "Should contain Line 3"); + } + + @Test + void testExtractToolResultTextWithEmptyOutput() { + // Test extractToolResultText with empty output + Msg toolResultMsg = + Msg.builder() + .id("msg-tr1") + .role(MsgRole.TOOL) + .content(ToolResultBlock.builder().id("tc-1").output(List.of()).build()) + .build(); + + Event toolResultEvent = new Event(EventType.TOOL_RESULT, toolResultMsg, true); + + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(toolResultEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + AguiEvent.ToolCallResult toolResult = + events.stream() + .filter(e -> e instanceof AguiEvent.ToolCallResult) + .map(e -> (AguiEvent.ToolCallResult) e) + .findFirst() + .orElse(null); + + assertNotNull(toolResult, "Should have ToolCallResult"); + // When output is empty, result should be null + assertTrue(toolResult.content() == null || toolResult.content().isEmpty()); + } + + @Test + void testToolUseBlockWithNullId() { + // Test that when ToolUseBlock has null ID, a UUID is generated + Msg toolCallMsg = + Msg.builder() + .id("msg-tc1") + .role(MsgRole.ASSISTANT) + .content( + ToolUseBlock.builder() + .id(null) // null ID + .name("test_tool") + .input(Map.of("param", "value")) + .build()) + .build(); + + Event toolCallEvent = new Event(EventType.REASONING, toolCallMsg, false); + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(toolCallEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + AguiEvent.ToolCallStart toolStart = + events.stream() + .filter(e -> e instanceof AguiEvent.ToolCallStart) + .map(e -> (AguiEvent.ToolCallStart) e) + .findFirst() + .orElse(null); + + assertNotNull(toolStart, "Should have ToolCallStart"); + // Should have generated a UUID (non-null, non-empty string) + assertNotNull(toolStart.toolCallId(), "Tool call ID should not be null"); + assertTrue(!toolStart.toolCallId().isEmpty(), "Tool call ID should not be empty"); + } + + @Test + void testToolUseBlockWithNullOrEmptyContent() { + // Test that when ToolUseBlock has null or empty content, ToolCallArgs is not emitted + Msg toolCallMsg = + Msg.builder() + .id("msg-tc1") + .role(MsgRole.ASSISTANT) + .content( + ToolUseBlock.builder() + .id("tc-1") + .name("test_tool") + .input(Map.of("param", "value")) + .content(null) // null content + .build()) + .build(); + + Event toolCallEvent = new Event(EventType.REASONING, toolCallMsg, false); + when(mockAgent.stream(anyList(), any(StreamOptions.class))) + .thenReturn(Flux.just(toolCallEvent)); + + RunAgentInput input = + RunAgentInput.builder() + .threadId("thread-1") + .runId("run-1") + .messages(List.of(AguiMessage.userMessage("msg-1", "Test"))) + .build(); + + List events = adapter.run(input).collectList().block(); + + assertNotNull(events); + + // Should still have ToolCallStart + boolean hasToolStart = events.stream().anyMatch(e -> e instanceof AguiEvent.ToolCallStart); + assertTrue(hasToolStart, "Should have ToolCallStart"); + + // Should NOT have ToolCallArgs when content is null + boolean hasToolArgs = events.stream().anyMatch(e -> e instanceof AguiEvent.ToolCallArgs); + assertTrue(!hasToolArgs, "Should NOT have ToolCallArgs when content is null"); + } + @Test void testRunWithThinkingBlockDefaultDisabled() { // Test that reasoning is disabled by default From 397c98b58a3c61d9127d7c8e00cf08ac73c76a1c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:09:48 +0800 Subject: [PATCH 37/53] chore(deps): bump mcp-sdk.version from 0.17.0 to 0.17.2 (#634) Bumps `mcp-sdk.version` from 0.17.0 to 0.17.2. Updates `io.modelcontextprotocol.sdk:mcp` from 0.17.0 to 0.17.2

    Release notes

    Sourced from io.modelcontextprotocol.sdk:mcp's releases.

    v0.17.2

    This release:

    • Addresses mostly the testing infrastructure issues.
    • Fixes a client-side issue with servers that process client-initiated notifications with a 202 Accepted HTTP Header.

    Full Changelog: https://github.com/modelcontextprotocol/java-sdk/compare/v0.17.1...v0.17.2

    v0.17.1

    Bug fix release:

    Full Changelog: https://github.com/modelcontextprotocol/java-sdk/compare/v0.17.0...v0.17.1

    Commits
    • 8fa4110 Release version 0.17.2
    • fc53c50 Fix everything-server-based integration tests (#756)
    • 07b4d51 Upgrade to testcontainers 1.21.4 (#743)
    • 7836ae9 Next development version
    • dad7675 Release version 0.17.1
    • b26cb00 Expose resourcesUpdateConsumer() in sync client (#735)
    • 9d1a2a4 Fix fomratting
    • a4929c5 add 2025-11-25 version to ProtocolVersions (#733)
    • a2a81cd fix: Support form and url fields in Elicitation capability per 2025-11-25 spe...
    • 250e4e1 fix: Enable javadoc generation for modules with OSGi metadata (#705)
    • Additional commits viewable in compare view

    Updates `io.modelcontextprotocol.sdk:mcp-spring-webflux` from 0.17.1 to 0.17.2
    Release notes

    Sourced from io.modelcontextprotocol.sdk:mcp-spring-webflux's releases.

    v0.17.2

    This release:

    • Addresses mostly the testing infrastructure issues.
    • Fixes a client-side issue with servers that process client-initiated notifications with a 202 Accepted HTTP Header.

    Full Changelog: https://github.com/modelcontextprotocol/java-sdk/compare/v0.17.1...v0.17.2

    Commits

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-examples/boba-tea-shop/business-mcp-server/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-examples/boba-tea-shop/business-mcp-server/pom.xml b/agentscope-examples/boba-tea-shop/business-mcp-server/pom.xml index d53e9e603..85eb72c58 100644 --- a/agentscope-examples/boba-tea-shop/business-mcp-server/pom.xml +++ b/agentscope-examples/boba-tea-shop/business-mcp-server/pom.xml @@ -32,7 +32,7 @@ Business MCP Server Module - 0.17.1 + 0.17.2 From b1eb9a0f8f33945b20995ffba0f052ca3cbdded6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:10:08 +0800 Subject: [PATCH 38/53] chore(deps): bump com.aliyun:bailian20231229 from 2.7.2 to 2.8.0 (#635) Bumps [com.aliyun:bailian20231229](https://github.com/aliyun/alibabacloud-java-sdk) from 2.7.2 to 2.8.0.
    Commits

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.aliyun:bailian20231229&package-manager=maven&previous-version=2.7.2&new-version=2.8.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-dependencies-bom/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml index 806576aa9..fa1379aeb 100644 --- a/agentscope-dependencies-bom/pom.xml +++ b/agentscope-dependencies-bom/pom.xml @@ -76,7 +76,7 @@ 33.5.0-jre 1.35.0 2.22.6 - 2.7.2 + 2.8.0 4.15.0 2.11.1 0.17.0 From fe7677b95ab6b3ebaad8edce08595e2766a5b39b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:10:25 +0800 Subject: [PATCH 39/53] chore(deps): bump org.springframework.boot:spring-boot-dependencies from 4.0.1 to 4.0.2 (#636) Bumps [org.springframework.boot:spring-boot-dependencies](https://github.com/spring-projects/spring-boot) from 4.0.1 to 4.0.2.
    Release notes

    Sourced from org.springframework.boot:spring-boot-dependencies's releases.

    v4.0.2

    :warning: Noteworthy Changes

    • The dependency on org.eclipse.jetty.ee11:jetty-ee11-servlets has been removed from spring-boot-jetty as it was unnecessary and unused. If your application code depends on a class from jetty-ee11-servlets, declare a dependency on it in your build configuration. #48677

    :lady_beetle: Bug Fixes

    • No TransactionAutoConfiguration with spring-boot-starter-kafka for Spring Boot 4 #48880
    • Evaluation of bean conditions unnecessarily queries the bean factory for types that are not present #48840
    • When a bean condition references a type that is not present, it appears as ? in the condition evaluation report #48838
    • SessionAutoConfiguration creates a DefaultCookieSerializer with a default SameSite of null instead of Lax #48830
    • Setting graphql schema location to "classpath*:graphql/**/" causes failure due to incorrectly packaged test resource #48829
    • Message interpolation by MVC and WebFlux's Validators does not work correctly in a native image #48828
    • CloudFoundry integration fails in Servlet-based web app without a dependency on spring-boot-starter-restclient #48826
    • RestTestClientAutoConfiguration and TestRestTemplateAutoConfiguration should be package-private #48820
    • SSL metrics are no longer auto-configured #48819
    • Actuator /info endpoint fails in Java 25 Native Image (VirtualThreadSchedulerMXBean support) #48812
    • DataSourceBuilder cannot create oracle.ucp.jdbc.PoolDataSourceImpl in a native image #48703
    • The spring-boot-cloudfoundry module should only have an optional dependency on spring-boot-security #48685
    • Application JAR created by extract command is not reproductible #48678
    • AOT processing of tests should not be disabled when 'skipTests' is set #48662
    • @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) is no longer applied to the management server #48653
    • Fix zero-length byte buffer in InspectedContent #48650
    • Can no longer override JacksonJsonHttpMessageConverter with ServerHttpMessageConvertersCustomizer #48635
    • HttpServiceClientProperties incorrectly uses the @ConfigurationProperties annotation on a LinkedHashMap class #48616
    • spring-boot-micrometer-tracing-opentelemetry fails if spring-boot-opentelemetry isn't there #48585
    • App fails to start with starter-webmvc and starter-zipkin #48581
    • Micrometer test modules should have an api dependency on micrometer-observation-test #48386

    :notebook_with_decorative_cover: Documentation

    • Fix typo in REST client documentation #48907
    • Remove duplicate word #48874
    • Document support for configuring arguments passed to Docker Compose #48806
    • The documentation related to EnvironmentPostProcessor links to deprecated interface #48803
    • Update documentation for Buildpack's AOT Cache support #48769
    • Correct docs to use new location for error handling configuration properties #48767
    • Document spring-boot-starter-cloudfoundry on Cloud Foundry Support Page #48675
    • Clarify javadoc to make it clear that HazelcastConfigCustomizer beans are only applied if Hazelcast is configured via a config file #48659
    • Example using excludeDevtools property should document that optional dependencies should be enabled #48641
    • Fix grammar and typos in the reference guide #48601
    • Update Tracing section for Spring Boot 4's modularity #48576

    :hammer: Dependency Upgrades

    • Upgrade to Classmate 1.7.3 #48783
    • Upgrade to Elasticsearch Client 9.2.3 #48721
    • Upgrade to Hibernate 7.2.1.Final #48857
    • Upgrade to HttpClient5 5.5.2 #48784
    • Upgrade to Jackson 2 Bom 2.20.2 #48910

    ... (truncated)

    Commits
    • fae3545 Release v4.0.2
    • 9fde744 Merge branch '3.5.x' into 4.0.x
    • 650236d Remove breaking and unnecessary Undertow TLS with RSA test
    • 547bc77 Upgrade to Spring Batch 6.0.2
    • 4387cbb Upgrade to Jackson Bom 3.0.4
    • abec26e Polish
    • f677fba Upgrade to Spring Integration 7.0.2
    • 849c2ee Upgrade to Spring GraphQL 2.0.2
    • facd456 Upgrade to Nullability Plugin 0.0.10
    • e99c08f Merge branch '3.5.x' into 4.0.x
    • Additional commits viewable in compare view

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=org.springframework.boot:spring-boot-dependencies&package-manager=maven&previous-version=4.0.1&new-version=4.0.2)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-examples/boba-tea-shop/pom.xml | 2 +- agentscope-extensions/agentscope-spring-boot-starters/pom.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/agentscope-examples/boba-tea-shop/pom.xml b/agentscope-examples/boba-tea-shop/pom.xml index 73b6e5dcd..00ecbfcf4 100644 --- a/agentscope-examples/boba-tea-shop/pom.xml +++ b/agentscope-examples/boba-tea-shop/pom.xml @@ -46,7 +46,7 @@ UTF-8 - 4.0.1 + 4.0.2 ${revision} diff --git a/agentscope-extensions/agentscope-spring-boot-starters/pom.xml b/agentscope-extensions/agentscope-spring-boot-starters/pom.xml index a40cb031d..de8171647 100644 --- a/agentscope-extensions/agentscope-spring-boot-starters/pom.xml +++ b/agentscope-extensions/agentscope-spring-boot-starters/pom.xml @@ -32,7 +32,7 @@ UTF-8 - 4.0.1 + 4.0.2 false From c01796a162d696378d52a7b03e8408203041b148 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:10:40 +0800 Subject: [PATCH 40/53] chore(deps): bump org.springframework.boot:spring-boot-autoconfigure from 4.0.1 to 4.0.2 (#637) Bumps [org.springframework.boot:spring-boot-autoconfigure](https://github.com/spring-projects/spring-boot) from 4.0.1 to 4.0.2.
    Release notes

    Sourced from org.springframework.boot:spring-boot-autoconfigure's releases.

    v4.0.2

    :warning: Noteworthy Changes

    • The dependency on org.eclipse.jetty.ee11:jetty-ee11-servlets has been removed from spring-boot-jetty as it was unnecessary and unused. If your application code depends on a class from jetty-ee11-servlets, declare a dependency on it in your build configuration. #48677

    :lady_beetle: Bug Fixes

    • No TransactionAutoConfiguration with spring-boot-starter-kafka for Spring Boot 4 #48880
    • Evaluation of bean conditions unnecessarily queries the bean factory for types that are not present #48840
    • When a bean condition references a type that is not present, it appears as ? in the condition evaluation report #48838
    • SessionAutoConfiguration creates a DefaultCookieSerializer with a default SameSite of null instead of Lax #48830
    • Setting graphql schema location to "classpath*:graphql/**/" causes failure due to incorrectly packaged test resource #48829
    • Message interpolation by MVC and WebFlux's Validators does not work correctly in a native image #48828
    • CloudFoundry integration fails in Servlet-based web app without a dependency on spring-boot-starter-restclient #48826
    • RestTestClientAutoConfiguration and TestRestTemplateAutoConfiguration should be package-private #48820
    • SSL metrics are no longer auto-configured #48819
    • Actuator /info endpoint fails in Java 25 Native Image (VirtualThreadSchedulerMXBean support) #48812
    • DataSourceBuilder cannot create oracle.ucp.jdbc.PoolDataSourceImpl in a native image #48703
    • The spring-boot-cloudfoundry module should only have an optional dependency on spring-boot-security #48685
    • Application JAR created by extract command is not reproductible #48678
    • AOT processing of tests should not be disabled when 'skipTests' is set #48662
    • @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) is no longer applied to the management server #48653
    • Fix zero-length byte buffer in InspectedContent #48650
    • Can no longer override JacksonJsonHttpMessageConverter with ServerHttpMessageConvertersCustomizer #48635
    • HttpServiceClientProperties incorrectly uses the @ConfigurationProperties annotation on a LinkedHashMap class #48616
    • spring-boot-micrometer-tracing-opentelemetry fails if spring-boot-opentelemetry isn't there #48585
    • App fails to start with starter-webmvc and starter-zipkin #48581
    • Micrometer test modules should have an api dependency on micrometer-observation-test #48386

    :notebook_with_decorative_cover: Documentation

    • Fix typo in REST client documentation #48907
    • Remove duplicate word #48874
    • Document support for configuring arguments passed to Docker Compose #48806
    • The documentation related to EnvironmentPostProcessor links to deprecated interface #48803
    • Update documentation for Buildpack's AOT Cache support #48769
    • Correct docs to use new location for error handling configuration properties #48767
    • Document spring-boot-starter-cloudfoundry on Cloud Foundry Support Page #48675
    • Clarify javadoc to make it clear that HazelcastConfigCustomizer beans are only applied if Hazelcast is configured via a config file #48659
    • Example using excludeDevtools property should document that optional dependencies should be enabled #48641
    • Fix grammar and typos in the reference guide #48601
    • Update Tracing section for Spring Boot 4's modularity #48576

    :hammer: Dependency Upgrades

    • Upgrade to Classmate 1.7.3 #48783
    • Upgrade to Elasticsearch Client 9.2.3 #48721
    • Upgrade to Hibernate 7.2.1.Final #48857
    • Upgrade to HttpClient5 5.5.2 #48784
    • Upgrade to Jackson 2 Bom 2.20.2 #48910

    ... (truncated)

    Commits
    • fae3545 Release v4.0.2
    • 9fde744 Merge branch '3.5.x' into 4.0.x
    • 650236d Remove breaking and unnecessary Undertow TLS with RSA test
    • 547bc77 Upgrade to Spring Batch 6.0.2
    • 4387cbb Upgrade to Jackson Bom 3.0.4
    • abec26e Polish
    • f677fba Upgrade to Spring Integration 7.0.2
    • 849c2ee Upgrade to Spring GraphQL 2.0.2
    • facd456 Upgrade to Nullability Plugin 0.0.10
    • e99c08f Merge branch '3.5.x' into 4.0.x
    • Additional commits viewable in compare view

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=org.springframework.boot:spring-boot-autoconfigure&package-manager=maven&previous-version=4.0.1&new-version=4.0.2)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-dependencies-bom/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml index fa1379aeb..bca06ea3e 100644 --- a/agentscope-dependencies-bom/pom.xml +++ b/agentscope-dependencies-bom/pom.xml @@ -101,7 +101,7 @@ 3.3.2 2.5.2 7.0.3 - 4.0.1 + 4.0.2 3.1.1 3.0.0 4.38.0 From 7386592e29419fc04ac46adfd117f315a6cbfed1 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:11:39 +0800 Subject: [PATCH 41/53] chore(deps-dev): bump com.google.genai:google-genai from 1.35.0 to 1.36.0 (#638) Bumps [com.google.genai:google-genai](https://github.com/googleapis/java-genai) from 1.35.0 to 1.36.0.
    Release notes

    Sourced from com.google.genai:google-genai's releases.

    v1.36.0

    1.36.0 (2026-01-22)

    Features

    • Add ModelArmorConfig support for prompt and response sanitization via the Model Armor service (9c77a8f)
    Changelog

    Sourced from com.google.genai:google-genai's changelog.

    1.36.0 (2026-01-22)

    Features

    • Add ModelArmorConfig support for prompt and response sanitization via the Model Armor service (9c77a8f)
    Commits
    • 500b895 chore(main): release 1.36.0 (#780)
    • 2502e78 chore: Update native-image configuration.
    • fb1f53d feat: Update data types from discovery doc.
    • 6444fb0 feat: Update data types from discovery doc.
    • 9c77a8f feat: Add ModelArmorConfig support for prompt and response sanitization via t...
    • a1dd99f Copybara import of the project:
    • 319ab24 Copybara import of the project:
    • 5a12d32 chore(main): release 1.36.0-SNAPSHOT (#779)
    • See full diff in compare view

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.google.genai:google-genai&package-manager=maven&previous-version=1.35.0&new-version=1.36.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-dependencies-bom/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml index bca06ea3e..50329ca4d 100644 --- a/agentscope-dependencies-bom/pom.xml +++ b/agentscope-dependencies-bom/pom.xml @@ -74,7 +74,7 @@ 5.21.0 6.0.2 33.5.0-jre - 1.35.0 + 1.36.0 2.22.6 2.8.0 4.15.0 From dfe2ff4956dc6ffdab279cd0979128528a463eea Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:12:04 +0800 Subject: [PATCH 42/53] chore(deps-dev): bump com.openai:openai-java from 4.15.0 to 4.16.0 (#639) Bumps [com.openai:openai-java](https://github.com/openai/openai-java) from 4.15.0 to 4.16.0.
    Release notes

    Sourced from com.openai:openai-java's releases.

    v4.16.0

    4.16.0 (2026-01-21)

    Full Changelog: v4.15.0...v4.16.0

    Features

    • api: api update (e5203e2)
    • client: send X-Stainless-Kotlin-Version header (d77a171)

    Bug Fixes

    • client: disallow coercion from float to int (4332495)
    • client: fully respect max retries (b2ac5ce)
    • client: send retry count header for max retries 0 (b2ac5ce)
    • date time deserialization leniency (35a4662)
    • make ResponseAccumulator forwards compatible with new event types (d9dc902)

    Chores

    • ci: upgrade actions/setup-java (d739c6a)
    • internal: clean up maven repo artifact script and add html documentation to repo root (763df3f)
    • internal: depend on packages directly in example (b2ac5ce)
    • internal: improve maven repo docs (005acfc)
    • internal: support uploading Maven repo artifacts to stainless package server (24dd88f)
    • internal: update actions/checkout version (64b074f)
    • internal: update maven repo doc to include authentication (c00b703)
    • test on Jackson 2.14.0 to avoid encountering FasterXML/jackson-databind#3240 in tests (35a4662)
    Changelog

    Sourced from com.openai:openai-java's changelog.

    4.16.0 (2026-01-21)

    Full Changelog: v4.15.0...v4.16.0

    Features

    • api: api update (e5203e2)
    • client: send X-Stainless-Kotlin-Version header (d77a171)

    Bug Fixes

    • client: disallow coercion from float to int (4332495)
    • client: fully respect max retries (b2ac5ce)
    • client: send retry count header for max retries 0 (b2ac5ce)
    • date time deserialization leniency (35a4662)
    • make ResponseAccumulator forwards compatible with new event types (d9dc902)

    Chores

    • ci: upgrade actions/setup-java (d739c6a)
    • internal: clean up maven repo artifact script and add html documentation to repo root (763df3f)
    • internal: depend on packages directly in example (b2ac5ce)
    • internal: improve maven repo docs (005acfc)
    • internal: support uploading Maven repo artifacts to stainless package server (24dd88f)
    • internal: update actions/checkout version (64b074f)
    • internal: update maven repo doc to include authentication (c00b703)
    • test on Jackson 2.14.0 to avoid encountering FasterXML/jackson-databind#3240 in tests (35a4662)
    Commits

    [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=com.openai:openai-java&package-manager=maven&previous-version=4.15.0&new-version=4.16.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
    Dependabot commands and options
    You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- agentscope-dependencies-bom/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-dependencies-bom/pom.xml b/agentscope-dependencies-bom/pom.xml index 50329ca4d..24baba859 100644 --- a/agentscope-dependencies-bom/pom.xml +++ b/agentscope-dependencies-bom/pom.xml @@ -77,7 +77,7 @@ 1.36.0 2.22.6 2.8.0 - 4.15.0 + 4.16.0 2.11.1 0.17.0 2.0.17 From b9fe56f3a63cb49d6b5df70cad73adc607f6d4ee Mon Sep 17 00:00:00 2001 From: xiaojing Date: Fri, 23 Jan 2026 10:13:29 +0800 Subject: [PATCH 43/53] feat: add Qwen tts model support. (#541) ## AgentScope-Java Version 1.0.7-SNAPSHOT ## Description Add Qwen TTS model support. AgentScope provides three ways to use TTS: 1. **TTSHook** - Auto-speak all Agent responses (non-invasive, speak while generating) 2. **TTSModel** - Standalone speech synthesis (independent of Agent, flexible calling) 3. **DashScopeMultiModalTool** - Agent invokes TTS as tool actively (Agent converts text to speech when needed) ## 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 --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../java/io/agentscope/core/hook/TTSHook.java | 456 ++++++++ .../core/model/tts/AudioPlayer.java | 326 ++++++ .../model/tts/DashScopeRealtimeTTSModel.java | 972 ++++++++++++++++++ .../core/model/tts/DashScopeTTSModel.java | 490 +++++++++ .../core/model/tts/DashScopeTTSRequest.java | 280 +++++ .../core/model/tts/DashScopeTTSResponse.java | 121 +++ .../core/model/tts/RealtimeTTSModel.java | 132 +++ .../model/tts/RealtimeTTSResponseEvent.java | 360 +++++++ .../core/model/tts/SessionConfig.java | 127 +++ .../agentscope/core/model/tts/TTSEvent.java | 126 +++ .../core/model/tts/TTSException.java | 114 ++ .../agentscope/core/model/tts/TTSModel.java | 56 + .../agentscope/core/model/tts/TTSOptions.java | 202 ++++ .../core/model/tts/TTSResponse.java | 249 +++++ .../multimodal/DashScopeMultiModalTool.java | 231 ++++- .../io/agentscope/core/hook/TTSHookTest.java | 484 +++++++++ .../core/model/tts/AudioPlayerTest.java | 401 ++++++++ .../tts/DashScopeRealtimeTTSModelTest.java | 910 ++++++++++++++++ .../core/model/tts/DashScopeTTSModelTest.java | 433 ++++++++ .../model/tts/DashScopeTTSRequestTest.java | 307 ++++++ .../model/tts/DashScopeTTSResponseTest.java | 176 ++++ .../tts/RealtimeTTSResponseEventTest.java | 310 ++++++ .../core/model/tts/SessionConfigTest.java | 158 +++ .../core/model/tts/TTSEventTest.java | 272 +++++ .../core/model/tts/TTSExceptionTest.java | 78 ++ .../core/model/tts/TTSOptionsTest.java | 90 ++ .../core/model/tts/TTSResponseTest.java | 182 ++++ .../DashScopeMultiModalToolE2ETest.java | 3 +- .../DashScopeMultiModalToolTest.java | 183 +++- .../tool/multimodal/DashScopeTTSE2ETest.java | 55 + agentscope-examples/chat-tts/pom.xml | 83 ++ .../examples/chattts/ChatController.java | 215 ++++ .../chattts/ChatTTSSpringBootApplication.java | 42 + .../chattts/ReActAgentWithTTSDemo.java | 92 ++ .../src/main/resources/application.yml | 24 + .../chat-tts/src/main/resources/logback.xml | 31 + .../src/main/resources/static/index.html | 945 +++++++++++++++++ agentscope-examples/pom.xml | 1 + agentscope-examples/quickstart/pom.xml | 6 + .../examples/quickstart/TTSExample.java | 467 +++++++++ docs/en/task/tts.md | 203 ++++ docs/zh/task/tts.md | 205 ++++ 42 files changed, 10580 insertions(+), 18 deletions(-) create mode 100644 agentscope-core/src/main/java/io/agentscope/core/hook/TTSHook.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/AudioPlayer.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModel.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSModel.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSRequest.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSResponse.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSModel.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSResponseEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/SessionConfig.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSEvent.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSException.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSModel.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSOptions.java create mode 100644 agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSResponse.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/hook/TTSHookTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/AudioPlayerTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModelTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSModelTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSRequestTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSResponseTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/RealtimeTTSResponseEventTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/SessionConfigTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSEventTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSExceptionTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSOptionsTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSResponseTest.java create mode 100644 agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeTTSE2ETest.java create mode 100644 agentscope-examples/chat-tts/pom.xml create mode 100644 agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatController.java create mode 100644 agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatTTSSpringBootApplication.java create mode 100644 agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ReActAgentWithTTSDemo.java create mode 100644 agentscope-examples/chat-tts/src/main/resources/application.yml create mode 100644 agentscope-examples/chat-tts/src/main/resources/logback.xml create mode 100644 agentscope-examples/chat-tts/src/main/resources/static/index.html create mode 100644 agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/TTSExample.java create mode 100644 docs/en/task/tts.md create mode 100644 docs/zh/task/tts.md diff --git a/agentscope-core/src/main/java/io/agentscope/core/hook/TTSHook.java b/agentscope-core/src/main/java/io/agentscope/core/hook/TTSHook.java new file mode 100644 index 000000000..fbc515a07 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/hook/TTSHook.java @@ -0,0 +1,456 @@ +/* + * 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 + * + * https://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.hook; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Msg; +import io.agentscope.core.model.tts.AudioPlayer; +import io.agentscope.core.model.tts.DashScopeRealtimeTTSModel; +import java.util.function.Consumer; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import reactor.core.publisher.Mono; +import reactor.core.publisher.Sinks; +import reactor.core.scheduler.Schedulers; + +/** + * Hook for real-time Text-to-Speech synthesis during agent execution. + * + *

    This hook implements "speak as you generate" by listening to streaming + * reasoning events and synthesizing speech in real-time. + * + *

    Two Usage Modes: + *

      + *
    • Local Playback (CLI/Desktop): Use audioPlayer for direct playback
      • + *
    • Server Mode (Web/SSE): Use audioCallback to return audio to frontend
      • + *
    + * + *

    Example 1: Local Playback (CLI/Testing) + * 

    {@code
+ * AudioPlayer player = AudioPlayer.builder().sampleRate(24000).build();
+ *
+ * TTSHook ttsHook = TTSHook.builder()
+ *     .ttsModel(ttsModel)
+ *     .audioPlayer(player)  // Local playback
+ *     .build();
+ * }
    + * + *

    Example 2: Server Mode (Return to Frontend via SSE) + * 

    {@code
+ * TTSHook ttsHook = TTSHook.builder()
+ *     .ttsModel(ttsModel)
+ *     .audioCallback(audio -> {
+ *         // Send via SSE/WebSocket to frontend
+ *         sseEmitter.send(audio);
+ *     })
+ *     .build();
+ * }
    + * + *

    Example 3: Get Audio Stream (Reactive) + * 

    {@code
+ * TTSHook ttsHook = TTSHook.builder()
+ *     .ttsModel(ttsModel)
+ *     .build();
+ *
+ * // Subscribe to audio stream
+ * ttsHook.getAudioStream()
+ *     .subscribe(audio -> sendToClient(audio));
+ * }
    + */ +public class TTSHook implements Hook { + + private static final Logger log = LoggerFactory.getLogger(TTSHook.class); + + private final DashScopeRealtimeTTSModel ttsModel; + private final AudioPlayer audioPlayer; + private final boolean autoStartPlayer; + private final boolean realtimeMode; + private final Consumer audioCallback; + + // Reactive audio stream for external consumers (e.g., SSE/WebSocket to frontend) + // This sink is NOT interrupted when new reasoning starts - frontend controls playback + private final Sinks.Many audioSink = + Sinks.many().multicast().onBackpressureBuffer(); + + private boolean playerStarted = false; + private boolean sessionStarted = false; + + private TTSHook(Builder builder) { + this.ttsModel = builder.ttsModel; + this.audioPlayer = builder.audioPlayer; + this.autoStartPlayer = builder.autoStartPlayer; + this.realtimeMode = builder.realtimeMode; + this.audioCallback = builder.audioCallback; + } + + /** + * Gets the reactive audio stream. + * + *

    Use this to subscribe to audio blocks as they are generated. + * This is useful for SSE/WebSocket streaming to frontend. + * + *

    Example: + * 

    {@code
+     * ttsHook.getAudioStream()
+     *     .map(audio -> ((Base64Source) audio.getSource()).getData())
+     *     .subscribe(base64 -> sseEmitter.send(base64));
+     * }
    + * + * @return Flux of AudioBlock that emits audio as it's synthesized + */ + public reactor.core.publisher.Flux getAudioStream() { + return audioSink.asFlux(); + } + + @Override + public Mono onEvent(T event) { + if (realtimeMode) { + return handleRealtimeMode(event); + } else { + return handleBatchMode(event); + } + } + + /** + * Handle real-time mode: synthesize on each chunk. + */ + private Mono handleRealtimeMode(T event) { + if (event instanceof PreReasoningEvent) { + // New reasoning is starting - interrupt current playback if any + interruptCurrentPlayback(); + } else if (event instanceof ReasoningChunkEvent) { + ReasoningChunkEvent e = (ReasoningChunkEvent) event; + Msg incrementalChunk = e.getIncrementalChunk(); + + if (incrementalChunk != null) { + String text = incrementalChunk.getTextContent(); + if (text != null && !text.isEmpty()) { + if (!sessionStarted) { + // New session starting - interrupt any ongoing playback first + if (audioPlayer != null && playerStarted) { + audioPlayer.interrupt(); + } + + ttsModel.startSession(); + sessionStarted = true; + ensurePlayerStarted(); + + // Subscribe to audio stream ONCE at session start + // Audio arrives asynchronously via WebSocket callback + ttsModel.getAudioStream().doOnNext(this::emitAudio).subscribe(); + } + + // Push text - audio delivered via getAudioStream subscription + ttsModel.push(text); + } + } + } else if (event instanceof PostReasoningEvent) { + if (sessionStarted) { + // finish() commits pending text and closes session + // Audio continues to arrive via getAudioStream subscription + ttsModel.finish().doOnComplete(this::drainPlayerAsync).blockLast(); + sessionStarted = false; + } + } + + return Mono.just(event); + } + + /** + * Handle batch mode: wait for complete response then synthesize. + */ + private Mono handleBatchMode(T event) { + if (event instanceof PreReasoningEvent) { + // New reasoning is starting - interrupt current playback if any + // (In batch mode, this handles cases where audio is still playing from previous + // response) + if (audioPlayer != null && playerStarted) { + audioPlayer.interrupt(); + } + } else if (event instanceof PostReasoningEvent) { + PostReasoningEvent e = (PostReasoningEvent) event; + Msg msg = e.getReasoningMessage(); + + if (msg != null) { + String text = msg.getTextContent(); + if (text != null && !text.isEmpty()) { + synthesizeAndEmit(text); + } + } + } + + return Mono.just(event); + } + + /** + * Emit audio to all consumers (player, callback, stream). + */ + private void emitAudio(AudioBlock audio) { + // 1. Emit to reactive stream (for SSE/WebSocket consumers) + // Note: FAIL_ZERO_SUBSCRIBER is normal when no external subscribers + // (e.g., when only using audioPlayer for local playback) + Sinks.EmitResult result = audioSink.tryEmitNext(audio); + if (result.isFailure()) { + if (result == Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER) { + // Normal case when no external subscribers (local playback only) + log.debug( + "No subscribers for audio stream (normal when using local playback only)"); + } else { + log.warn("Failed to emit audio to sink: {}", result); + } + } + + // 2. Call callback if provided + if (audioCallback != null) { + audioCallback.accept(audio); + } + + // 3. Play locally if player is configured + if (audioPlayer != null) { + audioPlayer.play(audio); + } + } + + /** + * Ensure audio player is started. + */ + private void ensurePlayerStarted() { + if (audioPlayer != null && autoStartPlayer && !playerStarted) { + audioPlayer.start(); + playerStarted = true; + } + } + + /** + * Interrupts current playback when a new reasoning starts. + * + *

    This method: + *

      + *
    • Interrupts local AudioPlayer - clears queue and stops current playback + * (even if TTS session has already ended, AudioPlayer may still be playing)
      • + *
    • Closes current TTS session if active - stops receiving new audio from WebSocket
      • + *
    • Does NOT interrupt audioSink - frontend stream continues, allowing frontend to + * control playback independently
      • + *
    + * + *

    Note: The audioSink (for frontend/SSE consumers) is not interrupted because + * frontend applications can control audio playback themselves. Only local playback + * is interrupted. + */ + private void interruptCurrentPlayback() { + // Always interrupt AudioPlayer if it's started, even if TTS session has ended + // This handles the case where AudioPlayer is still playing audio from previous response + if (audioPlayer != null && playerStarted) { + audioPlayer.interrupt(); + log.debug("Interrupted AudioPlayer (cleared queue, ready for new audio)"); + } + + // Close TTS session only if it's still active + if (sessionStarted) { + // Close current TTS session (stops receiving new audio from WebSocket) + if (ttsModel != null) { + ttsModel.close(); + } + sessionStarted = false; + log.debug("Closed TTS session for new reasoning"); + } + + // Note: audioSink is NOT interrupted - it continues to send audio to frontend + // Frontend can control playback independently (pause, stop, etc.) + } + + /** + * Drain the audio player asynchronously. + * + *

    This ensures audio plays completely without blocking the caller. + * The drain operation runs in a separate thread, allowing the agent + * to return immediately after synthesis completes. + */ + private void drainPlayerAsync() { + if (audioPlayer != null) { + Mono.fromRunnable(() -> audioPlayer.drain()) + .subscribeOn(Schedulers.boundedElastic()) + .subscribe(); + } + } + + /** + * Synthesize complete text and emit (for batch mode). + */ + private void synthesizeAndEmit(String text) { + if (text == null || text.isEmpty()) { + return; + } + + log.debug("Synthesizing text: {}...", text.substring(0, Math.min(50, text.length()))); + + ensurePlayerStarted(); + + ttsModel.synthesizeStream(text) + .doOnNext(this::emitAudio) + .doOnComplete(this::drainPlayerAsync) + .blockLast(); + } + + /** + * Stop the audio player and clean up resources. + */ + public void stop() { + // Close TTS WebSocket connection + if (ttsModel != null) { + ttsModel.close(); + } + + if (audioPlayer != null && playerStarted) { + audioPlayer.stop(); + playerStarted = false; + } + sessionStarted = false; + Sinks.EmitResult result = audioSink.tryEmitComplete(); + if (result.isFailure()) { + log.warn("Failed to complete audio sink: {}", result); + } + } + + /** + * Creates a new builder for TTSHook. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing TTSHook instances. + */ + public static class Builder { + private DashScopeRealtimeTTSModel ttsModel; + private AudioPlayer audioPlayer; + private boolean autoStartPlayer = true; + private boolean realtimeMode = true; + private Consumer audioCallback; + + /** + * Sets the TTS model for speech synthesis. (Required) + * + * @param ttsModel the realtime TTS model + * @return this builder + */ + public Builder ttsModel(DashScopeRealtimeTTSModel ttsModel) { + this.ttsModel = ttsModel; + return this; + } + + /** + * Sets the audio player for local playback. (Optional) + * + *

    If not set: + *

      + *
    • If audioCallback is also not set: A default AudioPlayer will be created + * automatically (24000 Hz sample rate, mono, 16-bit PCM) for local playback.
      • + *
    • If audioCallback is set: Audio will only be available via audioCallback + * or getAudioStream(), suitable for server-side usage.
      • + *
    + * + * @param audioPlayer the audio player, or null to use default or server mode + * @return this builder + */ + public Builder audioPlayer(AudioPlayer audioPlayer) { + this.audioPlayer = audioPlayer; + return this; + } + + /** + * Sets whether to auto-start the audio player. + * + * @param autoStartPlayer true to auto-start (default: true) + * @return this builder + */ + public Builder autoStartPlayer(boolean autoStartPlayer) { + this.autoStartPlayer = autoStartPlayer; + return this; + } + + /** + * Sets whether to use real-time mode. + * + *

    When true (default), TTS is triggered on each text chunk as LLM generates. + * When false, TTS waits for complete response before synthesis. + * + * @param realtimeMode true for real-time "speak as you generate" (default) + * @return this builder + */ + public Builder realtimeMode(boolean realtimeMode) { + this.realtimeMode = realtimeMode; + return this; + } + + /** + * Sets a callback for receiving audio blocks. (Optional) + * + *

    This is the recommended way for server-side usage to handle audio. + * The callback is invoked for each audio block as it's synthesized. + * + *

    Example for SSE: + * 

    {@code
+         * .audioCallback(audio -> {
+         *     Base64Source src = (Base64Source) audio.getSource();
+         *     sseEmitter.send(SseEmitter.event()
+         *         .name("audio")
+         *         .data(src.getData()));
+         * })
+         * }
    + * + * @param audioCallback callback to receive audio blocks + * @return this builder + */ + public Builder audioCallback(Consumer audioCallback) { + this.audioCallback = audioCallback; + return this; + } + + /** + * Builds the TTSHook instance. + * + *

    If neither audioPlayer nor audioCallback is provided, a default AudioPlayer + * will be created automatically for local playback (24000 Hz sample rate). + * + * @return configured TTSHook + * @throws IllegalArgumentException if ttsModel is not set + */ + public TTSHook build() { + if (ttsModel == null) { + throw new IllegalArgumentException("TTS model is required"); + } + + // If neither audioPlayer nor audioCallback is set, create a default AudioPlayer + // for local playback (CLI/desktop mode) + if (audioPlayer == null && audioCallback == null) { + audioPlayer = + AudioPlayer.builder() + .sampleRate(24000) // Default sample rate for TTS models + .sampleSizeInBits(16) + .channels(1) // Mono + .signed(true) + .bigEndian(false) // Little-endian + .build(); + } + + return new TTSHook(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/AudioPlayer.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/AudioPlayer.java new file mode 100644 index 000000000..79b0155b0 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/AudioPlayer.java @@ -0,0 +1,326 @@ +/* + * 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 + * + * https://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.model.tts; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import java.util.Base64; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.atomic.AtomicBoolean; +import javax.sound.sampled.AudioFormat; +import javax.sound.sampled.AudioSystem; +import javax.sound.sampled.DataLine; +import javax.sound.sampled.LineUnavailableException; +import javax.sound.sampled.SourceDataLine; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * Audio player for playing PCM audio data in real-time. + * + *

    This player uses Java Sound API (javax.sound.sampled) to play + * audio data. It supports both synchronous and asynchronous playback. + * + *

    Example usage: + * 

    {@code
+ * AudioPlayer player = AudioPlayer.builder()
+ *     .sampleRate(24000)
+ *     .build();
+ *
+ * player.start();
+ *
+ * // Play audio chunks as they arrive
+ * ttsModel.push("hello").subscribe(player::play);
+ *
+ * player.stop();
+ * }
    + */ +public class AudioPlayer { + + private static final Logger log = LoggerFactory.getLogger(AudioPlayer.class); + + private final int sampleRate; + private final int sampleSizeInBits; + private final int channels; + private final boolean signed; + private final boolean bigEndian; + + private SourceDataLine line; + private final AtomicBoolean running = new AtomicBoolean(false); + private final BlockingQueue audioQueue = new LinkedBlockingQueue<>(); + private Thread playbackThread; + + private AudioPlayer(Builder builder) { + this.sampleRate = builder.sampleRate; + this.sampleSizeInBits = builder.sampleSizeInBits; + this.channels = builder.channels; + this.signed = builder.signed; + this.bigEndian = builder.bigEndian; + } + + /** + * Starts the audio player and opens the audio line. + * + * @throws TTSException if audio line cannot be opened + */ + public void start() { + if (running.get()) { + return; + } + + try { + AudioFormat format = + new AudioFormat(sampleRate, sampleSizeInBits, channels, signed, bigEndian); + DataLine.Info info = new DataLine.Info(SourceDataLine.class, format); + + if (!AudioSystem.isLineSupported(info)) { + throw new TTSException("Audio line not supported: " + format); + } + + line = (SourceDataLine) AudioSystem.getLine(info); + line.open(format); + line.start(); + running.set(true); + + // Start background playback thread + playbackThread = new Thread(this::playbackLoop, "audio-player"); + playbackThread.setDaemon(true); + playbackThread.start(); + + log.debug("AudioPlayer started with format: {}", format); + } catch (LineUnavailableException e) { + throw new TTSException("Failed to open audio line", e); + } + } + + /** + * Plays audio data synchronously. + * + * @param audioData PCM audio data + */ + public void playSync(byte[] audioData) { + if (!running.get()) { + start(); + } + if (line != null && audioData != null && audioData.length > 0) { + line.write(audioData, 0, audioData.length); + } + } + + /** + * Queues audio data for asynchronous playback. + * + * @param audioData PCM audio data + */ + public void play(byte[] audioData) { + if (!running.get()) { + start(); + } + if (audioData != null && audioData.length > 0) { + boolean enqueued = audioQueue.offer(audioData); + if (!enqueued) { + log.warn( + "Failed to enqueue audio data for asynchronous playback; audio data may be" + + " dropped."); + } + } + } + + /** + * Plays an AudioBlock. + * + * @param audioBlock the audio block to play + */ + public void play(AudioBlock audioBlock) { + if (audioBlock == null || audioBlock.getSource() == null) { + return; + } + + if (audioBlock.getSource() instanceof Base64Source) { + Base64Source source = (Base64Source) audioBlock.getSource(); + if (source.getData() != null && !source.getData().isEmpty()) { + byte[] audioData = Base64.getDecoder().decode(source.getData()); + play(audioData); + } + } + } + + /** + * Interrupts current playback and clears the queue, but keeps the audio line open. + * + *

    This is useful when you want to immediately stop current playback and start + * playing new audio without closing and reopening the audio line. Unlike {@link #stop()}, + * this method keeps the audio line open so new audio can be played immediately. + */ + public void interrupt() { + // Clear the queue immediately + audioQueue.clear(); + + // Stop and flush the current line + if (line != null) { + line.stop(); + line.flush(); + line.start(); // Restart to accept new audio + } + + log.debug("AudioPlayer interrupted (queue cleared, line kept open)"); + } + + /** + * Stops the audio player and closes the audio line. + */ + public void stop() { + running.set(false); + + if (playbackThread != null) { + playbackThread.interrupt(); + try { + playbackThread.join(1000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + + if (line != null) { + line.drain(); + line.stop(); + line.close(); + line = null; + } + + audioQueue.clear(); + log.debug("AudioPlayer stopped"); + } + + /** + * Waits for all queued audio to finish playing. + */ + public void drain() { + // Wait for queue to empty + while (!audioQueue.isEmpty() && running.get()) { + try { + Thread.sleep(100); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + break; + } + } + + // Drain the audio line + if (line != null) { + line.drain(); + } + } + + private void playbackLoop() { + while (running.get()) { + try { + byte[] audioData = audioQueue.poll(100, java.util.concurrent.TimeUnit.MILLISECONDS); + if (audioData != null && line != null) { + line.write(audioData, 0, audioData.length); + } + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + break; + } + } + } + + /** + * Creates a new builder for AudioPlayer. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing AudioPlayer instances. + */ + public static class Builder { + private int sampleRate = 24000; + private int sampleSizeInBits = 16; + private int channels = 1; + private boolean signed = true; + private boolean bigEndian = false; + + /** + * Sets the sample rate in Hz. + * + * @param sampleRate sample rate (e.g., 16000, 24000, 48000) + * @return this builder + */ + public Builder sampleRate(int sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + /** + * Sets the sample size in bits. + * + * @param sampleSizeInBits bits per sample (e.g., 8, 16) + * @return this builder + */ + public Builder sampleSizeInBits(int sampleSizeInBits) { + this.sampleSizeInBits = sampleSizeInBits; + return this; + } + + /** + * Sets the number of audio channels. + * + * @param channels 1 for mono, 2 for stereo + * @return this builder + */ + public Builder channels(int channels) { + this.channels = channels; + return this; + } + + /** + * Sets whether the audio data is signed. + * + * @param signed true for signed, false for unsigned + * @return this builder + */ + public Builder signed(boolean signed) { + this.signed = signed; + return this; + } + + /** + * Sets the byte order of the audio data. + * + * @param bigEndian true for big-endian, false for little-endian + * @return this builder + */ + public Builder bigEndian(boolean bigEndian) { + this.bigEndian = bigEndian; + return this; + } + + /** + * Builds the AudioPlayer instance. + * + * @return a configured AudioPlayer + */ + public AudioPlayer build() { + return new AudioPlayer(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModel.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModel.java new file mode 100644 index 000000000..760b0b7db --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModel.java @@ -0,0 +1,972 @@ +/* + * 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 + * + * https://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.model.tts; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.model.transport.WebSocketTransport; +import io.agentscope.core.model.transport.websocket.JdkWebSocketTransport; +import io.agentscope.core.model.transport.websocket.WebSocketConnection; +import io.agentscope.core.model.transport.websocket.WebSocketRequest; +import io.agentscope.core.util.JsonException; +import io.agentscope.core.util.JsonUtils; +import java.io.ByteArrayOutputStream; +import java.time.Duration; +import java.util.Base64; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import reactor.core.publisher.Flux; +import reactor.core.publisher.Mono; +import reactor.core.publisher.Sinks; + +/** + * DashScope Realtime TTS Model with WebSocket streaming input support. + * + *

    This model uses DashScope's WebSocket-based TTS API via WebSocketTransport, + * enabling true streaming input where text can be pushed incrementally while + * maintaining context continuity for natural prosody and intonation. + * + *

    Key Features: + *

      + *
    • WebSocket-based streaming with WebSocketTransport
      • + *
    • Supports both {@code server_commit} and {@code commit} modes
      • + *
    • {@code push(text)} - Push text incrementally, TTS maintains context
      • + *
    • {@code finish()} - Signal end of input, get remaining audio
      • + *
    • Solves prosody/intonation issues that occur with independent HTTP requests
      • + *
    • No 600-character limit per request (streaming input)
      • + *
    + * + *

    Session Modes: + *

      + *
    • {@code server_commit} - Server automatically commits text buffer for synthesis
      • + *
    • {@code commit} - Client must manually commit text buffer
      • + *
    + * + *

    Usage Example: + * 

    {@code
+ * DashScopeRealtimeTTSModel tts = DashScopeRealtimeTTSModel.builder()
+ *     .apiKey(apiKey)
+ *     .modelName("qwen3-tts-flash-realtime")
+ *     .voice("Cherry")
+ *     .mode(SessionMode.SERVER_COMMIT)
+ *     .build();
+ *
+ * // Start a streaming session
+ * tts.startSession();
+ *
+ * // Push text chunks as LLM generates them (context is maintained!)
+ * tts.push("Hello, ").subscribe(audio -> player.play(audio));
+ * tts.push("welcome to ").subscribe(audio -> player.play(audio));
+ * tts.push("AgentScope.").subscribe(audio -> player.play(audio));
+ *
+ * // Finish and get remaining audio
+ * tts.finish().subscribe(audio -> player.play(audio));
+ * }
    + */ +public class DashScopeRealtimeTTSModel implements RealtimeTTSModel { + + private static final Logger log = LoggerFactory.getLogger(DashScopeRealtimeTTSModel.class); + + /** WebSocket URL for DashScope realtime TTS API. */ + private static final String WEBSOCKET_URL = "wss://dashscope.aliyuncs.com/api-ws/v1/realtime"; + + private final String apiKey; + private final String modelName; + private final String voice; + private final int sampleRate; + private final String format; + private final SessionMode mode; + private final String languageType; + + // WebSocket client and state + private final WebSocketTransport webSocketTransport; + private WebSocketConnection connection; + private final AtomicBoolean sessionActive = new AtomicBoolean(false); + private Sinks.Many audioSink; + private Mono messageReceiver; + + // Response tracking + private final AtomicBoolean isResponding = new AtomicBoolean(false); + private CompletableFuture responseDoneFuture; + private String currentResponseId; + private String currentItemId; + + /** + * Session mode for TTS. + */ + public enum SessionMode { + /** Server automatically commits text buffer for synthesis. */ + SERVER_COMMIT("server_commit"), + /** Client must manually commit text buffer. */ + COMMIT("commit"); + + private final String value; + + SessionMode(String value) { + this.value = value; + } + + public String getValue() { + return value; + } + } + + private DashScopeRealtimeTTSModel(Builder builder) { + this.apiKey = builder.apiKey; + this.modelName = builder.modelName; + this.voice = builder.voice; + this.sampleRate = builder.sampleRate; + this.format = builder.format; + this.mode = builder.mode; + this.languageType = builder.languageType; + this.webSocketTransport = JdkWebSocketTransport.create(); + } + + /** + * Returns true if this model supports streaming input (push/finish pattern). + * + * @return always true for this implementation + */ + public boolean supportsStreamingInput() { + return true; + } + + /** + * Starts a new TTS session with WebSocket connection. + * + *

    This establishes a WebSocket connection to DashScope's TTS service. + * Call this before using push()/finish() pattern. + */ + @Override + public void startSession() { + if (sessionActive.compareAndSet(false, true)) { + audioSink = Sinks.many().multicast().onBackpressureBuffer(); + responseDoneFuture = new CompletableFuture<>(); + + try { + WebSocketRequest request = + WebSocketRequest.builder(WEBSOCKET_URL + "?model=" + modelName) + .header("Authorization", "Bearer " + apiKey) + .connectTimeout(Duration.ofSeconds(30)) + .build(); + + connection = + webSocketTransport + .connect(request, String.class) + .doOnSuccess(conn -> log.debug("TTS WebSocket connection opened")) + .doOnError( + error -> + log.error( + "Failed to connect to TTS WebSocket: {}", + error.getMessage())) + .block(); + + if (connection == null) { + sessionActive.set(false); + throw new TTSException("Failed to establish WebSocket connection"); + } + + // Start message receiver in background + startMessageReceiver(); + + // Configure the session + updateSession(); + + log.debug("TTS WebSocket session started"); + } catch (Exception e) { + sessionActive.set(false); + log.error("Failed to start TTS session: {}", e.getMessage()); + throw new TTSException("Failed to start TTS session", e); + } + } + } + + /** + * Starts the message receiver to process incoming WebSocket messages. + */ + private void startMessageReceiver() { + if (connection == null) { + return; + } + + messageReceiver = + connection + .receive() + .doOnNext(this::processMessage) + .doOnError( + error -> + log.error( + "Error receiving WebSocket message: {}", + error.getMessage())) + .doOnComplete(() -> log.debug("WebSocket message receiver completed")) + .then(); + + // Subscribe in background + messageReceiver.subscribe(); + } + + /** + * Processes a received WebSocket message. + * + * @param message the JSON message from server + */ + private void processMessage(String message) { + try { + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(message, RealtimeTTSResponseEvent.class); + String eventType = event.getType(); + + if (!"response.audio.delta".equals(eventType)) { + log.debug("Received event: {}", eventType); + } + + switch (eventType) { + case "error": + RealtimeTTSResponseEvent.ErrorEvent errorEvent = + (RealtimeTTSResponseEvent.ErrorEvent) event; + String errMsg = + errorEvent.getError() != null + ? errorEvent.getError().toString() + : "Unknown error"; + log.error("TTS API error: {}", errMsg); + if (audioSink != null) { + audioSink.tryEmitError(new TTSException("TTS API error: " + errMsg)); + } + break; + + case "session.created": + RealtimeTTSResponseEvent.SessionCreatedEvent sessionCreatedEvent = + (RealtimeTTSResponseEvent.SessionCreatedEvent) event; + String sessionId = + sessionCreatedEvent.getSession() != null + ? sessionCreatedEvent.getSession().getId() + : null; + log.debug("Session created: {}", sessionId); + break; + + case "session.updated": + log.debug("Session updated"); + break; + + case "input_text_buffer.committed": + RealtimeTTSResponseEvent.InputTextBufferCommittedEvent committedEvent = + (RealtimeTTSResponseEvent.InputTextBufferCommittedEvent) event; + log.debug("Text buffer committed, item_id: {}", committedEvent.getItemId()); + break; + + case "input_text_buffer.cleared": + log.debug("Text buffer cleared"); + break; + + case "response.created": + RealtimeTTSResponseEvent.ResponseCreatedEvent responseCreatedEvent = + (RealtimeTTSResponseEvent.ResponseCreatedEvent) event; + currentResponseId = + responseCreatedEvent.getResponse() != null + ? responseCreatedEvent.getResponse().getId() + : null; + isResponding.set(true); + responseDoneFuture = new CompletableFuture<>(); + log.debug("Response created: {}", currentResponseId); + break; + + case "response.output_item.added": + RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent itemAddedEvent = + (RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent) event; + currentItemId = + itemAddedEvent.getItem() != null + ? itemAddedEvent.getItem().getId() + : null; + log.debug("Output item added: {}", currentItemId); + break; + + case "response.output_item.done": + log.debug("Output item done"); + break; + + case "response.content_part.added": + RealtimeTTSResponseEvent.ResponseContentPartAddedEvent contentPartEvent = + (RealtimeTTSResponseEvent.ResponseContentPartAddedEvent) event; + String contentPartId = + contentPartEvent.getContentPart() != null + ? contentPartEvent.getContentPart().getId() + : null; + log.debug("Content part added: {}", contentPartId); + break; + + case "response.content_part.done": + log.debug("Content part done"); + break; + + case "response.audio.delta": + RealtimeTTSResponseEvent.ResponseAudioDeltaEvent audioDeltaEvent = + (RealtimeTTSResponseEvent.ResponseAudioDeltaEvent) event; + String base64Audio = audioDeltaEvent.getDelta(); + if (base64Audio != null && !base64Audio.isEmpty()) { + AudioBlock audioBlock = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/" + format) + .data(base64Audio) + .build()) + .build(); + if (audioSink != null) { + Sinks.EmitResult result = audioSink.tryEmitNext(audioBlock); + if (result.isFailure()) { + // Use debug level - this can happen if subscriber cancelled + log.debug( + "Failed to emit audio (sink may be cancelled): {}", result); + } + } + } + break; + + case "response.audio.done": + log.debug("Audio generation completed"); + break; + + case "response.done": + isResponding.set(false); + currentResponseId = null; + currentItemId = null; + if (responseDoneFuture != null && !responseDoneFuture.isDone()) { + responseDoneFuture.complete(null); + } + log.debug("Response completed"); + break; + + case "session.finished": + log.debug("Session finished"); + if (audioSink != null) { + audioSink.tryEmitComplete(); + } + break; + + default: + // Handle unknown event types gracefully + if (event instanceof RealtimeTTSResponseEvent.UnknownEvent) { + log.warn("Received unknown event type: {}", eventType); + } else { + log.warn("Unhandled event type: {}", eventType); + } + break; + } + } catch (Exception e) { + log.error("Error processing WebSocket message: {}", e.getMessage()); + if (audioSink != null) { + audioSink.tryEmitError( + new TTSException("Error processing message: " + e.getMessage(), e)); + } + } + } + + /** + * Updates the session configuration. + */ + private void updateSession() { + SessionConfig sessionConfig = + SessionConfig.builder() + .mode(mode.getValue()) + .voice(voice) + .languageType(languageType) + .responseFormat(format) + .sampleRate(sampleRate) + .build(); + + TTSEvent.SessionUpdateEvent event = + new TTSEvent.SessionUpdateEvent(generateEventId(), sessionConfig); + + sendEvent(event); + log.debug("Session update sent: {}", sessionConfig); + } + + /** + * Generates a unique event ID. + */ + private String generateEventId() { + return "event_" + System.currentTimeMillis(); + } + + /** + * Sends an event to the WebSocket. + */ + private void sendEvent(TTSEvent event) { + if (connection == null || !connection.isOpen()) { + throw new TTSException("WebSocket not connected"); + } + try { + String json = JsonUtils.getJsonCodec().toJson(event); + log.debug("Sending event: type={}, event_id={}", event.getType(), event.getEventId()); + connection.send(json).subscribe(); + } catch (JsonException e) { + throw new TTSException("Failed to serialize event", e); + } + } + + /** + * Pushes a text chunk for synthesis. + * + *

    Unlike HTTP-based TTS, this maintains context continuity across + * multiple push() calls, resulting in natural prosody and intonation. + * + *

    Note: This method returns empty Flux. Audio is delivered through + * {@link #getAudioStream()} to avoid duplicate subscriptions causing + * repeated audio playback. + * + * @param text the text chunk to synthesize + * @return empty Flux (audio delivered via getAudioStream) + */ + @Override + public Flux push(String text) { + // Check for null/empty text first to avoid starting session unnecessarily + if (text == null || text.isEmpty()) { + return Flux.empty(); + } + + if (!sessionActive.get()) { + startSession(); + } + + // Append text to the WebSocket session + appendText(text); + + // Return empty - audio is delivered through getAudioStream() + return Flux.empty(); + } + + /** + * Appends text to the input buffer. + * + * @param text the text to append + */ + private void appendText(String text) { + TTSEvent.AppendTextEvent event = new TTSEvent.AppendTextEvent(generateEventId(), text); + sendEvent(event); + } + + /** + * Commits the text buffer to trigger processing. + * + *

    Only needed in {@link SessionMode#COMMIT} mode. + * In {@link SessionMode#SERVER_COMMIT} mode, the server commits automatically. + */ + public void commitTextBuffer() { + TTSEvent.CommitEvent event = new TTSEvent.CommitEvent(generateEventId()); + sendEvent(event); + log.debug("Text buffer committed"); + } + + /** + * Clears the text buffer. + */ + public void clearTextBuffer() { + TTSEvent.ClearEvent event = new TTSEvent.ClearEvent(generateEventId()); + sendEvent(event); + log.debug("Text buffer cleared"); + } + + /** + * Finishes the streaming session and retrieves remaining audio. + * + *

    This signals the end of input and waits for all audio to be generated. + * The sink will be completed when the server sends the "session.finished" event. + * + * @return Flux of remaining AudioBlock chunks + */ + @Override + public Flux finish() { + if (!sessionActive.get() || connection == null) { + return Flux.empty(); + } + + // Send session finish event + TTSEvent.FinishEvent event = new TTSEvent.FinishEvent(generateEventId()); + sendEvent(event); + + sessionActive.set(false); + log.debug("TTS session finish requested"); + + // Don't complete the sink here - let the message receiver complete it + // when it receives the "session.finished" event from the server. + // This ensures all audio data is received before completing. + + return audioSink != null ? audioSink.asFlux() : Flux.empty(); + } + + /** + * Waits for the current response to complete. + * + * @param timeout the maximum time to wait + * @param unit the time unit of the timeout + * @return true if the response completed within the timeout + */ + public boolean waitForResponseDone(long timeout, TimeUnit unit) { + if (responseDoneFuture == null) { + return true; + } + try { + responseDoneFuture.get(timeout, unit); + return true; + } catch (Exception e) { + log.warn("Timeout waiting for response done: {}", e.getMessage()); + return false; + } + } + + /** + * Closes the WebSocket connection and releases resources. + */ + @Override + public void close() { + if (connection != null) { + try { + connection.close().block(Duration.ofSeconds(5)); + } catch (Exception e) { + log.warn("Error closing WebSocket: {}", e.getMessage()); + } + connection = null; + } + sessionActive.set(false); + if (audioSink != null) { + audioSink.tryEmitComplete(); + } + } + + /** + * Gets the audio stream for listening to all audio chunks. + * + * @return Flux of AudioBlock that emits audio as it's synthesized + */ + @Override + public Flux getAudioStream() { + return audioSink != null ? audioSink.asFlux() : Flux.empty(); + } + + /** + * Synthesizes complete text to audio using streaming. + * + *

    This is a convenience method that creates a session, pushes all text, + * and returns the complete audio stream. + * + * @param text the complete text to synthesize + * @return Flux of AudioBlock chunks as they are generated + */ + @Override + public Flux synthesizeStream(String text) { + Sinks.Many streamSink = Sinks.many().unicast().onBackpressureBuffer(); + AtomicReference> connectionRef = new AtomicReference<>(); + + WebSocketRequest request = + WebSocketRequest.builder(WEBSOCKET_URL + "?model=" + modelName) + .header("Authorization", "Bearer " + apiKey) + .connectTimeout(Duration.ofSeconds(30)) + .build(); + + return webSocketTransport + .connect(request, String.class) + .flatMapMany( + conn -> { + connectionRef.set(conn); + + // Setup message receiver + StreamEventProcessor eventProcessor = + new StreamEventProcessor(conn, streamSink, text); + Mono receiver = + conn.receive().doOnNext(eventProcessor::processMessage).then(); + receiver.subscribe(); + + // Send session update + sendStreamSessionUpdate(conn, streamSink); + + return streamSink.asFlux(); + }) + .doOnCancel( + () -> { + log.debug("Stream cancelled, closing WebSocket"); + WebSocketConnection ws = connectionRef.get(); + if (ws != null && ws.isOpen()) { + ws.close().subscribe(); + } + }) + .doOnTerminate(() -> log.debug("Stream terminated")); + } + + /** + * Sends session update event for streaming synthesis. + * + * @param conn the WebSocket connection + * @param streamSink the sink for emitting errors + */ + private void sendStreamSessionUpdate( + WebSocketConnection conn, Sinks.Many streamSink) { + SessionConfig sessionConfig = + SessionConfig.builder() + .mode(mode.getValue()) + .voice(voice) + .languageType(languageType) + .responseFormat(format) + .sampleRate(sampleRate) + .build(); + + TTSEvent.SessionUpdateEvent event = + new TTSEvent.SessionUpdateEvent(generateEventId(), sessionConfig); + + try { + conn.send(JsonUtils.getJsonCodec().toJson(event)).subscribe(); + } catch (JsonException e) { + log.error("Failed to send session update: {}", e.getMessage()); + streamSink.tryEmitError(new TTSException("Failed to send session update", e)); + } + } + + /** + * Sends an event to the WebSocket connection. + * + * @param conn the WebSocket connection + * @param event the event to send + */ + private void sendStreamEvent(WebSocketConnection conn, TTSEvent event) { + conn.send(JsonUtils.getJsonCodec().toJson(event)).subscribe(); + } + + /** + * Event processor for streaming synthesis WebSocket messages. + */ + private class StreamEventProcessor { + private final WebSocketConnection connection; + private final Sinks.Many sink; + private final String textToSynthesize; + + StreamEventProcessor( + WebSocketConnection connection, + Sinks.Many sink, + String textToSynthesize) { + this.connection = connection; + this.sink = sink; + this.textToSynthesize = textToSynthesize; + } + + /** + * Processes a WebSocket message event. + * + * @param message the JSON message from server + */ + void processMessage(String message) { + try { + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(message, RealtimeTTSResponseEvent.class); + String eventType = event.getType(); + + if (!"response.audio.delta".equals(eventType)) { + log.debug("Received event: {}", eventType); + } + + switch (eventType) { + case "error": + handleError((RealtimeTTSResponseEvent.ErrorEvent) event); + break; + case "session.created": + handleSessionCreated((RealtimeTTSResponseEvent.SessionCreatedEvent) event); + break; + case "session.updated": + handleSessionUpdated(); + break; + case "response.output_item.done": + // Output item done - no special handling needed, just log + log.debug("Output item done event received"); + break; + case "response.content_part.added": + // Content part added - no special handling needed, just log + log.debug("Content part added event received"); + break; + case "response.content_part.done": + // Content part done - no special handling needed, just log + log.debug("Content part done event received"); + break; + case "response.audio.delta": + handleAudioDelta((RealtimeTTSResponseEvent.ResponseAudioDeltaEvent) event); + break; + case "response.audio.done": + log.debug("Audio generation completed"); + break; + case "response.done": + log.debug("Response completed"); + break; + case "session.finished": + handleSessionFinished(); + break; + default: + // Handle unknown event types gracefully + if (event instanceof RealtimeTTSResponseEvent.UnknownEvent) { + log.debug("Received unknown event type: {}", eventType); + } else { + log.debug("Unhandled event type: {}", eventType); + } + break; + } + } catch (Exception e) { + log.error("Error processing message: {}", e.getMessage()); + sink.tryEmitError( + new TTSException("Error processing message: " + e.getMessage(), e)); + } + } + + private void handleError(RealtimeTTSResponseEvent.ErrorEvent event) { + String errMsg = + event.getError() != null ? event.getError().toString() : "Unknown error"; + log.error("TTS API error: {}", errMsg); + sink.tryEmitError(new TTSException("TTS API error: " + errMsg)); + } + + private void handleSessionCreated(RealtimeTTSResponseEvent.SessionCreatedEvent event) { + String sessionId = event.getSession() != null ? event.getSession().getId() : null; + log.debug("Session created: {}", sessionId); + } + + private void handleSessionUpdated() { + log.debug("Session updated, sending text"); + sendAppendTextEvent(); + if (mode == SessionMode.COMMIT) { + sendCommitEvent(); + } + sendFinishEvent(); + } + + private void sendAppendTextEvent() { + TTSEvent.AppendTextEvent event = + new TTSEvent.AppendTextEvent(generateEventId(), textToSynthesize); + sendStreamEvent(connection, event); + } + + private void sendCommitEvent() { + TTSEvent.CommitEvent event = new TTSEvent.CommitEvent(generateEventId()); + sendStreamEvent(connection, event); + } + + private void sendFinishEvent() { + TTSEvent.FinishEvent event = new TTSEvent.FinishEvent(generateEventId()); + sendStreamEvent(connection, event); + } + + private void handleAudioDelta(RealtimeTTSResponseEvent.ResponseAudioDeltaEvent event) { + String base64Audio = event.getDelta(); + if (base64Audio == null || base64Audio.isEmpty()) { + return; + } + + AudioBlock audioBlock = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/" + format) + .data(base64Audio) + .build()) + .build(); + + Sinks.EmitResult result = sink.tryEmitNext(audioBlock); + if (result.isFailure()) { + log.debug("Failed to emit audio (sink may be cancelled): {}", result); + } + } + + private void handleSessionFinished() { + log.debug("Session finished, completing stream"); + sink.tryEmitComplete(); + connection.close().subscribe(); + } + } + + /** + * Synthesizes text to audio (blocking). + * + * @param text the text to synthesize + * @param options optional TTS options (may be null) + * @return Mono containing the TTS response with audio data + */ + @Override + public Mono synthesize(String text, TTSOptions options) { + return Mono.fromCallable( + () -> { + ByteArrayOutputStream audioBuffer = new ByteArrayOutputStream(); + + synthesizeStream(text) + .doOnNext( + audioBlock -> { + if (audioBlock.getSource() instanceof Base64Source src) { + if (src.getData() != null) { + byte[] data = + Base64.getDecoder().decode(src.getData()); + audioBuffer.write(data, 0, data.length); + } + } + }) + .blockLast(); + + return TTSResponse.builder() + .audioData(audioBuffer.toByteArray()) + .format(format) + .sampleRate(sampleRate) + .build(); + }); + } + + /** + * Gets the model name. + * + * @return the model name + */ + @Override + public String getModelName() { + return modelName; + } + + /** + * Creates a new builder for DashScopeRealtimeTTSModel. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing DashScopeRealtimeTTSModel instances. + */ + public static class Builder { + private String apiKey; + // Use flash model which supports system voices (Cherry, Serena, etc.) + private String modelName = "qwen3-tts-flash-realtime"; + private String voice = "Cherry"; + private int sampleRate = 24000; + private String format = "pcm"; + private SessionMode mode = SessionMode.SERVER_COMMIT; + private String languageType = "Auto"; + + /** + * Sets the API key for DashScope authentication. + * + * @param apiKey the API key + * @return this builder + */ + public Builder apiKey(String apiKey) { + this.apiKey = apiKey; + return this; + } + + /** + * Sets the TTS model name. + * + *

    Supported models: + *

      + *
    • qwen3-tts-flash-realtime - supports system voices
      • + *
    • qwen3-tts-vd-realtime - supports voice design via text description
      • + *
    • qwen3-tts-vc-realtime - supports voice cloning
      • + *
    • qwen-tts-realtime - legacy model
      • + *
    + * + * @param modelName the model name + * @return this builder + */ + public Builder modelName(String modelName) { + this.modelName = modelName; + return this; + } + + /** + * Sets the voice for synthesis. + * + *

    Available voices include: Cherry, Serena, Ethan, Chelsie, etc. + * + * @param voice the voice name + * @return this builder + */ + public Builder voice(String voice) { + this.voice = voice; + return this; + } + + /** + * Sets the audio sample rate. + * + * @param sampleRate sample rate in Hz (default: 24000) + * @return this builder + */ + public Builder sampleRate(int sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + /** + * Sets the audio format. + * + *

    Supported formats: pcm, mp3, opus + * + * @param format audio format + * @return this builder + */ + public Builder format(String format) { + this.format = format; + return this; + } + + /** + * Sets the session mode. + * + *

    In {@link SessionMode#SERVER_COMMIT} mode, the server automatically + * commits text for synthesis. In {@link SessionMode#COMMIT} mode, the client + * must manually call {@link #commitTextBuffer()}. + * + * @param mode the session mode (default: SERVER_COMMIT) + * @return this builder + */ + public Builder mode(SessionMode mode) { + this.mode = mode; + return this; + } + + /** + * Sets the language type for synthesis. + * + *

    Supported values: Chinese, English, German, Italian, Portuguese, + * Spanish, Japanese, Korean, French, Russian, Auto + * + * @param languageType the language type (default: Auto) + * @return this builder + */ + public Builder languageType(String languageType) { + this.languageType = languageType; + return this; + } + + /** + * Builds the DashScopeRealtimeTTSModel instance. + * + * @return a configured DashScopeRealtimeTTSModel + * @throws IllegalArgumentException if apiKey is not set + */ + public DashScopeRealtimeTTSModel build() { + if (apiKey == null || apiKey.isEmpty()) { + throw new IllegalArgumentException("API key is required"); + } + return new DashScopeRealtimeTTSModel(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSModel.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSModel.java new file mode 100644 index 000000000..e1dfbd8cf --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSModel.java @@ -0,0 +1,490 @@ +/* + * 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 + * + * https://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.model.tts; + +import io.agentscope.core.Version; +import io.agentscope.core.model.transport.HttpRequest; +import io.agentscope.core.model.transport.HttpResponse; +import io.agentscope.core.model.transport.HttpTransport; +import io.agentscope.core.model.transport.HttpTransportException; +import io.agentscope.core.model.transport.HttpTransportFactory; +import io.agentscope.core.util.JsonException; +import io.agentscope.core.util.JsonUtils; +import java.util.Base64; +import java.util.HashMap; +import java.util.Map; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import reactor.core.publisher.Mono; + +/** + * DashScope TTS Model implementation. + * + *

    This implementation uses direct HTTP calls to DashScope's TTS API, + * supporting multiple TTS models including: + *

      + *
    • qwen3-tts-flash - Qwen3 TTS fast model
      • + *
    • qwen-tts - Qwen TTS model
      • + *
    • sambert-* - Sambert series (e.g., sambert-zhimao-v1)
      • + *
    • cosyvoice-* - CosyVoice series
      • + *
    + * + *

    Example usage: + * 

    {@code
+ * DashScopeTTSModel tts = DashScopeTTSModel.builder()
+ *     .apiKey(System.getenv("DASHSCOPE_API_KEY"))
+ *     .modelName("qwen3-tts-flash")
+ *     .voice("Cherry")
+ *     .build();
+ *
+ * TTSResponse response = tts.synthesize("你好，世界！", null).block();
+ * byte[] audioData = response.getAudioData();
+ * }
    + * + * @see DashScope TTS API Documentation + */ +public class DashScopeTTSModel implements TTSModel { + + private static final Logger log = LoggerFactory.getLogger(DashScopeTTSModel.class); + + /** Default base URL for DashScope API. */ + public static final String DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com"; + + /** TTS API endpoint (uses multimodal-generation for qwen-tts models). */ + public static final String TTS_ENDPOINT = + "/api/v1/services/aigc/multimodal-generation/generation"; + + private final String apiKey; + private final String modelName; + private final String voice; + private final TTSOptions defaultOptions; + private final String baseUrl; + private final HttpTransport transport; + + private DashScopeTTSModel(Builder builder) { + this.apiKey = builder.apiKey; + this.modelName = builder.modelName; + this.voice = builder.voice; + this.defaultOptions = builder.defaultOptions; + this.baseUrl = builder.baseUrl != null ? builder.baseUrl : DEFAULT_BASE_URL; + this.transport = + builder.transport != null ? builder.transport : HttpTransportFactory.getDefault(); + } + + /** + * Synthesizes speech from text using DashScope TTS API. + * + * @param text the text to convert to speech + * @param options optional TTS configuration, uses defaults if null + * @return a Mono containing the TTS response with audio data + */ + @Override + public Mono synthesize(String text, TTSOptions options) { + return Mono.fromCallable(() -> doSynthesize(text, options)); + } + + /** + * Performs the actual TTS synthesis by calling the DashScope API. + * + *

    This method builds the HTTP request, sends it to DashScope, + * and parses the response. If the API returns a URL instead of + * inline audio data, the audio is automatically downloaded. + * + * @param text the text to synthesize + * @param options optional TTS configuration + * @return TTSResponse containing audio data and metadata + * @throws TTSException if the API call fails or response parsing fails + */ + private TTSResponse doSynthesize(String text, TTSOptions options) { + TTSOptions effectiveOptions = options != null ? options : defaultOptions; + String effectiveVoice = + effectiveOptions != null && effectiveOptions.getVoice() != null + ? effectiveOptions.getVoice() + : voice; + + log.debug( + "TTS synthesize - model: {}, voice: {}, text length: {}", + modelName, + effectiveVoice, + text.length()); + + try { + String requestBody = buildRequestBody(text, effectiveVoice, effectiveOptions); + log.debug("DashScope TTS request body: {}", requestBody); + + HttpRequest request = + HttpRequest.builder() + .url(baseUrl + TTS_ENDPOINT) + .method("POST") + .headers(buildHeaders()) + .body(requestBody) + .build(); + + log.debug("Sending TTS request to: {}", request.getUrl()); + HttpResponse response = transport.execute(request); + log.debug("TTS response status: {}", response.getStatusCode()); + + if (!response.isSuccessful()) { + log.error( + "TTS request failed - status: {}, body: {}", + response.getStatusCode(), + response.getBody()); + throw new TTSException( + "TTS request failed with status " + response.getStatusCode(), + response.getStatusCode(), + response.getBody()); + } + + return parseResponse(response); + + } catch (JsonException e) { + log.error("Failed to build TTS request: {}", e.getMessage()); + throw new TTSException("Failed to build TTS request", e); + } catch (HttpTransportException e) { + log.error("HTTP transport error: {}", e.getMessage()); + throw new TTSException("HTTP transport error: " + e.getMessage(), e); + } + } + + /** + * Builds the request body for DashScope TTS API. + * + *

    Request format (per official API docs): + * 

    {@code
+     * {
+     *   "model": "qwen3-tts-flash",
+     *   "input": {
+     *     "text": "要合成的文本",
+     *     "voice": "Cherry",
+     *     "language_type": "Chinese"
+     *   },
+     *   "parameters": {
+     *     "sample_rate": 24000,
+     *     "format": "wav",
+     *     "rate": 1.0,
+     *     "volume": 50,
+     *     "pitch": 1.0
+     *   }
+     * }
+     * }
    + */ + private String buildRequestBody(String text, String voiceName, TTSOptions options) { + DashScopeTTSRequest.TTSInput.Builder inputBuilder = + DashScopeTTSRequest.TTSInput.builder().text(text); + if (voiceName != null) { + inputBuilder.voice(voiceName); + } + if (options != null && options.getLanguage() != null) { + inputBuilder.languageType(options.getLanguage()); + } + + DashScopeTTSRequest.Builder requestBuilder = + DashScopeTTSRequest.builder().model(modelName).input(inputBuilder.build()); + + if (options != null) { + DashScopeTTSRequest.TTSParameters.Builder paramsBuilder = + DashScopeTTSRequest.TTSParameters.builder(); + if (options.getSampleRate() != null) { + paramsBuilder.sampleRate(options.getSampleRate()); + } + if (options.getFormat() != null) { + paramsBuilder.format(options.getFormat()); + } + if (options.getSpeed() != null) { + paramsBuilder.rate(options.getSpeed().doubleValue()); + } + if (options.getVolume() != null) { + paramsBuilder.volume(options.getVolume().intValue()); + } + if (options.getPitch() != null) { + paramsBuilder.pitch(options.getPitch().doubleValue()); + } + DashScopeTTSRequest.TTSParameters params = paramsBuilder.build(); + // Only add parameters if at least one is set + if (params.getSampleRate() != null + || params.getFormat() != null + || params.getRate() != null + || params.getVolume() != null + || params.getPitch() != null) { + requestBuilder.parameters(params); + } + } + + DashScopeTTSRequest request = requestBuilder.build(); + return JsonUtils.getJsonCodec().toJson(request); + } + + /** + * Builds HTTP headers for the DashScope API request. + * + *

    Includes Authorization header with Bearer token, Content-Type, + * and User-Agent for request tracking. + * + * @return map of header names to values + */ + private Map buildHeaders() { + Map headers = new HashMap<>(); + headers.put("Authorization", "Bearer " + apiKey); + headers.put("Content-Type", "application/json"); + headers.put("User-Agent", Version.getUserAgent()); + return headers; + } + + /** + * Parses the TTS response. + * + *

    DashScope TTS API response format: + * 

    {@code
+     * {
+     *   "request_id": "xxx",
+     *   "output": {
+     *     "audio": {
+     *       "url": "https://...",
+     *       "data": "base64_encoded_audio"  // or raw bytes
+     *     }
+     *   },
+     *   "usage": {...}
+     * }
+     * }
    + */ + private TTSResponse parseResponse(HttpResponse httpResponse) { + String responseBody = httpResponse.getBody(); + log.debug("DashScope TTS raw response: {}", responseBody); + + try { + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(responseBody, DashScopeTTSResponse.class); + + // Check for errors + if (response.getCode() != null) { + String code = response.getCode(); + String message = + response.getMessage() != null ? response.getMessage() : "Unknown error"; + log.error("DashScope TTS API error - code: {}, message: {}", code, message); + throw new TTSException("DashScope TTS error: " + message, code, responseBody); + } + + String requestId = response.getRequestId(); + log.debug("TTS request_id: {}", requestId); + + TTSResponse.Builder builder = TTSResponse.builder().requestId(requestId); + + String audioUrl = null; + byte[] audioData = null; + + // Parse output + DashScopeTTSResponse.Output output = response.getOutput(); + if (output != null) { + DashScopeTTSResponse.Audio audio = output.getAudio(); + if (audio != null) { + // Check for URL + if (audio.getUrl() != null && !audio.getUrl().isEmpty()) { + audioUrl = audio.getUrl(); + log.debug("TTS audio URL present: {}", !audioUrl.isEmpty()); + if (!audioUrl.isEmpty()) { + builder.audioUrl(audioUrl); + } + } + // Check for base64 data + if (audio.getData() != null && !audio.getData().isEmpty()) { + String base64Data = audio.getData(); + log.debug( + "TTS audio data present: {}, length: {}", + base64Data != null && !base64Data.isEmpty(), + base64Data != null ? base64Data.length() : 0); + if (base64Data != null && !base64Data.isEmpty()) { + audioData = Base64.getDecoder().decode(base64Data); + builder.audioData(audioData); + log.debug("Decoded base64 audio: {} bytes", audioData.length); + } + } + } + } else { + log.warn("TTS response has no 'output' field"); + } + + // If no audioData but has URL, download the audio + if ((audioData == null || audioData.length == 0) + && audioUrl != null + && !audioUrl.isEmpty()) { + log.debug("No inline audio data, downloading from URL..."); + try { + audioData = downloadAudio(audioUrl); + builder.audioData(audioData); + log.debug("Downloaded audio from URL: {} bytes", audioData.length); + } catch (Exception e) { + log.warn("Failed to download audio from URL: {}", e.getMessage()); + } + } + + // Set default format if not specified + if (defaultOptions != null && defaultOptions.getFormat() != null) { + builder.format(defaultOptions.getFormat()); + } else { + builder.format("wav"); + } + + TTSResponse result = builder.build(); + log.debug( + "TTS synthesis complete - audioData: {} bytes, audioUrl: {}", + result.getAudioData() != null ? result.getAudioData().length : 0, + result.getAudioUrl() != null ? "present" : "null"); + + return result; + + } catch (JsonException e) { + log.error("Failed to parse TTS response: {}", e.getMessage()); + throw new TTSException("Failed to parse TTS response: " + e.getMessage(), e); + } + } + + /** + * Downloads audio data from a URL. + * + *

    Used when DashScope returns an audio URL instead of inline base64 data. + * This typically happens in non-streaming mode. + * + * @param audioUrl the URL to download audio from + * @return the raw audio bytes + * @throws Exception if download fails (network error, invalid URL, etc.) + */ + private byte[] downloadAudio(String audioUrl) throws Exception { + java.net.URL url = new java.net.URL(audioUrl); + try (java.io.InputStream is = url.openStream()) { + return is.readAllBytes(); + } + } + + /** + * Returns the name of the TTS model being used. + * + * @return the model name (e.g., "qwen3-tts-flash", "qwen-tts") + */ + @Override + public String getModelName() { + return modelName; + } + + /** + * Creates a new builder for DashScopeTTSModel. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing DashScopeTTSModel instances. + */ + public static class Builder { + private String apiKey; + private String modelName = "qwen3-tts-flash"; + private String voice = "Cherry"; + private TTSOptions defaultOptions; + private String baseUrl; + private HttpTransport transport; + + /** + * Sets the API key for DashScope authentication. + * + * @param apiKey the API key + * @return this builder + */ + public Builder apiKey(String apiKey) { + this.apiKey = apiKey; + return this; + } + + /** + * Sets the TTS model name. + * + *

    Available models: + *

      + *
    • qwen3-tts-flash - Fast Qwen3 TTS
      • + *
    • qwen-tts - Standard Qwen TTS
      • + *
    • sambert-zhimao-v1 - Sambert Chinese voice
      • + *
    • cosyvoice-v1 - CosyVoice model
      • + *
    + * + * @param modelName the model name + * @return this builder + */ + public Builder modelName(String modelName) { + this.modelName = modelName; + return this; + } + + /** + * Sets the default voice for synthesis. + * + *

    Common voices include: Cherry, zhimao, etc. + * + * @param voice the voice name + * @return this builder + */ + public Builder voice(String voice) { + this.voice = voice; + return this; + } + + /** + * Sets the default TTS options. + * + * @param options default options + * @return this builder + */ + public Builder defaultOptions(TTSOptions options) { + this.defaultOptions = options; + return this; + } + + /** + * Sets a custom base URL for DashScope API. + * + * @param baseUrl the base URL + * @return this builder + */ + public Builder baseUrl(String baseUrl) { + this.baseUrl = baseUrl; + return this; + } + + /** + * Sets the HTTP transport to use. + * + * @param transport the HTTP transport + * @return this builder + */ + public Builder httpTransport(HttpTransport transport) { + this.transport = transport; + return this; + } + + /** + * Builds the DashScopeTTSModel instance. + * + * @return a configured DashScopeTTSModel + * @throws IllegalArgumentException if apiKey is not set + */ + public DashScopeTTSModel build() { + if (apiKey == null || apiKey.isEmpty()) { + throw new IllegalArgumentException("API key is required"); + } + return new DashScopeTTSModel(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSRequest.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSRequest.java new file mode 100644 index 000000000..f65ba10cd --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSRequest.java @@ -0,0 +1,280 @@ +/* + * 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 + * + * https://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.model.tts; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * DashScope TTS API request DTO. + * + *

    Request format: + * 

    {@code
+ * {
+ *   "model": "qwen3-tts-flash",
+ *   "input": {
+ *     "text": "要合成的文本",
+ *     "voice": "Cherry",
+ *     "language_type": "Chinese"
+ *   },
+ *   "parameters": {
+ *     "sample_rate": 24000,
+ *     "format": "wav",
+ *     "rate": 1.0,
+ *     "volume": 50,
+ *     "pitch": 1.0
+ *   }
+ * }
+ * }
    + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public class DashScopeTTSRequest { + + @JsonProperty("model") + private final String model; + + @JsonProperty("input") + private final TTSInput input; + + @JsonProperty("parameters") + private final TTSParameters parameters; + + @JsonCreator + private DashScopeTTSRequest( + @JsonProperty("model") String model, + @JsonProperty("input") TTSInput input, + @JsonProperty("parameters") TTSParameters parameters) { + this.model = model; + this.input = input; + this.parameters = parameters; + } + + private DashScopeTTSRequest(Builder builder) { + this(builder.model, builder.input, builder.parameters); + } + + public String getModel() { + return model; + } + + public TTSInput getInput() { + return input; + } + + public TTSParameters getParameters() { + return parameters; + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private String model; + private TTSInput input; + private TTSParameters parameters; + + public Builder model(String model) { + this.model = model; + return this; + } + + public Builder input(TTSInput input) { + this.input = input; + return this; + } + + public Builder parameters(TTSParameters parameters) { + this.parameters = parameters; + return this; + } + + public DashScopeTTSRequest build() { + return new DashScopeTTSRequest(this); + } + } + + /** + * TTS input containing text, voice, and language. + */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static class TTSInput { + @JsonProperty("text") + private final String text; + + @JsonProperty("voice") + private final String voice; + + @JsonProperty("language_type") + private final String languageType; + + @JsonCreator + private TTSInput( + @JsonProperty("text") String text, + @JsonProperty("voice") String voice, + @JsonProperty("language_type") String languageType) { + this.text = text; + this.voice = voice; + this.languageType = languageType; + } + + private TTSInput(Builder builder) { + this(builder.text, builder.voice, builder.languageType); + } + + public String getText() { + return text; + } + + public String getVoice() { + return voice; + } + + public String getLanguageType() { + return languageType; + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private String text; + private String voice; + private String languageType; + + public Builder text(String text) { + this.text = text; + return this; + } + + public Builder voice(String voice) { + this.voice = voice; + return this; + } + + public Builder languageType(String languageType) { + this.languageType = languageType; + return this; + } + + public TTSInput build() { + return new TTSInput(this); + } + } + } + + /** + * TTS parameters for audio format settings. + */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static class TTSParameters { + @JsonProperty("sample_rate") + private final Integer sampleRate; + + @JsonProperty("format") + private final String format; + + @JsonProperty("rate") + private final Double rate; + + @JsonProperty("volume") + private final Integer volume; + + @JsonProperty("pitch") + private final Double pitch; + + @JsonCreator + private TTSParameters( + @JsonProperty("sample_rate") Integer sampleRate, + @JsonProperty("format") String format, + @JsonProperty("rate") Double rate, + @JsonProperty("volume") Integer volume, + @JsonProperty("pitch") Double pitch) { + this.sampleRate = sampleRate; + this.format = format; + this.rate = rate; + this.volume = volume; + this.pitch = pitch; + } + + private TTSParameters(Builder builder) { + this(builder.sampleRate, builder.format, builder.rate, builder.volume, builder.pitch); + } + + public Integer getSampleRate() { + return sampleRate; + } + + public String getFormat() { + return format; + } + + public Double getRate() { + return rate; + } + + public Integer getVolume() { + return volume; + } + + public Double getPitch() { + return pitch; + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private Integer sampleRate; + private String format; + private Double rate; + private Integer volume; + private Double pitch; + + public Builder sampleRate(Integer sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + public Builder format(String format) { + this.format = format; + return this; + } + + public Builder rate(Double rate) { + this.rate = rate; + return this; + } + + public Builder volume(Integer volume) { + this.volume = volume; + return this; + } + + public Builder pitch(Double pitch) { + this.pitch = pitch; + return this; + } + + public TTSParameters build() { + return new TTSParameters(this); + } + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSResponse.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSResponse.java new file mode 100644 index 000000000..2dd173f0e --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/DashScopeTTSResponse.java @@ -0,0 +1,121 @@ +/* + * 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 + * + * https://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.model.tts; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * DashScope TTS API HTTP response. + * + *

    Response format: + * 

    {@code
+ * {
+ *   "request_id": "xxx",
+ *   "output": {
+ *     "audio": {
+ *       "url": "https://...",
+ *       "data": "base64_encoded_audio"
+ *     }
+ *   },
+ *   "usage": {...}
+ * }
+ * }
    + */ +public class DashScopeTTSResponse { + + @JsonProperty("code") + private final String code; + + @JsonProperty("message") + private final String message; + + @JsonProperty("request_id") + private final String requestId; + + @JsonProperty("output") + private final Output output; + + @JsonCreator + public DashScopeTTSResponse( + @JsonProperty("code") String code, + @JsonProperty("message") String message, + @JsonProperty("request_id") String requestId, + @JsonProperty("output") Output output) { + this.code = code; + this.message = message; + this.requestId = requestId; + this.output = output; + } + + public String getCode() { + return code; + } + + public String getMessage() { + return message; + } + + public String getRequestId() { + return requestId; + } + + public Output getOutput() { + return output; + } + + /** + * Output section of the response. + */ + public static class Output { + @JsonProperty("audio") + private final Audio audio; + + @JsonCreator + public Output(@JsonProperty("audio") Audio audio) { + this.audio = audio; + } + + public Audio getAudio() { + return audio; + } + } + + /** + * Audio section of the output. + */ + public static class Audio { + @JsonProperty("url") + private final String url; + + @JsonProperty("data") + private final String data; + + @JsonCreator + public Audio(@JsonProperty("url") String url, @JsonProperty("data") String data) { + this.url = url; + this.data = data; + } + + public String getUrl() { + return url; + } + + public String getData() { + return data; + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSModel.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSModel.java new file mode 100644 index 000000000..6ea70ae96 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSModel.java @@ -0,0 +1,132 @@ +/* + * 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 + * + * https://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.model.tts; + +import io.agentscope.core.message.AudioBlock; +import reactor.core.publisher.Flux; + +/** + * Interface for real-time TTS models that support streaming input. + * + *

    This interface extends {@link TTSModel} with methods for streaming text input, + * enabling "speak as you generate" functionality. Unlike the base {@link TTSModel} + * which requires complete text upfront, this interface allows pushing text + * incrementally while maintaining context continuity. + * + *

    Key difference from TTSModel: + *

      + *
    • {@link TTSModel}: One-time input, streaming output (e.g., HTTP + SSE)
      • + *
    • {@link RealtimeTTSModel}: Streaming input + streaming output (e.g., WebSocket)
      • + *
    + * + *

    Typical models: + *

      + *
    • {@code qwen3-tts-flash-realtime} - WebSocket real-time model
      • + *
    • {@code cosyvoice-v2} - WebSocket streaming model
      • + *
    + * + *

    Usage Example: + * 

    {@code
+ * RealtimeTTSModel tts = DashScopeRealtimeTTSModel.builder()
+ *     .apiKey(apiKey)
+ *     .modelName("qwen3-tts-flash-realtime")
+ *     .voice("Cherry")
+ *     .build();
+ *
+ * // Start streaming session
+ * tts.startSession();
+ *
+ * // Push text chunks (context maintained for natural prosody)
+ * tts.push("Hello, ").subscribe(audio -> player.play(audio));
+ * tts.push("welcome to ").subscribe(audio -> player.play(audio));
+ * tts.push("AgentScope.").subscribe(audio -> player.play(audio));
+ *
+ * // Finish session and get remaining audio
+ * tts.finish().blockLast();
+ *
+ * // Clean up
+ * tts.close();
+ * }
    + * + * @see TTSModel + * @see DashScopeRealtimeTTSModel + */ +public interface RealtimeTTSModel extends TTSModel { + + /** + * Starts a new streaming session. + * + *

    This typically establishes a WebSocket connection to the TTS service. + * Must be called before {@link #push(String)} or {@link #finish()}. + * + * @throws TTSException if session cannot be started + */ + void startSession(); + + /** + * Pushes text incrementally to the TTS service. + * + *

    Text is buffered and synthesized while maintaining context continuity, + * resulting in natural prosody and intonation across chunks. + * + * @param text the text chunk to synthesize + * @return Flux of AudioBlock containing synthesized audio + */ + Flux push(String text); + + /** + * Signals end of input and flushes remaining audio. + * + *

    Call this when all text has been pushed to receive any remaining + * synthesized audio. + * + * @return Flux of AudioBlock containing remaining audio + */ + Flux finish(); + + /** + * Synthesizes text using streaming and returns audio blocks. + * + *

    This is a convenience method that handles the full session lifecycle + * (start, push, finish) for a single text input. + * + * @param text the complete text to synthesize + * @return Flux of AudioBlock as audio is synthesized + */ + Flux synthesizeStream(String text); + + /** + * Closes the TTS session and releases resources. + * + *

    Should be called when the model is no longer needed to close + * WebSocket connections and clean up resources. + */ + void close(); + + /** + * Gets the audio stream for receiving synthesized audio. + * + *

    This method returns a Flux that emits audio blocks as they are + * synthesized. Subscribe to this stream once after calling + * {@link #startSession()} to receive audio data. + * + *

    Important: Only subscribe once per session. Multiple + * subscriptions may cause duplicate audio playback. + * + * @return Flux of AudioBlock that emits audio as it's synthesized + */ + Flux getAudioStream(); +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSResponseEvent.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSResponseEvent.java new file mode 100644 index 000000000..3762a9c4d --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/RealtimeTTSResponseEvent.java @@ -0,0 +1,360 @@ +/* + * 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 + * + * https://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.model.tts; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonSubTypes; +import com.fasterxml.jackson.annotation.JsonTypeInfo; + +/** + * Base class for WebSocket response events from DashScope Realtime TTS API. + * + *

    All events received from the DashScope TTS service via WebSocket extend this class. + * Each event has a type for identification. + */ +@JsonTypeInfo( + use = JsonTypeInfo.Id.NAME, + include = JsonTypeInfo.As.PROPERTY, + property = "type", + defaultImpl = RealtimeTTSResponseEvent.UnknownEvent.class) +@JsonSubTypes({ + @JsonSubTypes.Type(value = RealtimeTTSResponseEvent.ErrorEvent.class, name = "error"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.SessionCreatedEvent.class, + name = "session.created"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.SessionUpdatedEvent.class, + name = "session.updated"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.InputTextBufferCommittedEvent.class, + name = "input_text_buffer.committed"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.InputTextBufferClearedEvent.class, + name = "input_text_buffer.cleared"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseCreatedEvent.class, + name = "response.created"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent.class, + name = "response.output_item.added"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseOutputItemDoneEvent.class, + name = "response.output_item.done"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseContentPartAddedEvent.class, + name = "response.content_part.added"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseContentPartDoneEvent.class, + name = "response.content_part.done"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseAudioDeltaEvent.class, + name = "response.audio.delta"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseAudioDoneEvent.class, + name = "response.audio.done"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.ResponseDoneEvent.class, + name = "response.done"), + @JsonSubTypes.Type( + value = RealtimeTTSResponseEvent.SessionFinishedEvent.class, + name = "session.finished") +}) +public abstract class RealtimeTTSResponseEvent { + + @JsonProperty("type") + private final String type; + + protected RealtimeTTSResponseEvent(String type) { + this.type = type; + } + + public String getType() { + return type; + } + + /** + * Error event. + */ + public static class ErrorEvent extends RealtimeTTSResponseEvent { + @JsonProperty("error") + private final Object error; + + @JsonCreator + public ErrorEvent(@JsonProperty("error") Object error) { + super("error"); + this.error = error; + } + + public Object getError() { + return error; + } + } + + /** + * Session created event. + */ + public static class SessionCreatedEvent extends RealtimeTTSResponseEvent { + @JsonProperty("session") + private final SessionInfo session; + + @JsonCreator + public SessionCreatedEvent(@JsonProperty("session") SessionInfo session) { + super("session.created"); + this.session = session; + } + + public SessionInfo getSession() { + return session; + } + + /** Session information. */ + public static class SessionInfo { + @JsonProperty("id") + private final String id; + + @JsonCreator + public SessionInfo(@JsonProperty("id") String id) { + this.id = id; + } + + public String getId() { + return id; + } + } + } + + /** + * Session updated event. + */ + public static class SessionUpdatedEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public SessionUpdatedEvent() { + super("session.updated"); + } + } + + /** + * Input text buffer committed event. + */ + public static class InputTextBufferCommittedEvent extends RealtimeTTSResponseEvent { + @JsonProperty("item_id") + private final String itemId; + + @JsonCreator + public InputTextBufferCommittedEvent(@JsonProperty("item_id") String itemId) { + super("input_text_buffer.committed"); + this.itemId = itemId; + } + + public String getItemId() { + return itemId; + } + } + + /** + * Input text buffer cleared event. + */ + public static class InputTextBufferClearedEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public InputTextBufferClearedEvent() { + super("input_text_buffer.cleared"); + } + } + + /** + * Response created event. + */ + public static class ResponseCreatedEvent extends RealtimeTTSResponseEvent { + @JsonProperty("response") + private final ResponseInfo response; + + @JsonCreator + public ResponseCreatedEvent(@JsonProperty("response") ResponseInfo response) { + super("response.created"); + this.response = response; + } + + public ResponseInfo getResponse() { + return response; + } + + /** Response information. */ + public static class ResponseInfo { + @JsonProperty("id") + private final String id; + + @JsonCreator + public ResponseInfo(@JsonProperty("id") String id) { + this.id = id; + } + + public String getId() { + return id; + } + } + } + + /** + * Response output item added event. + */ + public static class ResponseOutputItemAddedEvent extends RealtimeTTSResponseEvent { + @JsonProperty("item") + private final ItemInfo item; + + @JsonCreator + public ResponseOutputItemAddedEvent(@JsonProperty("item") ItemInfo item) { + super("response.output_item.added"); + this.item = item; + } + + public ItemInfo getItem() { + return item; + } + + /** Item information. */ + public static class ItemInfo { + @JsonProperty("id") + private final String id; + + @JsonCreator + public ItemInfo(@JsonProperty("id") String id) { + this.id = id; + } + + public String getId() { + return id; + } + } + } + + /** + * Response output item done event. + */ + public static class ResponseOutputItemDoneEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public ResponseOutputItemDoneEvent() { + super("response.output_item.done"); + } + } + + /** + * Response content part added event. + */ + public static class ResponseContentPartAddedEvent extends RealtimeTTSResponseEvent { + @JsonProperty("content_part") + private final ContentPartInfo contentPart; + + @JsonCreator + public ResponseContentPartAddedEvent( + @JsonProperty("content_part") ContentPartInfo contentPart) { + super("response.content_part.added"); + this.contentPart = contentPart; + } + + public ContentPartInfo getContentPart() { + return contentPart; + } + + /** Content part information. */ + public static class ContentPartInfo { + @JsonProperty("id") + private final String id; + + @JsonCreator + public ContentPartInfo(@JsonProperty("id") String id) { + this.id = id; + } + + public String getId() { + return id; + } + } + } + + /** + * Response content part done event. + */ + public static class ResponseContentPartDoneEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public ResponseContentPartDoneEvent() { + super("response.content_part.done"); + } + } + + /** + * Response audio delta event (contains audio data). + */ + public static class ResponseAudioDeltaEvent extends RealtimeTTSResponseEvent { + @JsonProperty("delta") + private final String delta; + + @JsonCreator + public ResponseAudioDeltaEvent(@JsonProperty("delta") String delta) { + super("response.audio.delta"); + this.delta = delta; + } + + public String getDelta() { + return delta; + } + } + + /** + * Response audio done event. + */ + public static class ResponseAudioDoneEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public ResponseAudioDoneEvent() { + super("response.audio.done"); + } + } + + /** + * Response done event. + */ + public static class ResponseDoneEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public ResponseDoneEvent() { + super("response.done"); + } + } + + /** + * Session finished event. + */ + public static class SessionFinishedEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public SessionFinishedEvent() { + super("session.finished"); + } + } + + /** + * Unknown event type (fallback for unregistered event types). + * + *

    This class is used as the default implementation when Jackson encounters + * an event type that is not registered in {@code @JsonSubTypes}. This allows + * the code to gracefully handle new event types from the API without throwing + * exceptions. + */ + public static class UnknownEvent extends RealtimeTTSResponseEvent { + @JsonCreator + public UnknownEvent(@JsonProperty("type") String type) { + super(type != null ? type : "unknown"); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/SessionConfig.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/SessionConfig.java new file mode 100644 index 000000000..d55b8362f --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/SessionConfig.java @@ -0,0 +1,127 @@ +/* + * 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 + * + * https://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.model.tts; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Session configuration for DashScope Realtime TTS. + * + *

    This class represents the session configuration sent to the TTS service + * via WebSocket, including voice settings, format, and mode. + */ +public class SessionConfig { + + @JsonProperty("mode") + private final String mode; + + @JsonProperty("voice") + private final String voice; + + @JsonProperty("language_type") + private final String languageType; + + @JsonProperty("response_format") + private final String responseFormat; + + @JsonProperty("sample_rate") + private final int sampleRate; + + @JsonCreator + private SessionConfig( + @JsonProperty("mode") String mode, + @JsonProperty("voice") String voice, + @JsonProperty("language_type") String languageType, + @JsonProperty("response_format") String responseFormat, + @JsonProperty("sample_rate") int sampleRate) { + this.mode = mode; + this.voice = voice; + this.languageType = languageType; + this.responseFormat = responseFormat; + this.sampleRate = sampleRate; + } + + private SessionConfig(Builder builder) { + this( + builder.mode, + builder.voice, + builder.languageType, + builder.responseFormat, + builder.sampleRate); + } + + public String getMode() { + return mode; + } + + public String getVoice() { + return voice; + } + + public String getLanguageType() { + return languageType; + } + + public String getResponseFormat() { + return responseFormat; + } + + public int getSampleRate() { + return sampleRate; + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private String mode; + private String voice; + private String languageType; + private String responseFormat; + private int sampleRate; + + public Builder mode(String mode) { + this.mode = mode; + return this; + } + + public Builder voice(String voice) { + this.voice = voice; + return this; + } + + public Builder languageType(String languageType) { + this.languageType = languageType; + return this; + } + + public Builder responseFormat(String responseFormat) { + this.responseFormat = responseFormat; + return this; + } + + public Builder sampleRate(int sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + public SessionConfig build() { + return new SessionConfig(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSEvent.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSEvent.java new file mode 100644 index 000000000..27867f949 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSEvent.java @@ -0,0 +1,126 @@ +/* + * 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 + * + * https://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.model.tts; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonSubTypes; +import com.fasterxml.jackson.annotation.JsonTypeInfo; + +/** + * Base class for TTS WebSocket events. + * + *

    All events sent to the DashScope TTS service via WebSocket extend this class. + * Each event has a type and an event_id for tracking. + */ +@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type") +@JsonSubTypes({ + @JsonSubTypes.Type(value = TTSEvent.SessionUpdateEvent.class, name = "session.update"), + @JsonSubTypes.Type(value = TTSEvent.AppendTextEvent.class, name = "input_text_buffer.append"), + @JsonSubTypes.Type(value = TTSEvent.CommitEvent.class, name = "input_text_buffer.commit"), + @JsonSubTypes.Type(value = TTSEvent.ClearEvent.class, name = "input_text_buffer.clear"), + @JsonSubTypes.Type(value = TTSEvent.FinishEvent.class, name = "session.finish") +}) +public abstract class TTSEvent { + + @JsonProperty("type") + private final String type; + + @JsonProperty("event_id") + private final String eventId; + + protected TTSEvent(String type, String eventId) { + this.type = type; + this.eventId = eventId; + } + + public String getType() { + return type; + } + + public String getEventId() { + return eventId; + } + + /** + * Session update event. + */ + public static class SessionUpdateEvent extends TTSEvent { + @JsonProperty("session") + private final SessionConfig session; + + @JsonCreator + public SessionUpdateEvent( + @JsonProperty("event_id") String eventId, + @JsonProperty("session") SessionConfig session) { + super("session.update", eventId); + this.session = session; + } + + public SessionConfig getSession() { + return session; + } + } + + /** + * Append text to input buffer event. + */ + public static class AppendTextEvent extends TTSEvent { + @JsonProperty("text") + private final String text; + + @JsonCreator + public AppendTextEvent( + @JsonProperty("event_id") String eventId, @JsonProperty("text") String text) { + super("input_text_buffer.append", eventId); + this.text = text; + } + + public String getText() { + return text; + } + } + + /** + * Commit text buffer event. + */ + public static class CommitEvent extends TTSEvent { + @JsonCreator + public CommitEvent(@JsonProperty("event_id") String eventId) { + super("input_text_buffer.commit", eventId); + } + } + + /** + * Clear text buffer event. + */ + public static class ClearEvent extends TTSEvent { + @JsonCreator + public ClearEvent(@JsonProperty("event_id") String eventId) { + super("input_text_buffer.clear", eventId); + } + } + + /** + * Session finish event. + */ + public static class FinishEvent extends TTSEvent { + @JsonCreator + public FinishEvent(@JsonProperty("event_id") String eventId) { + super("session.finish", eventId); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSException.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSException.java new file mode 100644 index 000000000..acac1efa7 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSException.java @@ -0,0 +1,114 @@ +/* + * 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 + * + * https://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.model.tts; + +/** + * Exception thrown when TTS operations fail. + * + *

    This exception encapsulates errors that occur during text-to-speech + * synthesis, including API errors, network issues, and invalid configurations. + */ +public class TTSException extends RuntimeException { + + /** HTTP status code (if applicable). */ + private final Integer statusCode; + + /** Error code from the TTS provider. */ + private final String errorCode; + + /** Raw response body (for debugging). */ + private final String responseBody; + + /** + * Creates a new TTSException with a message. + * + * @param message error message + */ + public TTSException(String message) { + super(message); + this.statusCode = null; + this.errorCode = null; + this.responseBody = null; + } + + /** + * Creates a new TTSException with a message and cause. + * + * @param message error message + * @param cause the underlying cause + */ + public TTSException(String message, Throwable cause) { + super(message, cause); + this.statusCode = null; + this.errorCode = null; + this.responseBody = null; + } + + /** + * Creates a new TTSException with HTTP status code. + * + * @param message error message + * @param statusCode HTTP status code + * @param responseBody raw response body + */ + public TTSException(String message, int statusCode, String responseBody) { + super(message); + this.statusCode = statusCode; + this.errorCode = null; + this.responseBody = responseBody; + } + + /** + * Creates a new TTSException with error code. + * + * @param message error message + * @param errorCode error code from provider + * @param responseBody raw response body + */ + public TTSException(String message, String errorCode, String responseBody) { + super(message); + this.statusCode = null; + this.errorCode = errorCode; + this.responseBody = responseBody; + } + + /** + * Gets the HTTP status code. + * + * @return status code, or null if not applicable + */ + public Integer getStatusCode() { + return statusCode; + } + + /** + * Gets the error code from the TTS provider. + * + * @return error code, or null if not available + */ + public String getErrorCode() { + return errorCode; + } + + /** + * Gets the raw response body. + * + * @return response body for debugging + */ + public String getResponseBody() { + return responseBody; + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSModel.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSModel.java new file mode 100644 index 000000000..f4532a44b --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSModel.java @@ -0,0 +1,56 @@ +/* + * 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 + * + * https://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.model.tts; + +import reactor.core.publisher.Mono; + +/** + * Text-to-Speech model interface. + * + *

    This interface defines the contract for TTS models that convert text + * to audio. Implementations may support various TTS providers such as + * DashScope, OpenAI, etc. + * + *

    Example usage: + * 

    {@code
+ * TTSModel tts = DashScopeTTSModel.builder()
+ *     .apiKey("your-api-key")
+ *     .modelName("qwen3-tts-flash")
+ *     .voice("Cherry")
+ *     .build();
+ *
+ * TTSResponse response = tts.synthesize("Hello, world!", null).block();
+ * byte[] audioData = response.getAudioData();
+ * }
    + */ +public interface TTSModel { + + /** + * Synthesize text to audio. + * + * @param text the text to synthesize + * @param options optional TTS options (null to use defaults) + * @return Mono of TTSResponse containing audio data + */ + Mono synthesize(String text, TTSOptions options); + + /** + * Get model name for logging and identification. + * + * @return the model name + */ + String getModelName(); +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSOptions.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSOptions.java new file mode 100644 index 000000000..cc0f60d1b --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSOptions.java @@ -0,0 +1,202 @@ +/* + * 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 + * + * https://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.model.tts; + +/** + * Options for TTS synthesis. + * + *

    This class provides configuration options for text-to-speech synthesis, + * including voice selection, audio format, and speech parameters. + * + *

    Example usage: + * 

    {@code
+ * TTSOptions options = TTSOptions.builder()
+ *     .voice("Cherry")
+ *     .sampleRate(24000)
+ *     .format("wav")
+ *     .speed(1.0f)
+ *     .build();
+ * }
    + */ +public class TTSOptions { + + /** Voice name/ID for synthesis (e.g., "Cherry", "zhimao"). */ + private final String voice; + + /** Audio sample rate in Hz (e.g., 16000, 24000, 48000). */ + private final Integer sampleRate; + + /** Output audio format (e.g., "wav", "mp3", "pcm"). */ + private final String format; + + /** Speech speed/rate multiplier (0.5-2.0, default 1.0). */ + private final Float speed; + + /** Audio volume (0-100, default 50). */ + private final Float volume; + + /** Speech pitch multiplier (0.5-2.0, default 1.0). */ + private final Float pitch; + + /** Language type for synthesis (e.g., "Chinese", "English", "Japanese"). */ + private final String language; + + private TTSOptions(Builder builder) { + this.voice = builder.voice; + this.sampleRate = builder.sampleRate; + this.format = builder.format; + this.speed = builder.speed; + this.volume = builder.volume; + this.pitch = builder.pitch; + this.language = builder.language; + } + + public String getVoice() { + return voice; + } + + public Integer getSampleRate() { + return sampleRate; + } + + public String getFormat() { + return format; + } + + public Float getSpeed() { + return speed; + } + + public Float getVolume() { + return volume; + } + + public Float getPitch() { + return pitch; + } + + public String getLanguage() { + return language; + } + + /** + * Creates a new builder for TTSOptions. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing TTSOptions instances. + */ + public static class Builder { + private String voice; + private Integer sampleRate; + private String format; + private Float speed; + private Float volume; + private Float pitch; + private String language; + + /** + * Sets the voice for synthesis. + * + * @param voice the voice name/ID + * @return this builder + */ + public Builder voice(String voice) { + this.voice = voice; + return this; + } + + /** + * Sets the audio sample rate. + * + * @param sampleRate sample rate in Hz + * @return this builder + */ + public Builder sampleRate(Integer sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + /** + * Sets the output audio format. + * + * @param format audio format (e.g., "wav", "mp3") + * @return this builder + */ + public Builder format(String format) { + this.format = format; + return this; + } + + /** + * Sets the speech speed. + * + * @param speed speed multiplier (0.5-2.0) + * @return this builder + */ + public Builder speed(Float speed) { + this.speed = speed; + return this; + } + + /** + * Sets the audio volume. + * + * @param volume volume level (0-100) + * @return this builder + */ + public Builder volume(Float volume) { + this.volume = volume; + return this; + } + + /** + * Sets the speech pitch. + * + * @param pitch pitch multiplier (0.5-2.0) + * @return this builder + */ + public Builder pitch(Float pitch) { + this.pitch = pitch; + return this; + } + + /** + * Sets the language type. + * + * @param language language code (e.g., "Chinese") + * @return this builder + */ + public Builder language(String language) { + this.language = language; + return this; + } + + /** + * Builds the TTSOptions instance. + * + * @return a new TTSOptions + */ + public TTSOptions build() { + return new TTSOptions(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSResponse.java b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSResponse.java new file mode 100644 index 000000000..0e1494f39 --- /dev/null +++ b/agentscope-core/src/main/java/io/agentscope/core/model/tts/TTSResponse.java @@ -0,0 +1,249 @@ +/* + * 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 + * + * https://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.model.tts; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.message.URLSource; +import java.util.Base64; + +/** + * Response from TTS synthesis. + * + *

    This class encapsulates the result of a text-to-speech synthesis operation, + * including the audio data and metadata about the synthesis. + * + *

    The response can contain either raw audio bytes or a URL to the audio file, + * depending on the TTS provider and configuration. + */ +public class TTSResponse { + + /** Raw audio data bytes. */ + private final byte[] audioData; + + /** URL to the audio file (if provided instead of raw data). */ + private final String audioUrl; + + /** Audio format (e.g., "wav", "mp3"). */ + private final String format; + + /** Audio sample rate in Hz. */ + private final Integer sampleRate; + + /** Audio duration in milliseconds. */ + private final Long durationMs; + + /** Request ID for tracking. */ + private final String requestId; + + private TTSResponse(Builder builder) { + this.audioData = builder.audioData; + this.audioUrl = builder.audioUrl; + this.format = builder.format; + this.sampleRate = builder.sampleRate; + this.durationMs = builder.durationMs; + this.requestId = builder.requestId; + } + + /** + * Gets the raw audio data. + * + * @return audio data bytes, or null if only URL is available + */ + public byte[] getAudioData() { + return audioData; + } + + /** + * Gets the audio URL. + * + * @return URL to audio file, or null if only raw data is available + */ + public String getAudioUrl() { + return audioUrl; + } + + /** + * Gets the audio format. + * + * @return audio format (e.g., "wav", "mp3") + */ + public String getFormat() { + return format; + } + + /** + * Gets the audio sample rate. + * + * @return sample rate in Hz + */ + public Integer getSampleRate() { + return sampleRate; + } + + /** + * Gets the audio duration. + * + * @return duration in milliseconds + */ + public Long getDurationMs() { + return durationMs; + } + + /** + * Gets the request ID. + * + * @return request ID for tracking + */ + public String getRequestId() { + return requestId; + } + + /** + * Converts this response to an AudioBlock for use in Msg. + * + *

    If audio data is available, it will be encoded as Base64. + * If only URL is available, it will be used directly. + * + * @return an AudioBlock containing the audio content + * @throws IllegalStateException if neither audio data nor URL is available + */ + public AudioBlock toAudioBlock() { + if (audioData != null && audioData.length > 0) { + String mediaType = getMediaType(); + String base64Data = Base64.getEncoder().encodeToString(audioData); + return AudioBlock.builder() + .source(Base64Source.builder().mediaType(mediaType).data(base64Data).build()) + .build(); + } else if (audioUrl != null && !audioUrl.isEmpty()) { + return AudioBlock.builder().source(new URLSource(audioUrl)).build(); + } else { + throw new IllegalStateException("No audio data or URL available"); + } + } + + /** + * Gets the MIME type based on the audio format. + */ + private String getMediaType() { + if (format == null) { + return "audio/wav"; + } + return switch (format.toLowerCase()) { + case "mp3" -> "audio/mpeg"; + case "ogg" -> "audio/ogg"; + case "pcm" -> "audio/pcm"; + case "wav" -> "audio/wav"; + default -> "audio/" + format; + }; + } + + /** + * Creates a new builder for TTSResponse. + * + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for constructing TTSResponse instances. + */ + public static class Builder { + private byte[] audioData; + private String audioUrl; + private String format; + private Integer sampleRate; + private Long durationMs; + private String requestId; + + /** + * Sets the raw audio data. + * + * @param audioData audio bytes + * @return this builder + */ + public Builder audioData(byte[] audioData) { + this.audioData = audioData; + return this; + } + + /** + * Sets the audio URL. + * + * @param audioUrl URL to audio file + * @return this builder + */ + public Builder audioUrl(String audioUrl) { + this.audioUrl = audioUrl; + return this; + } + + /** + * Sets the audio format. + * + * @param format audio format + * @return this builder + */ + public Builder format(String format) { + this.format = format; + return this; + } + + /** + * Sets the sample rate. + * + * @param sampleRate sample rate in Hz + * @return this builder + */ + public Builder sampleRate(Integer sampleRate) { + this.sampleRate = sampleRate; + return this; + } + + /** + * Sets the duration. + * + * @param durationMs duration in milliseconds + * @return this builder + */ + public Builder durationMs(Long durationMs) { + this.durationMs = durationMs; + return this; + } + + /** + * Sets the request ID. + * + * @param requestId request ID + * @return this builder + */ + public Builder requestId(String requestId) { + this.requestId = requestId; + return this; + } + + /** + * Builds the TTSResponse instance. + * + * @return a new TTSResponse + */ + public TTSResponse build() { + return new TTSResponse(this); + } + } +} diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalTool.java b/agentscope-core/src/main/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalTool.java index 72afc03d8..45baf84e9 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalTool.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalTool.java @@ -318,9 +318,18 @@ public Mono dashscopeImageToText( /** * Convert the given text to audio. * + *

    Supports two types of TTS models: + *

      + *
    • Qwen TTS models (qwen3-tts-flash, qwen-tts) - uses multimodal-generation API
      • + *
    • Sambert models (sambert-*) - uses speech synthesis SDK
      • + *
    + * * @param text The text to be converted into audio. - * @param model The TTS model to use, e.g., 'sambert-zhinan-v1', 'sambert-zhiqi-v1', 'sambert-zhichu-v1', etc. - * @param sampleRate Sample rate of the audio (e.g., 8000, 16000). + * @param model The TTS model to use. For Qwen TTS: 'qwen3-tts-flash', 'qwen-tts'. + * For Sambert: 'sambert-zhinan-v1', 'sambert-zhiqi-v1', 'sambert-zhichu-v1', etc. + * @param voice Voice name for Qwen TTS models, e.g., 'Cherry', 'Serena'. Ignored for Sambert models. + * @param language Language type for Qwen TTS, e.g., 'Chinese', 'English'. Ignored for Sambert models. + * @param sampleRate Sample rate of the audio (e.g., 16000, 24000, 48000). * @return A ToolResultBlock containing the base64 data of audio or error message. */ @Tool(name = "dashscope_text_to_audio", description = "Convert the given text to audio.") @@ -330,35 +339,232 @@ public Mono dashscopeTextToAudio( @ToolParam( name = "model", description = - "The TTS model to use, e.g., 'sambert-zhinan-v1'," + "The TTS model to use. For Qwen TTS: 'qwen3-tts-flash'," + + " 'qwen-tts'. For Sambert: 'sambert-zhinan-v1'," + " 'sambert-zhiqi-v1', 'sambert-zhichu-v1', etc.", required = false) String model, + @ToolParam( + name = "voice", + description = + "Voice name for Qwen TTS models, e.g., 'Cherry', 'Serena'." + + " Ignored for Sambert models.", + required = false) + String voice, + @ToolParam( + name = "language", + description = + "Language type for Qwen TTS, e.g., 'Chinese', 'English'." + + " Ignored for Sambert models.", + required = false) + String language, @ToolParam( name = "sample_rate", - description = "Sample rate of the audio (e.g., 16000, 48000).", + description = "Sample rate of the audio (e.g., 16000, 24000, 48000).", required = false) Integer sampleRate) { String finalModel = Optional.ofNullable(model) .filter(s -> !s.trim().isEmpty()) - .orElse("sambert-zhichu-v1"); - Integer finalSampleRate = Optional.ofNullable(sampleRate).orElse(16000); + .orElse("qwen3-tts-flash"); + Integer finalSampleRate = Optional.ofNullable(sampleRate).orElse(24000); + + // Check if it's a Qwen TTS model + boolean isQwenTTS = finalModel.startsWith("qwen3-tts") || finalModel.startsWith("qwen-tts"); + log.debug( - "dashscope_text_to_audio called: prompt='{}', model='{}', sampleRate='{}'", + "dashscope_text_to_audio called: text='{}', model='{}', voice='{}', language='{}'," + + " sampleRate='{}', isQwenTTS='{}'", text, finalModel, - finalSampleRate); + voice, + language, + finalSampleRate, + isQwenTTS); + + if (isQwenTTS) { + return synthesizeWithQwenTTS(text, finalModel, voice, language); + } else { + return synthesizeWithSambert(text, finalModel, finalSampleRate); + } + } + + /** + * Synthesizes audio using Qwen TTS models via the multimodal-generation API. + * + *

    This method handles the HTTP communication with DashScope's Qwen TTS endpoint, + * building the request payload with text, voice, and language parameters, then + * parsing the response to extract audio data. + * + *

    The method uses the multimodal-generation API endpoint which differs from + * the standard speech synthesis endpoint used by other models. + * + * @param text the text to synthesize into speech + * @param model the Qwen TTS model name (e.g., "qwen3-tts-flash", "qwen-tts") + * @param voice the voice name for synthesis, defaults to "Cherry" if null/empty + * @param language the language type, defaults to "Chinese" if null/empty + * @return a Mono containing ToolResultBlock with AudioBlock on success, + * or an error ToolResultBlock on failure + */ + private Mono synthesizeWithQwenTTS( + String text, String model, String voice, String language) { + String finalVoice = + Optional.ofNullable(voice).filter(s -> !s.trim().isEmpty()).orElse("Cherry"); + String finalLanguage = + Optional.ofNullable(language).filter(s -> !s.trim().isEmpty()).orElse("Chinese"); + + return Mono.fromCallable( + () -> { + // Build request for Qwen TTS API + Map input = new java.util.HashMap<>(); + input.put("text", text); + input.put("voice", finalVoice); + input.put("language_type", finalLanguage); + + Map request = new java.util.HashMap<>(); + request.put("model", model); + request.put("input", input); + + String requestBody = + io.agentscope.core.util.JsonUtils.getJsonCodec() + .toJson(request); + + // Call DashScope API using Java HttpClient + java.net.http.HttpClient client = + java.net.http.HttpClient.newHttpClient(); + java.net.http.HttpRequest httpRequest = + java.net.http.HttpRequest.newBuilder() + .uri( + URI.create( + "https://dashscope.aliyuncs.com/api/v1/services" + + "/aigc/multimodal-generation/generation")) + .header("Authorization", "Bearer " + this.apiKey) + .header("Content-Type", "application/json") + .header("User-Agent", Version.getUserAgent()) + .POST( + java.net.http.HttpRequest.BodyPublishers + .ofString(requestBody)) + .build(); + + java.net.http.HttpResponse response = + client.send( + httpRequest, + java.net.http.HttpResponse.BodyHandlers.ofString()); + + if (response.statusCode() != 200) { + log.error( + "Qwen TTS API failed: status={}, body={}", + response.statusCode(), + response.body()); + return ToolResultBlock.error( + "TTS API failed: " + response.statusCode()); + } + + return parseQwenTTSResponse(response.body()); + }) + .onErrorResume( + e -> { + log.error( + "Failed to generate audio with Qwen TTS: '{}'", + e.getMessage(), + e); + return Mono.just(ToolResultBlock.error(e.getMessage())); + }); + } + /** + * Parses the Qwen TTS API response and extracts audio data. + * + *

    The response structure from Qwen TTS API is: + * 

    {@code
+     * {
+     *   "request_id": "...",
+     *   "output": {
+     *     "audio": {
+     *       "url": "https://..."  // or "data": "base64..."
+     *     }
+     *   }
+     * }
+     * }
    + * + *

    The method handles two audio formats: + *

      + *
    • URL-based: returns AudioBlock with URLSource
      • + *
    • Base64-encoded: returns AudioBlock with Base64Source
      • + *
    + * + * @param responseBody the raw JSON response body from the API + * @return ToolResultBlock containing AudioBlock on success, + * or an error ToolResultBlock if parsing fails or response contains an error + */ + private ToolResultBlock parseQwenTTSResponse(String responseBody) { + try { + @SuppressWarnings("unchecked") + Map response = + io.agentscope.core.util.JsonUtils.getJsonCodec() + .fromJson(responseBody, Map.class); + + // Check for error + if (response.containsKey("code") && response.get("code") != null) { + String message = + response.containsKey("message") + ? response.get("message").toString() + : "Unknown error"; + log.error("Qwen TTS error: {}", message); + return ToolResultBlock.error(message); + } + + // Extract audio from output + @SuppressWarnings("unchecked") + Map output = (Map) response.get("output"); + if (output == null) { + return ToolResultBlock.error("No output in response"); + } + + @SuppressWarnings("unchecked") + Map audio = (Map) output.get("audio"); + if (audio == null) { + return ToolResultBlock.error("No audio in response"); + } + + // Check for URL or base64 data + if (audio.containsKey("url") && audio.get("url") != null) { + String url = audio.get("url").toString(); + return ToolResultBlock.of( + AudioBlock.builder().source(URLSource.builder().url(url).build()).build()); + } else if (audio.containsKey("data") && audio.get("data") != null) { + String data = audio.get("data").toString(); + return ToolResultBlock.of( + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data(data) + .build()) + .build()); + } else { + return ToolResultBlock.error("No audio data in response"); + } + } catch (Exception e) { + log.error("Failed to parse Qwen TTS response: {}", e.getMessage()); + return ToolResultBlock.error("Failed to parse response: " + e.getMessage()); + } + } + + /** + * Synthesize audio using Sambert models via speech synthesis SDK. + */ + private Mono synthesizeWithSambert( + String text, String model, Integer sampleRate) { return Mono.fromCallable( () -> { SpeechSynthesisParam param = SpeechSynthesisParam.builder() .apiKey(this.apiKey) .text(text) - .model(finalModel) - .sampleRate(finalSampleRate) + .model(model) + .sampleRate(sampleRate) .format(SpeechSynthesisAudioFormat.WAV) .header("user-agent", Version.getUserAgent()) .build(); @@ -383,7 +589,10 @@ public Mono dashscopeTextToAudio( }) .onErrorResume( e -> { - log.error("Failed to generate audio '{}'", e.getMessage(), e); + log.error( + "Failed to generate audio with Sambert: '{}'", + e.getMessage(), + e); return Mono.just(ToolResultBlock.error(e.getMessage())); }); } diff --git a/agentscope-core/src/test/java/io/agentscope/core/hook/TTSHookTest.java b/agentscope-core/src/test/java/io/agentscope/core/hook/TTSHookTest.java new file mode 100644 index 000000000..2bd644ee0 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/hook/TTSHookTest.java @@ -0,0 +1,484 @@ +/* + * 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 + * + * https://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.hook; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +import io.agentscope.core.agent.Agent; +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.message.Msg; +import io.agentscope.core.message.MsgRole; +import io.agentscope.core.message.TextBlock; +import io.agentscope.core.model.GenerateOptions; +import io.agentscope.core.model.tts.AudioPlayer; +import io.agentscope.core.model.tts.DashScopeRealtimeTTSModel; +import java.util.ArrayList; +import java.util.List; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; +import reactor.core.publisher.Flux; + +/** + * Unit tests for TTSHook. + */ +class TTSHookTest { + + private DashScopeRealtimeTTSModel mockTtsModel; + private AudioPlayer mockPlayer; + private Agent mockAgent; + private GenerateOptions mockGenerateOptions; + + @BeforeEach + void setUp() { + mockTtsModel = mock(DashScopeRealtimeTTSModel.class); + mockPlayer = mock(AudioPlayer.class); + mockAgent = mock(Agent.class); + mockGenerateOptions = mock(GenerateOptions.class); + } + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should throw when no TTS model is set") + void shouldThrowWhenNoTtsModelSet() { + assertThrows(IllegalArgumentException.class, () -> TTSHook.builder().build()); + } + + @Test + @DisplayName("should build with TTS model only") + void shouldBuildWithTtsModelOnly() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).build(); + + assertNotNull(hook); + } + + @Test + @DisplayName("should build with all options") + void shouldBuildWithAllOptions() { + List receivedAudio = new ArrayList<>(); + + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .audioPlayer(mockPlayer) + .autoStartPlayer(false) + .realtimeMode(true) + .audioCallback(receivedAudio::add) + .build(); + + assertNotNull(hook); + } + } + + @Nested + @DisplayName("Audio Stream Tests") + class AudioStreamTests { + + @Test + @DisplayName("should provide audio stream") + void shouldProvideAudioStream() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).build(); + + assertNotNull(hook.getAudioStream()); + } + } + + @Nested + @DisplayName("Realtime Mode Tests") + class RealtimeModeTests { + + @Test + @DisplayName("should process reasoning chunk in realtime mode") + void shouldProcessReasoningChunkInRealtimeMode() { + AudioBlock mockAudio = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + when(mockTtsModel.push(any())).thenReturn(Flux.just(mockAudio)); + when(mockTtsModel.getAudioStream()).thenReturn(Flux.empty()); + + // Use audioCallback to avoid creating AudioPlayer in CI environment + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .realtimeMode(true) + .audioCallback(audio -> {}) // Avoid AudioPlayer creation + .build(); + + Msg chunk = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Hello").build()) + .build(); + + ReasoningChunkEvent event = + new ReasoningChunkEvent( + mockAgent, "test-model", mockGenerateOptions, chunk, chunk); + hook.onEvent(event).block(); + + verify(mockTtsModel).startSession(); + verify(mockTtsModel).push("Hello"); + } + + @Test + @DisplayName("should handle empty text in chunk") + void shouldHandleEmptyTextInChunk() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).realtimeMode(true).build(); + + Msg chunk = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("").build()) + .build(); + + ReasoningChunkEvent event = + new ReasoningChunkEvent( + mockAgent, "test-model", mockGenerateOptions, chunk, chunk); + hook.onEvent(event).block(); + + verify(mockTtsModel, never()).startSession(); + verify(mockTtsModel, never()).push(any()); + } + } + + @Nested + @DisplayName("Batch Mode Tests") + class BatchModeTests { + + @Test + @DisplayName("should process complete response in batch mode") + void shouldProcessCompleteResponseInBatchMode() { + AudioBlock mockAudio = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + when(mockTtsModel.synthesizeStream(any())).thenReturn(Flux.just(mockAudio)); + + // Use audioCallback to avoid creating AudioPlayer in CI environment + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .realtimeMode(false) + .audioCallback(audio -> {}) // Avoid AudioPlayer creation + .build(); + + Msg response = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Complete response").build()) + .build(); + + PostReasoningEvent event = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, response); + hook.onEvent(event).block(); + + verify(mockTtsModel).synthesizeStream("Complete response"); + } + } + + @Nested + @DisplayName("Callback Tests") + class CallbackTests { + + @Test + @DisplayName("should invoke audio callback") + void shouldInvokeAudioCallback() { + AudioBlock mockAudio = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + when(mockTtsModel.synthesizeStream(any())).thenReturn(Flux.just(mockAudio)); + + List receivedAudio = new ArrayList<>(); + + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .realtimeMode(false) + .audioCallback(receivedAudio::add) + .build(); + + Msg response = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Test").build()) + .build(); + + PostReasoningEvent event = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, response); + hook.onEvent(event).block(); + + assertEquals(1, receivedAudio.size()); + } + } + + @Nested + @DisplayName("Stop Tests") + class StopTests { + + @Test + @DisplayName("should stop without error when player is null") + void shouldStopWithoutErrorWhenPlayerIsNull() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).build(); + + // Should not throw + hook.stop(); + } + + @Test + @DisplayName("should not stop player if not started") + void shouldNotStopPlayerIfNotStarted() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).audioPlayer(mockPlayer).build(); + + // Player was never started, so stop() should not call audioPlayer.stop() + hook.stop(); + + verify(mockPlayer, never()).stop(); + } + + @Test + @DisplayName("should close TTS model on stop") + void shouldCloseTtsModelOnStop() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).build(); + + hook.stop(); + + verify(mockTtsModel).close(); + } + } + + @Nested + @DisplayName("Realtime Mode Finish Tests") + class RealtimeModeFinishTests { + + @Test + @DisplayName("should call finish on PostReasoningEvent in realtime mode") + void shouldCallFinishOnPostReasoningEventInRealtimeMode() { + AudioBlock mockAudio = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + when(mockTtsModel.push(any())).thenReturn(Flux.just(mockAudio)); + when(mockTtsModel.finish()).thenReturn(Flux.just(mockAudio)); + when(mockTtsModel.getAudioStream()).thenReturn(Flux.empty()); + + // Use audioCallback to avoid creating AudioPlayer in CI environment + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .realtimeMode(true) + .audioCallback(audio -> {}) // Avoid AudioPlayer creation + .build(); + + // First send a chunk to start session + Msg chunk = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Hello").build()) + .build(); + ReasoningChunkEvent chunkEvent = + new ReasoningChunkEvent( + mockAgent, "test-model", mockGenerateOptions, chunk, chunk); + hook.onEvent(chunkEvent).block(); + + // Then send PostReasoningEvent + Msg response = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Complete").build()) + .build(); + PostReasoningEvent postEvent = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, response); + hook.onEvent(postEvent).block(); + + verify(mockTtsModel).finish(); + } + } + + @Nested + @DisplayName("Batch Mode Edge Cases") + class BatchModeEdgeCases { + + @Test + @DisplayName("should handle null message in batch mode") + void shouldHandleNullMessageInBatchMode() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).realtimeMode(false).build(); + + PostReasoningEvent event = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, null); + hook.onEvent(event).block(); + + verify(mockTtsModel, never()).synthesizeStream(any()); + } + + @Test + @DisplayName("should handle empty text in batch mode") + void shouldHandleEmptyTextInBatchMode() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).realtimeMode(false).build(); + + Msg response = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("").build()) + .build(); + + PostReasoningEvent event = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, response); + hook.onEvent(event).block(); + + verify(mockTtsModel, never()).synthesizeStream(any()); + } + } + + @Nested + @DisplayName("Realtime Mode Edge Cases") + class RealtimeModeEdgeCases { + + @Test + @DisplayName("should handle chunk with empty text content") + void shouldHandleChunkWithEmptyTextContent() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).realtimeMode(true).build(); + + // Message with empty text + Msg chunk = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("").build()) + .build(); + + ReasoningChunkEvent event = + new ReasoningChunkEvent( + mockAgent, "test-model", mockGenerateOptions, chunk, chunk); + hook.onEvent(event).block(); + + verify(mockTtsModel, never()).startSession(); + } + + @Test + @DisplayName("should handle chunk with null text content") + void shouldHandleChunkWithNullTextContent() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).realtimeMode(true).build(); + + // Message with no content blocks + Msg chunk = Msg.builder().role(MsgRole.ASSISTANT).build(); + + ReasoningChunkEvent event = + new ReasoningChunkEvent( + mockAgent, "test-model", mockGenerateOptions, chunk, chunk); + hook.onEvent(event).block(); + + verify(mockTtsModel, never()).startSession(); + } + } + + @Nested + @DisplayName("Audio Player Integration") + class AudioPlayerIntegration { + + @Test + @DisplayName("should play audio when player is configured") + void shouldPlayAudioWhenPlayerConfigured() { + AudioBlock mockAudio = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + when(mockTtsModel.synthesizeStream(any())).thenReturn(Flux.just(mockAudio)); + + TTSHook hook = + TTSHook.builder() + .ttsModel(mockTtsModel) + .realtimeMode(false) + .audioPlayer(mockPlayer) + .autoStartPlayer(false) // Disable auto-start + .build(); + + Msg response = + Msg.builder() + .role(MsgRole.ASSISTANT) + .content(TextBlock.builder().text("Test").build()) + .build(); + + PostReasoningEvent event = + new PostReasoningEvent(mockAgent, "test-model", mockGenerateOptions, response); + hook.onEvent(event).block(); + + verify(mockPlayer).play(any(AudioBlock.class)); + } + } + + @Nested + @DisplayName("Other Event Types") + class OtherEventTypes { + + @Test + @DisplayName("should pass through unknown event types") + void shouldPassThroughUnknownEventTypes() { + TTSHook hook = TTSHook.builder().ttsModel(mockTtsModel).build(); + + // Create a PreReasoningEvent (not handled by TTSHook) + Msg msg = + Msg.builder() + .role(MsgRole.USER) + .content(TextBlock.builder().text("User message").build()) + .build(); + PreReasoningEvent event = + new PreReasoningEvent( + mockAgent, "test-model", mockGenerateOptions, java.util.List.of(msg)); + + var result = hook.onEvent(event).block(); + + assertNotNull(result); + assertEquals(event, result); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/AudioPlayerTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/AudioPlayerTest.java new file mode 100644 index 000000000..d3f54a4bb --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/AudioPlayerTest.java @@ -0,0 +1,401 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertNotNull; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.message.URLSource; +import java.util.Base64; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for AudioPlayer. + * + *

    Note: Actual audio playback is not tested as it requires audio hardware. + * These tests focus on builder and basic logic. + */ +class AudioPlayerTest { + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should build with default values") + void shouldBuildWithDefaults() { + AudioPlayer player = AudioPlayer.builder().build(); + + assertNotNull(player); + } + + @Test + @DisplayName("should build with custom values") + void shouldBuildWithCustomValues() { + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(48000) + .sampleSizeInBits(16) + .channels(2) + .signed(true) + .bigEndian(true) + .build(); + + assertNotNull(player); + } + + @Test + @DisplayName("should build with common TTS settings") + void shouldBuildWithCommonTTSSettings() { + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(24000) + .sampleSizeInBits(16) + .channels(1) + .signed(true) + .bigEndian(false) + .build(); + + assertNotNull(player); + } + } + + @Nested + @DisplayName("Play AudioBlock Tests") + class PlayAudioBlockTests { + + @Test + @DisplayName("should handle null audio block") + void shouldHandleNullAudioBlock() { + AudioPlayer player = AudioPlayer.builder().build(); + + // Should not throw + player.play((AudioBlock) null); + } + + @Test + @DisplayName("should handle audio block with valid Base64Source") + void shouldHandleAudioBlockWithValidBase64Source() { + AudioPlayer player = AudioPlayer.builder().build(); + AudioBlock audioBlock = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data("dGVzdA==") + .build()) + .build(); + + // May throw TTSException if no audio hardware available (CI environment) + try { + player.play(audioBlock); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + assertNotNull(e.getMessage()); + } + } + + @Test + @DisplayName("should handle audio block with URL source") + void shouldHandleAudioBlockWithUrlSource() { + AudioPlayer player = AudioPlayer.builder().build(); + AudioBlock audioBlock = + AudioBlock.builder() + .source(new URLSource("https://example.com/audio.wav")) + .build(); + + // URL sources are not supported for direct playback, should not throw + player.play(audioBlock); + } + + @Test + @DisplayName("should handle audio block with empty base64 data") + void shouldHandleAudioBlockWithEmptyBase64Data() { + AudioPlayer player = AudioPlayer.builder().build(); + AudioBlock audioBlock = + AudioBlock.builder() + .source(Base64Source.builder().mediaType("audio/wav").data("").build()) + .build(); + + // Should not throw + player.play(audioBlock); + } + } + + @Nested + @DisplayName("Play Bytes Tests") + class PlayBytesTests { + + @Test + @DisplayName("should handle null bytes") + void shouldHandleNullBytes() { + AudioPlayer player = AudioPlayer.builder().build(); + + // May throw TTSException if no audio hardware available (CI environment) + try { + player.play((byte[]) null); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + assertNotNull(e.getMessage()); + } + } + + @Test + @DisplayName("should handle empty bytes") + void shouldHandleEmptyBytes() { + AudioPlayer player = AudioPlayer.builder().build(); + + // May throw TTSException if no audio hardware available (CI environment) + try { + player.play(new byte[0]); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + assertNotNull(e.getMessage()); + } + } + } + + @Nested + @DisplayName("Interrupt Tests") + class InterruptTests { + + @Test + @DisplayName("should interrupt without error when not started") + void shouldInterruptWithoutErrorWhenNotStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + // Should not throw - interrupt() can be called even when not started + player.interrupt(); + } + + @Test + @DisplayName("should interrupt when started") + void shouldInterruptWhenStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + try { + player.start(); + // If started successfully, interrupt should work + player.interrupt(); + player.stop(); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + // In this case, interrupt() should still not throw + player.interrupt(); + } + } + } + + @Nested + @DisplayName("Stop Tests") + class StopTests { + + @Test + @DisplayName("should stop without error when not started") + void shouldStopWithoutErrorWhenNotStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + // Should not throw + player.stop(); + } + } + + @Nested + @DisplayName("Drain Tests") + class DrainTests { + + @Test + @DisplayName("should drain without error when not started") + void shouldDrainWithoutErrorWhenNotStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + // Should not throw - but will do nothing since not running + player.drain(); + } + } + + @Nested + @DisplayName("Audio Data Decoding Tests") + class AudioDataDecodingTests { + + @Test + @DisplayName("should decode base64 audio data") + void shouldDecodeBase64AudioData() { + byte[] originalData = "test audio data".getBytes(); + String base64Data = Base64.getEncoder().encodeToString(originalData); + + // Verify decoding works correctly + byte[] decoded = Base64.getDecoder().decode(base64Data); + assertNotNull(decoded); + } + } + + @Nested + @DisplayName("Start Tests") + class StartTests { + + @Test + @DisplayName("should start and throw TTSException in CI environment") + void shouldStartAndThrowInCIEnvironment() { + AudioPlayer player = AudioPlayer.builder().build(); + + // In CI without audio hardware, start() throws TTSException + try { + player.start(); + // If we get here, audio hardware is available - that's fine + player.stop(); + } catch (TTSException e) { + // Expected in CI environment + assertNotNull(e.getMessage()); + } + } + } + + @Nested + @DisplayName("PlaySync Tests") + class PlaySyncTests { + + @Test + @DisplayName("should handle playSync with null data") + void shouldHandlePlaySyncWithNullData() { + AudioPlayer player = AudioPlayer.builder().build(); + + // playSync with null should handle gracefully + try { + player.playSync(null); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + assertNotNull(e.getMessage()); + } + } + + @Test + @DisplayName("should handle playSync with empty data") + void shouldHandlePlaySyncWithEmptyData() { + AudioPlayer player = AudioPlayer.builder().build(); + + try { + player.playSync(new byte[0]); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + assertNotNull(e.getMessage()); + } + } + } + + @Nested + @DisplayName("Builder Edge Cases") + class BuilderEdgeCases { + + @Test + @DisplayName("should build with 8-bit sample size") + void shouldBuildWith8BitSampleSize() { + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(8000) + .sampleSizeInBits(8) + .channels(1) + .signed(false) + .bigEndian(false) + .build(); + + assertNotNull(player); + } + + @Test + @DisplayName("should build with stereo channels") + void shouldBuildWithStereoChannels() { + AudioPlayer player = AudioPlayer.builder().channels(2).build(); + + assertNotNull(player); + } + } + + @Nested + @DisplayName("Drain Tests Extended") + class DrainTestsExtended { + + @Test + @DisplayName("should handle drain when started") + void shouldHandleDrainWhenStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + try { + player.start(); + // drain() should work when started + player.drain(); + player.stop(); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + // drain() should still work + player.drain(); + } + } + + @Test + @DisplayName("should handle drain when line is null") + void shouldHandleDrainWhenLineIsNull() { + AudioPlayer player = AudioPlayer.builder().build(); + + // drain() should not throw when line is null + player.drain(); + } + } + + @Nested + @DisplayName("Play Tests Extended") + class PlayTestsExtended { + + @Test + @DisplayName("should handle play when started") + void shouldHandlePlayWhenStarted() { + AudioPlayer player = AudioPlayer.builder().build(); + + try { + player.start(); + byte[] audioData = new byte[] {1, 2, 3, 4}; + player.play(audioData); + player.stop(); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + } + } + + @Test + @DisplayName("should handle play with valid base64 audio block") + void shouldHandlePlayWithValidBase64AudioBlock() { + AudioPlayer player = AudioPlayer.builder().build(); + String base64Data = Base64.getEncoder().encodeToString("test audio".getBytes()); + AudioBlock audioBlock = + AudioBlock.builder() + .source( + Base64Source.builder() + .mediaType("audio/wav") + .data(base64Data) + .build()) + .build(); + + try { + player.play(audioBlock); + } catch (TTSException e) { + // Expected in CI environment without audio hardware + } + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModelTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModelTest.java new file mode 100644 index 000000000..f63d7c7c2 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeRealtimeTTSModelTest.java @@ -0,0 +1,910 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for DashScopeRealtimeTTSModel. + */ +class DashScopeRealtimeTTSModelTest { + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should throw when API key is missing") + void shouldThrowWhenApiKeyMissing() { + assertThrows( + IllegalArgumentException.class, + () -> DashScopeRealtimeTTSModel.builder().modelName("qwen3-tts-flash").build()); + } + + @Test + @DisplayName("should build with default values") + void shouldBuildWithDefaults() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertNotNull(model); + assertEquals("qwen3-tts-flash-realtime", model.getModelName()); + } + + @Test + @DisplayName("should build with custom values") + void shouldBuildWithCustomValues() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .modelName("custom-model") + .voice("Cherry") + .sampleRate(48000) + .format("mp3") + .build(); + + assertNotNull(model); + assertEquals("custom-model", model.getModelName()); + } + } + + @Nested + @DisplayName("Streaming Input Support Tests") + class StreamingInputSupportTests { + + @Test + @DisplayName("should support streaming input") + void shouldSupportStreamingInput() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertTrue(model.supportsStreamingInput()); + } + } + + @Nested + @DisplayName("Session Tests") + class SessionTests { + + @Test + @DisplayName("should start session without error") + void shouldStartSessionWithoutError() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // startSession() may throw TTSException if API key is invalid (expected in unit tests) + // This test verifies the method can be called, actual connection is tested in E2E tests + try { + model.startSession(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle multiple start session calls") + void shouldHandleMultipleStartSessionCalls() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // startSession() may throw TTSException if API key is invalid (expected in unit tests) + // This test verifies idempotent behavior when called multiple times + try { + model.startSession(); + model.startSession(); // Should not throw - idempotent operation + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + } + + @Nested + @DisplayName("Push Tests") + class PushTests { + + @Test + @DisplayName("should handle push without session start") + void shouldHandlePushWithoutSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // push() may throw TTSException if session fails to start (expected in unit tests) + // This test verifies push can be called, actual connection tested in E2E tests + try { + // push should start session automatically (or handle gracefully) + assertNotNull(model.push("test")); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle null text") + void shouldHandleNullText() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw + assertNotNull(model.push(null)); + } + + @Test + @DisplayName("should handle empty text") + void shouldHandleEmptyText() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw + assertNotNull(model.push("")); + } + } + + @Nested + @DisplayName("Finish Tests") + class FinishTests { + + @Test + @DisplayName("should handle finish without session start") + void shouldHandleFinishWithoutSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should return empty flux + assertNotNull(model.finish()); + } + } + + @Nested + @DisplayName("Synthesize Tests") + class SynthesizeTests { + + @Test + @DisplayName("should return Mono for synchronous synthesis") + void shouldReturnMonoForSynchronousSynthesis() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Just verify it returns a Mono, actual network call is E2E test + assertNotNull(model.synthesize("test", null)); + } + } + + @Nested + @DisplayName("SynthesizeStream Tests") + class SynthesizeStreamTests { + + @Test + @DisplayName("should return Flux for streaming synthesis") + void shouldReturnFluxForStreamingSynthesis() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Just verify it returns a Flux, actual network call is E2E test + assertNotNull(model.synthesizeStream("test")); + } + + @Test + @DisplayName("should handle null text in synthesizeStream") + void shouldHandleNullTextInSynthesizeStream() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw + assertNotNull(model.synthesizeStream(null)); + } + + @Test + @DisplayName("should handle empty text in synthesizeStream") + void shouldHandleEmptyTextInSynthesizeStream() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw + assertNotNull(model.synthesizeStream("")); + } + } + + @Nested + @DisplayName("Audio Stream Tests") + class AudioStreamTests { + + @Test + @DisplayName("should provide audio stream") + void shouldProvideAudioStream() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertNotNull(model.getAudioStream()); + } + } + + @Nested + @DisplayName("Session Workflow Tests") + class SessionWorkflowTests { + + @Test + @DisplayName("should handle push then finish workflow") + void shouldHandlePushThenFinishWorkflow() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + + // Push small text + var result1 = model.push("Hi"); + assertNotNull(result1); + + // Finish should flush remaining text + var result2 = model.finish(); + assertNotNull(result2); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle push with sentence end triggers synthesis") + void shouldHandlePushWithSentenceEnd() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + + // Push text with Chinese period + var result = model.push("你好。"); + assertNotNull(result); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle push with various punctuation") + void shouldHandlePushWithVariousPunctuation() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + + // Test various punctuation marks + assertNotNull(model.push("Hello!")); + assertNotNull(model.push("What?")); + assertNotNull(model.push("OK,")); + assertNotNull(model.push("好！")); + assertNotNull(model.push("吗？")); + assertNotNull(model.push("好，")); + assertNotNull(model.push("Line\n")); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle finish after multiple pushes") + void shouldHandleFinishAfterMultiplePushes() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.push("A"); + model.push("B"); + model.push("C"); + + var result = model.finish(); + assertNotNull(result); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle double finish") + void shouldHandleDoubleFinish() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.push("test"); + + model.finish(); + // Second finish should return empty + var result = model.finish(); + assertNotNull(result); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + } + + @Nested + @DisplayName("Builder Method Tests") + class BuilderMethodTests { + + @Test + @DisplayName("should set all builder properties") + void shouldSetAllBuilderProperties() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-key") + .modelName("test-model") + .voice("TestVoice") + .sampleRate(16000) + .format("pcm") + .build(); + + assertNotNull(model); + assertEquals("test-model", model.getModelName()); + } + + @Test + @DisplayName("should throw on empty API key") + void shouldThrowOnEmptyApiKey() { + assertThrows( + IllegalArgumentException.class, + () -> DashScopeRealtimeTTSModel.builder().apiKey("").build()); + } + + @Test + @DisplayName("should set session mode") + void shouldSetSessionMode() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-key") + .mode(DashScopeRealtimeTTSModel.SessionMode.COMMIT) + .build(); + + assertNotNull(model); + } + + @Test + @DisplayName("should set server commit mode by default") + void shouldSetServerCommitModeByDefault() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-key").build(); + + assertNotNull(model); + } + + @Test + @DisplayName("should set language type") + void shouldSetLanguageType() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-key") + .languageType("Chinese") + .build(); + + assertNotNull(model); + } + + @Test + @DisplayName("should set all new builder properties") + void shouldSetAllNewBuilderProperties() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-key") + .modelName("qwen3-tts-flash-realtime") + .voice("Cherry") + .sampleRate(24000) + .format("pcm") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) + .languageType("Auto") + .build(); + + assertNotNull(model); + assertEquals("qwen3-tts-flash-realtime", model.getModelName()); + } + } + + @Nested + @DisplayName("SessionMode Enum Tests") + class SessionModeEnumTests { + + @Test + @DisplayName("should have correct value for SERVER_COMMIT") + void shouldHaveCorrectValueForServerCommit() { + assertEquals( + "server_commit", + DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT.getValue()); + } + + @Test + @DisplayName("should have correct value for COMMIT") + void shouldHaveCorrectValueForCommit() { + assertEquals("commit", DashScopeRealtimeTTSModel.SessionMode.COMMIT.getValue()); + } + } + + @Nested + @DisplayName("Close Tests") + class CloseTests { + + @Test + @DisplayName("should handle close without session start") + void shouldHandleCloseWithoutSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw + model.close(); + } + + @Test + @DisplayName("should handle close after session start") + void shouldHandleCloseAfterSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + // Should not throw + model.close(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + // close() should still work even if session failed to start + model.close(); + } + } + + @Test + @DisplayName("should handle double close") + void shouldHandleDoubleClose() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.close(); + // Second close should not throw + model.close(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + // close() should still work even if session failed to start + model.close(); + model.close(); + } + } + } + + @Nested + @DisplayName("Buffer Operation Tests") + class BufferOperationTests { + + @Test + @DisplayName("should handle commitTextBuffer after session start") + void shouldHandleCommitTextBuffer() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .mode(DashScopeRealtimeTTSModel.SessionMode.COMMIT) + .build(); + + try { + model.startSession(); + model.push("test"); + // Should not throw + model.commitTextBuffer(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + + @Test + @DisplayName("should handle clearTextBuffer after session start") + void shouldHandleClearTextBuffer() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.push("test"); + // Should not throw + model.clearTextBuffer(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key - actual connection tested in E2E + } + } + } + + @Nested + @DisplayName("Wait For Response Tests") + class WaitForResponseTests { + + @Test + @DisplayName("should return true when no response pending") + void shouldReturnTrueWhenNoResponsePending() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertTrue(model.waitForResponseDone(1, java.util.concurrent.TimeUnit.SECONDS)); + } + + @Test + @DisplayName("should return false on timeout") + void shouldReturnFalseOnTimeout() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // When responseDoneFuture is null, should return true immediately + assertTrue(model.waitForResponseDone(1, java.util.concurrent.TimeUnit.SECONDS)); + } + } + + @Nested + @DisplayName("Synthesize Extended Tests") + class SynthesizeExtendedTests { + + @Test + @DisplayName("should handle synthesize with null options") + void shouldHandleSynthesizeWithNullOptions() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // synthesize() may throw TTSException if API key is invalid (expected in unit tests) + try { + assertNotNull(model.synthesize("test", null)); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle synthesize with options") + void shouldHandleSynthesizeWithOptions() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + TTSOptions options = TTSOptions.builder().language("Chinese").build(); + try { + assertNotNull(model.synthesize("test", options)); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Get Audio Stream Tests") + class GetAudioStreamTests { + + @Test + @DisplayName("should return empty flux when no session started") + void shouldReturnEmptyFluxWhenNoSessionStarted() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertNotNull(model.getAudioStream()); + } + } + + @Nested + @DisplayName("Close Tests Extended") + class CloseTestsExtended { + + @Test + @DisplayName("should handle close when connection is null") + void shouldHandleCloseWhenConnectionIsNull() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw even if connection is null + model.close(); + } + + @Test + @DisplayName("should handle close when audioSink is null") + void shouldHandleCloseWhenAudioSinkIsNull() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // Should not throw even if audioSink is null + model.close(); + } + } + + @Nested + @DisplayName("SynthesizeStream Tests Extended") + class SynthesizeStreamTestsExtended { + + @Test + @DisplayName("should return flux for synthesizeStream") + void shouldReturnFluxForSynthesizeStream() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // synthesizeStream() returns a Flux, but may fail due to invalid API key + // This test verifies the method can be called + assertNotNull(model.synthesizeStream("test")); + } + + @Test + @DisplayName("should handle synthesizeStream with long text") + void shouldHandleSynthesizeStreamWithLongText() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + String longText = "This is a long text. ".repeat(100); + try { + assertNotNull(model.synthesizeStream(longText)); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle synthesizeStream with special characters") + void shouldHandleSynthesizeStreamWithSpecialCharacters() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + String specialText = "Hello! 你好？测试，test。"; + try { + assertNotNull(model.synthesizeStream(specialText)); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle synthesizeStream in commit mode") + void shouldHandleSynthesizeStreamInCommitMode() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .mode(DashScopeRealtimeTTSModel.SessionMode.COMMIT) + .build(); + + try { + assertNotNull(model.synthesizeStream("test")); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Start Message Receiver Tests") + class StartMessageReceiverTests { + + @Test + @DisplayName("should handle startMessageReceiver when connection is null") + void shouldHandleStartMessageReceiverWhenConnectionIsNull() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // startSession() creates connection, but if connection is null, + // startMessageReceiver() should handle it gracefully + // This is tested indirectly through startSession() + try { + model.startSession(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Append Text Tests") + class AppendTextTests { + + @Test + @DisplayName("should handle appendText after session start") + void shouldHandleAppendTextAfterSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + // push() calls appendText() internally + model.push("test"); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Update Session Tests") + class UpdateSessionTests { + + @Test + @DisplayName("should update session after start") + void shouldUpdateSessionAfterStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .voice("Cherry") + .sampleRate(24000) + .build(); + + try { + // startSession() calls updateSession() internally + model.startSession(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should update session with custom settings") + void shouldUpdateSessionWithCustomSettings() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .voice("Serena") + .sampleRate(48000) + .format("mp3") + .mode(DashScopeRealtimeTTSModel.SessionMode.COMMIT) + .languageType("Chinese") + .build(); + + try { + model.startSession(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Send Event Tests") + class SendEventTests { + + @Test + @DisplayName("should handle sendEvent after session start") + void shouldHandleSendEventAfterSessionStart() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + // push() calls sendEvent() internally + model.push("test"); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle sendEvent for commitTextBuffer") + void shouldHandleSendEventForCommitTextBuffer() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .mode(DashScopeRealtimeTTSModel.SessionMode.COMMIT) + .build(); + + try { + model.startSession(); + model.push("test"); + // commitTextBuffer() calls sendEvent() internally + model.commitTextBuffer(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle sendEvent for clearTextBuffer") + void shouldHandleSendEventForClearTextBuffer() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.push("test"); + // clearTextBuffer() calls sendEvent() internally + model.clearTextBuffer(); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + } + + @Nested + @DisplayName("Finish Tests Extended") + class FinishTestsExtended { + + @Test + @DisplayName("should handle finish after push") + void shouldHandleFinishAfterPush() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + try { + model.startSession(); + model.push("test"); + var result = model.finish(); + assertNotNull(result); + } catch (TTSException e) { + // Expected in unit tests with invalid API key + } + } + + @Test + @DisplayName("should handle finish returns flux") + void shouldHandleFinishReturnsFlux() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // finish() should return Flux even without session + assertNotNull(model.finish()); + } + } + + @Nested + @DisplayName("Wait For Response Tests Extended") + class WaitForResponseTestsExtended { + + @Test + @DisplayName("should handle waitForResponseDone with very short timeout") + void shouldHandleWaitForResponseDoneWithVeryShortTimeout() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // With null responseDoneFuture, should return true immediately + assertTrue(model.waitForResponseDone(1, java.util.concurrent.TimeUnit.MILLISECONDS)); + } + + @Test + @DisplayName("should handle waitForResponseDone with zero timeout") + void shouldHandleWaitForResponseDoneWithZeroTimeout() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + // With null responseDoneFuture, should return true immediately + assertTrue(model.waitForResponseDone(0, java.util.concurrent.TimeUnit.MILLISECONDS)); + } + } + + @Nested + @DisplayName("Get Model Name Tests") + class GetModelNameTests { + + @Test + @DisplayName("should return default model name") + void shouldReturnDefaultModelName() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder().apiKey("test-api-key").build(); + + assertEquals("qwen3-tts-flash-realtime", model.getModelName()); + } + + @Test + @DisplayName("should return custom model name") + void shouldReturnCustomModelName() { + DashScopeRealtimeTTSModel model = + DashScopeRealtimeTTSModel.builder() + .apiKey("test-api-key") + .modelName("custom-model") + .build(); + + assertEquals("custom-model", model.getModelName()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSModelTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSModelTest.java new file mode 100644 index 000000000..5025cd6d7 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSModelTest.java @@ -0,0 +1,433 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.model.transport.HttpRequest; +import io.agentscope.core.model.transport.HttpResponse; +import io.agentscope.core.model.transport.HttpTransport; +import java.util.Base64; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; +import org.mockito.ArgumentCaptor; + +/** + * Unit tests for DashScopeTTSModel. + */ +class DashScopeTTSModelTest { + + private HttpTransport mockTransport; + + @BeforeEach + void setUp() { + mockTransport = mock(HttpTransport.class); + } + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should throw exception when API key is missing") + void shouldThrowWhenApiKeyMissing() { + assertThrows( + IllegalArgumentException.class, + () -> DashScopeTTSModel.builder().modelName("qwen3-tts-flash").build()); + } + + @Test + @DisplayName("should build with default values") + void shouldBuildWithDefaults() { + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + assertNotNull(model); + assertEquals("qwen3-tts-flash", model.getModelName()); + } + } + + @Nested + @DisplayName("Synthesis Tests") + class SynthesisTests { + + @Test + @DisplayName("should synthesize text with URL response") + void shouldSynthesizeWithUrlResponse() throws Exception { + String responseJson = + """ + { + "request_id": "test-request-id", + "output": { + "audio": { + "url": "https://example.com/audio.wav" + } + } + } + """; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("你好，世界！", null).block(); + + assertNotNull(response); + assertEquals("test-request-id", response.getRequestId()); + assertEquals("https://example.com/audio.wav", response.getAudioUrl()); + } + + @Test + @DisplayName("should synthesize text with base64 audio data") + void shouldSynthesizeWithBase64Response() throws Exception { + byte[] audioBytes = "fake audio data".getBytes(); + String base64Audio = Base64.getEncoder().encodeToString(audioBytes); + + String responseJson = + String.format( + """ + { + "request_id": "test-request-id", + "output": { + "audio": { + "data": "%s" + } + } + } + """, + base64Audio); + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("你好，世界！", null).block(); + + assertNotNull(response); + assertArrayEquals(audioBytes, response.getAudioData()); + } + + @Test + @DisplayName("should place voice and language_type in input section") + void shouldPlaceVoiceAndLanguageInInput() throws Exception { + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()) + .thenReturn( + "{\"request_id\":\"test\",\"output\":{\"audio\":{\"url\":\"http://test\"}}}"); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .voice("Cherry") + .httpTransport(mockTransport) + .build(); + + TTSOptions options = TTSOptions.builder().language("Chinese").build(); + + model.synthesize("测试文本", options).block(); + + ArgumentCaptor requestCaptor = ArgumentCaptor.forClass(HttpRequest.class); + verify(mockTransport).execute(requestCaptor.capture()); + + String requestBody = requestCaptor.getValue().getBody(); + assertTrue( + requestBody.contains("\"voice\":\"Cherry\""), + "voice should be in request body"); + assertTrue( + requestBody.contains("\"language_type\":\"Chinese\""), + "language_type should be in request body"); + assertTrue(requestBody.contains("\"text\":\"测试文本\""), "text should be in request body"); + } + } + + @Nested + @DisplayName("TTSResponse Tests") + class TTSResponseTests { + + @Test + @DisplayName("should convert base64 audio to AudioBlock") + void shouldConvertBase64ToAudioBlock() { + byte[] audioData = "test audio".getBytes(); + + TTSResponse response = TTSResponse.builder().audioData(audioData).format("wav").build(); + + AudioBlock audioBlock = response.toAudioBlock(); + + assertNotNull(audioBlock); + assertNotNull(audioBlock.getSource()); + } + + @Test + @DisplayName("should convert URL to AudioBlock") + void shouldConvertUrlToAudioBlock() { + TTSResponse response = + TTSResponse.builder() + .audioUrl("https://example.com/audio.mp3") + .format("mp3") + .build(); + + AudioBlock audioBlock = response.toAudioBlock(); + + assertNotNull(audioBlock); + assertNotNull(audioBlock.getSource()); + } + + @Test + @DisplayName("should throw when no audio data or URL") + void shouldThrowWhenNoAudioData() { + TTSResponse response = TTSResponse.builder().requestId("test").build(); + + assertThrows(IllegalStateException.class, response::toAudioBlock); + } + } + + @Nested + @DisplayName("Error Handling Tests") + class ErrorHandlingTests { + + @Test + @DisplayName("should handle HTTP error response") + void shouldHandleHttpErrorResponse() throws Exception { + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(false); + when(mockResponse.getStatusCode()).thenReturn(400); + when(mockResponse.getBody()).thenReturn("Bad Request"); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + assertThrows(TTSException.class, () -> model.synthesize("test", null).block()); + } + + @Test + @DisplayName("should handle API error in response") + void shouldHandleApiErrorInResponse() throws Exception { + String responseJson = + """ + { + "code": "InvalidParameter", + "message": "Invalid text parameter" + } + """; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + assertThrows(TTSException.class, () -> model.synthesize("test", null).block()); + } + + @Test + @DisplayName("should handle response with no output") + void shouldHandleResponseWithNoOutput() throws Exception { + String responseJson = "{\"request_id\": \"test-id\"}"; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("test", null).block(); + assertNotNull(response); + } + + @Test + @DisplayName("should handle response with empty audio URL") + void shouldHandleResponseWithEmptyAudioUrl() throws Exception { + String responseJson = + """ + { + "request_id": "test-id", + "output": { + "audio": { + "url": "" + } + } + } + """; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("test", null).block(); + assertNotNull(response); + } + + @Test + @DisplayName("should handle response with null audio data") + void shouldHandleResponseWithNullAudioData() throws Exception { + String responseJson = + """ + { + "request_id": "test-id", + "output": { + "audio": { + "data": null + } + } + } + """; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("test", null).block(); + assertNotNull(response); + } + + @Test + @DisplayName("should handle response with empty audio data") + void shouldHandleResponseWithEmptyAudioData() throws Exception { + String responseJson = + """ + { + "request_id": "test-id", + "output": { + "audio": { + "data": "" + } + } + } + """; + + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn(responseJson); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + TTSResponse response = model.synthesize("test", null).block(); + assertNotNull(response); + } + + @Test + @DisplayName("should handle JSON parsing error") + void shouldHandleJsonParsingError() throws Exception { + HttpResponse mockResponse = mock(HttpResponse.class); + when(mockResponse.isSuccessful()).thenReturn(true); + when(mockResponse.getBody()).thenReturn("invalid json"); + when(mockTransport.execute(any(HttpRequest.class))).thenReturn(mockResponse); + + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .httpTransport(mockTransport) + .build(); + + assertThrows(TTSException.class, () -> model.synthesize("test", null).block()); + } + } + + @Nested + @DisplayName("Builder Tests Extended") + class BuilderTestsExtended { + + @Test + @DisplayName("should build with custom base URL") + void shouldBuildWithCustomBaseUrl() { + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .baseUrl("https://custom.example.com") + .httpTransport(mockTransport) + .build(); + + assertNotNull(model); + } + + @Test + @DisplayName("should build with default options") + void shouldBuildWithDefaultOptions() { + TTSOptions options = TTSOptions.builder().language("Chinese").build(); + DashScopeTTSModel model = + DashScopeTTSModel.builder() + .apiKey("test-api-key") + .defaultOptions(options) + .httpTransport(mockTransport) + .build(); + + assertNotNull(model); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSRequestTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSRequestTest.java new file mode 100644 index 000000000..bae4229d4 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSRequestTest.java @@ -0,0 +1,307 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.agentscope.core.util.JsonUtils; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for DashScopeTTSRequest and its nested classes. + */ +class DashScopeTTSRequestTest { + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should build with all properties") + void shouldBuildWithAllProperties() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder() + .text("Hello, world!") + .voice("Cherry") + .languageType("English") + .build(); + + DashScopeTTSRequest.TTSParameters parameters = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(24000) + .format("wav") + .rate(1.0) + .volume(50) + .pitch(1.0) + .build(); + + DashScopeTTSRequest request = + DashScopeTTSRequest.builder() + .model("qwen3-tts-flash") + .input(input) + .parameters(parameters) + .build(); + + assertEquals("qwen3-tts-flash", request.getModel()); + assertNotNull(request.getInput()); + assertEquals("Hello, world!", request.getInput().getText()); + assertEquals("Cherry", request.getInput().getVoice()); + assertEquals("English", request.getInput().getLanguageType()); + assertNotNull(request.getParameters()); + assertEquals(24000, request.getParameters().getSampleRate()); + assertEquals("wav", request.getParameters().getFormat()); + assertEquals(1.0, request.getParameters().getRate()); + assertEquals(50, request.getParameters().getVolume()); + assertEquals(1.0, request.getParameters().getPitch()); + } + + @Test + @DisplayName("should build with minimal properties") + void shouldBuildWithMinimalProperties() { + DashScopeTTSRequest request = + DashScopeTTSRequest.builder().model("qwen3-tts-flash").build(); + + assertNotNull(request); + assertEquals("qwen3-tts-flash", request.getModel()); + assertNull(request.getInput()); + assertNull(request.getParameters()); + } + } + + @Nested + @DisplayName("TTSInput Tests") + class TTSInputTests { + + @Test + @DisplayName("should build TTSInput with all properties") + void shouldBuildTTSInputWithAllProperties() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder() + .text("测试文本") + .voice("zhimao") + .languageType("Chinese") + .build(); + + assertEquals("测试文本", input.getText()); + assertEquals("zhimao", input.getVoice()); + assertEquals("Chinese", input.getLanguageType()); + } + + @Test + @DisplayName("should build TTSInput with partial properties") + void shouldBuildTTSInputWithPartialProperties() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder().text("Hello").build(); + + assertEquals("Hello", input.getText()); + assertNull(input.getVoice()); + assertNull(input.getLanguageType()); + } + + @Test + @DisplayName("should serialize TTSInput to JSON") + void shouldSerializeTTSInputToJson() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder() + .text("Hello") + .voice("Cherry") + .languageType("English") + .build(); + + String json = JsonUtils.getJsonCodec().toJson(input); + + assertNotNull(json); + assertTrue(json.contains("\"text\":\"Hello\"")); + assertTrue(json.contains("\"voice\":\"Cherry\"")); + assertTrue(json.contains("\"language_type\":\"English\"")); + } + } + + @Nested + @DisplayName("TTSParameters Tests") + class TTSParametersTests { + + @Test + @DisplayName("should build TTSParameters with all properties") + void shouldBuildTTSParametersWithAllProperties() { + DashScopeTTSRequest.TTSParameters params = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(48000) + .format("mp3") + .rate(1.5) + .volume(80) + .pitch(1.2) + .build(); + + assertEquals(48000, params.getSampleRate()); + assertEquals("mp3", params.getFormat()); + assertEquals(1.5, params.getRate()); + assertEquals(80, params.getVolume()); + assertEquals(1.2, params.getPitch()); + } + + @Test + @DisplayName("should build TTSParameters with partial properties") + void shouldBuildTTSParametersWithPartialProperties() { + DashScopeTTSRequest.TTSParameters params = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(16000) + .format("wav") + .build(); + + assertEquals(16000, params.getSampleRate()); + assertEquals("wav", params.getFormat()); + assertNull(params.getRate()); + assertNull(params.getVolume()); + assertNull(params.getPitch()); + } + + @Test + @DisplayName("should serialize TTSParameters to JSON") + void shouldSerializeTTSParametersToJson() { + DashScopeTTSRequest.TTSParameters params = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(24000) + .format("wav") + .rate(1.0) + .volume(50) + .pitch(1.0) + .build(); + + String json = JsonUtils.getJsonCodec().toJson(params); + + assertNotNull(json); + assertTrue(json.contains("\"sample_rate\":24000")); + assertTrue(json.contains("\"format\":\"wav\"")); + assertTrue(json.contains("\"rate\":1.0")); + assertTrue(json.contains("\"volume\":50")); + assertTrue(json.contains("\"pitch\":1.0")); + } + } + + @Nested + @DisplayName("JSON Serialization Tests") + class JsonSerializationTests { + + @Test + @DisplayName("should serialize complete request to JSON") + void shouldSerializeCompleteRequestToJson() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder() + .text("Hello, world!") + .voice("Cherry") + .languageType("English") + .build(); + + DashScopeTTSRequest.TTSParameters parameters = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(24000) + .format("wav") + .rate(1.0) + .volume(50) + .pitch(1.0) + .build(); + + DashScopeTTSRequest request = + DashScopeTTSRequest.builder() + .model("qwen3-tts-flash") + .input(input) + .parameters(parameters) + .build(); + + String json = JsonUtils.getJsonCodec().toJson(request); + + assertNotNull(json); + assertTrue(json.contains("\"model\":\"qwen3-tts-flash\"")); + assertTrue(json.contains("\"input\"")); + assertTrue(json.contains("\"parameters\"")); + } + + @Test + @DisplayName("should exclude null fields from JSON") + void shouldExcludeNullFieldsFromJson() { + DashScopeTTSRequest request = + DashScopeTTSRequest.builder().model("qwen3-tts-flash").build(); + + String json = JsonUtils.getJsonCodec().toJson(request); + + assertNotNull(json); + assertTrue(json.contains("\"model\":\"qwen3-tts-flash\"")); + // null fields should be excluded due to @JsonInclude(NON_NULL) + assertTrue(!json.contains("\"input\"")); + } + + @Test + @DisplayName("should deserialize from JSON") + void shouldDeserializeFromJson() { + String json = + "{\"model\":\"qwen3-tts-flash\"," + + "\"input\":{\"text\":\"Hello\",\"voice\":\"Cherry\",\"language_type\":\"English\"}," + + "\"parameters\":{\"sample_rate\":24000,\"format\":\"wav\",\"rate\":1.0,\"volume\":50,\"pitch\":1.0}}"; + + DashScopeTTSRequest request = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSRequest.class); + + assertNotNull(request); + assertEquals("qwen3-tts-flash", request.getModel()); + assertNotNull(request.getInput()); + assertEquals("Hello", request.getInput().getText()); + assertNotNull(request.getParameters()); + assertEquals(24000, request.getParameters().getSampleRate()); + } + + @Test + @DisplayName("should handle round-trip serialization") + void shouldHandleRoundTripSerialization() { + DashScopeTTSRequest.TTSInput input = + DashScopeTTSRequest.TTSInput.builder() + .text("Test") + .voice("Cherry") + .languageType("English") + .build(); + + DashScopeTTSRequest.TTSParameters parameters = + DashScopeTTSRequest.TTSParameters.builder() + .sampleRate(24000) + .format("wav") + .rate(1.0) + .build(); + + DashScopeTTSRequest original = + DashScopeTTSRequest.builder() + .model("qwen3-tts-flash") + .input(input) + .parameters(parameters) + .build(); + + String json = JsonUtils.getJsonCodec().toJson(original); + DashScopeTTSRequest deserialized = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSRequest.class); + + assertEquals(original.getModel(), deserialized.getModel()); + assertEquals(original.getInput().getText(), deserialized.getInput().getText()); + assertEquals(original.getInput().getVoice(), deserialized.getInput().getVoice()); + assertEquals( + original.getParameters().getSampleRate(), + deserialized.getParameters().getSampleRate()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSResponseTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSResponseTest.java new file mode 100644 index 000000000..5e144b57e --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/DashScopeTTSResponseTest.java @@ -0,0 +1,176 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; + +import io.agentscope.core.util.JsonUtils; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for DashScopeTTSResponse. + */ +class DashScopeTTSResponseTest { + + @Nested + @DisplayName("Deserialization Tests") + class DeserializationTests { + + @Test + @DisplayName("should deserialize response with audio data") + void shouldDeserializeResponseWithAudioData() { + String json = + "{\n" + + " \"request_id\": \"req-123\",\n" + + " \"output\": {\n" + + " \"audio\": {\n" + + " \"data\": \"base64encodedaudio==\"\n" + + " }\n" + + " }\n" + + "}"; + + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(response); + assertEquals("req-123", response.getRequestId()); + assertNull(response.getCode()); + assertNull(response.getMessage()); + assertNotNull(response.getOutput()); + assertNotNull(response.getOutput().getAudio()); + assertEquals("base64encodedaudio==", response.getOutput().getAudio().getData()); + assertNull(response.getOutput().getAudio().getUrl()); + } + + @Test + @DisplayName("should deserialize response with audio URL") + void shouldDeserializeResponseWithAudioUrl() { + String json = + "{\n" + + " \"request_id\": \"req-456\",\n" + + " \"output\": {\n" + + " \"audio\": {\n" + + " \"url\": \"https://example.com/audio.wav\"\n" + + " }\n" + + " }\n" + + "}"; + + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(response); + assertEquals("req-456", response.getRequestId()); + assertNotNull(response.getOutput()); + assertNotNull(response.getOutput().getAudio()); + assertEquals("https://example.com/audio.wav", response.getOutput().getAudio().getUrl()); + assertNull(response.getOutput().getAudio().getData()); + } + + @Test + @DisplayName("should deserialize response with both audio data and URL") + void shouldDeserializeResponseWithBothAudioDataAndUrl() { + String json = + "{\n" + + " \"request_id\": \"req-789\",\n" + + " \"output\": {\n" + + " \"audio\": {\n" + + " \"url\": \"https://example.com/audio.wav\",\n" + + " \"data\": \"base64encodedaudio==\"\n" + + " }\n" + + " }\n" + + "}"; + + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(response); + assertEquals("req-789", response.getRequestId()); + assertNotNull(response.getOutput()); + assertNotNull(response.getOutput().getAudio()); + assertEquals("https://example.com/audio.wav", response.getOutput().getAudio().getUrl()); + assertEquals("base64encodedaudio==", response.getOutput().getAudio().getData()); + } + + @Test + @DisplayName("should deserialize error response") + void shouldDeserializeErrorResponse() { + String json = + "{\n" + + " \"code\": \"InvalidApiKey\",\n" + + " \"message\": \"API key is invalid\"\n" + + "}"; + + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(response); + assertEquals("InvalidApiKey", response.getCode()); + assertEquals("API key is invalid", response.getMessage()); + assertNull(response.getRequestId()); + assertNull(response.getOutput()); + } + + @Test + @DisplayName("should deserialize response with null fields") + void shouldDeserializeResponseWithNullFields() { + String json = "{}"; + + DashScopeTTSResponse response = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(response); + assertNull(response.getCode()); + assertNull(response.getMessage()); + assertNull(response.getRequestId()); + assertNull(response.getOutput()); + } + } + + @Nested + @DisplayName("Serialization Tests") + class SerializationTests { + + @Test + @DisplayName("should serialize and deserialize round trip") + void shouldSerializeAndDeserializeRoundTrip() { + DashScopeTTSResponse.Audio audio = + new DashScopeTTSResponse.Audio("https://example.com/audio.wav", "base64data=="); + DashScopeTTSResponse.Output output = new DashScopeTTSResponse.Output(audio); + DashScopeTTSResponse original = new DashScopeTTSResponse(null, null, "req-123", output); + + String json = JsonUtils.getJsonCodec().toJson(original); + assertNotNull(json); + + DashScopeTTSResponse deserialized = + JsonUtils.getJsonCodec().fromJson(json, DashScopeTTSResponse.class); + + assertNotNull(deserialized); + assertEquals(original.getRequestId(), deserialized.getRequestId()); + assertNotNull(deserialized.getOutput()); + assertNotNull(deserialized.getOutput().getAudio()); + assertEquals( + original.getOutput().getAudio().getUrl(), + deserialized.getOutput().getAudio().getUrl()); + assertEquals( + original.getOutput().getAudio().getData(), + deserialized.getOutput().getAudio().getData()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/RealtimeTTSResponseEventTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/RealtimeTTSResponseEventTest.java new file mode 100644 index 000000000..fee7ef076 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/RealtimeTTSResponseEventTest.java @@ -0,0 +1,310 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.agentscope.core.util.JsonUtils; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for RealtimeTTSResponseEvent. + */ +class RealtimeTTSResponseEventTest { + + @Nested + @DisplayName("ErrorEvent Tests") + class ErrorEventTests { + + @Test + @DisplayName("should deserialize error event") + void shouldDeserializeErrorEvent() { + String json = "{\"type\":\"error\",\"error\":\"Invalid API key\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ErrorEvent); + assertEquals("error", event.getType()); + RealtimeTTSResponseEvent.ErrorEvent errorEvent = + (RealtimeTTSResponseEvent.ErrorEvent) event; + assertEquals("Invalid API key", errorEvent.getError().toString()); + } + } + + @Nested + @DisplayName("SessionCreatedEvent Tests") + class SessionCreatedEventTests { + + @Test + @DisplayName("should deserialize session created event") + void shouldDeserializeSessionCreatedEvent() { + String json = "{\"type\":\"session.created\",\"session\":{\"id\":\"session-123\"}}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.SessionCreatedEvent); + assertEquals("session.created", event.getType()); + RealtimeTTSResponseEvent.SessionCreatedEvent sessionEvent = + (RealtimeTTSResponseEvent.SessionCreatedEvent) event; + assertNotNull(sessionEvent.getSession()); + assertEquals("session-123", sessionEvent.getSession().getId()); + } + } + + @Nested + @DisplayName("SessionUpdatedEvent Tests") + class SessionUpdatedEventTests { + + @Test + @DisplayName("should deserialize session updated event") + void shouldDeserializeSessionUpdatedEvent() { + String json = "{\"type\":\"session.updated\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.SessionUpdatedEvent); + assertEquals("session.updated", event.getType()); + } + } + + @Nested + @DisplayName("InputTextBufferCommittedEvent Tests") + class InputTextBufferCommittedEventTests { + + @Test + @DisplayName("should deserialize input text buffer committed event") + void shouldDeserializeInputTextBufferCommittedEvent() { + String json = "{\"type\":\"input_text_buffer.committed\",\"item_id\":\"item-456\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.InputTextBufferCommittedEvent); + assertEquals("input_text_buffer.committed", event.getType()); + RealtimeTTSResponseEvent.InputTextBufferCommittedEvent committedEvent = + (RealtimeTTSResponseEvent.InputTextBufferCommittedEvent) event; + assertEquals("item-456", committedEvent.getItemId()); + } + } + + @Nested + @DisplayName("InputTextBufferClearedEvent Tests") + class InputTextBufferClearedEventTests { + + @Test + @DisplayName("should deserialize input text buffer cleared event") + void shouldDeserializeInputTextBufferClearedEvent() { + String json = "{\"type\":\"input_text_buffer.cleared\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.InputTextBufferClearedEvent); + assertEquals("input_text_buffer.cleared", event.getType()); + } + } + + @Nested + @DisplayName("ResponseCreatedEvent Tests") + class ResponseCreatedEventTests { + + @Test + @DisplayName("should deserialize response created event") + void shouldDeserializeResponseCreatedEvent() { + String json = "{\"type\":\"response.created\",\"response\":{\"id\":\"resp-789\"}}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseCreatedEvent); + assertEquals("response.created", event.getType()); + RealtimeTTSResponseEvent.ResponseCreatedEvent responseEvent = + (RealtimeTTSResponseEvent.ResponseCreatedEvent) event; + assertNotNull(responseEvent.getResponse()); + assertEquals("resp-789", responseEvent.getResponse().getId()); + } + } + + @Nested + @DisplayName("ResponseOutputItemAddedEvent Tests") + class ResponseOutputItemAddedEventTests { + + @Test + @DisplayName("should deserialize response output item added event") + void shouldDeserializeResponseOutputItemAddedEvent() { + String json = + "{\"type\":\"response.output_item.added\",\"item\":{\"id\":\"item-999\"}}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent); + assertEquals("response.output_item.added", event.getType()); + RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent itemEvent = + (RealtimeTTSResponseEvent.ResponseOutputItemAddedEvent) event; + assertNotNull(itemEvent.getItem()); + assertEquals("item-999", itemEvent.getItem().getId()); + } + } + + @Nested + @DisplayName("ResponseOutputItemDoneEvent Tests") + class ResponseOutputItemDoneEventTests { + + @Test + @DisplayName("should deserialize response output item done event") + void shouldDeserializeResponseOutputItemDoneEvent() { + String json = "{\"type\":\"response.output_item.done\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseOutputItemDoneEvent); + assertEquals("response.output_item.done", event.getType()); + } + } + + @Nested + @DisplayName("ResponseContentPartAddedEvent Tests") + class ResponseContentPartAddedEventTests { + + @Test + @DisplayName("should deserialize response content part added event") + void shouldDeserializeResponseContentPartAddedEvent() { + String json = + "{\"type\":\"response.content_part.added\",\"content_part\":{\"id\":\"part-123\"}}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseContentPartAddedEvent); + assertEquals("response.content_part.added", event.getType()); + RealtimeTTSResponseEvent.ResponseContentPartAddedEvent contentPartEvent = + (RealtimeTTSResponseEvent.ResponseContentPartAddedEvent) event; + assertNotNull(contentPartEvent.getContentPart()); + assertEquals("part-123", contentPartEvent.getContentPart().getId()); + } + } + + @Nested + @DisplayName("ResponseContentPartDoneEvent Tests") + class ResponseContentPartDoneEventTests { + + @Test + @DisplayName("should deserialize response content part done event") + void shouldDeserializeResponseContentPartDoneEvent() { + String json = "{\"type\":\"response.content_part.done\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseContentPartDoneEvent); + assertEquals("response.content_part.done", event.getType()); + } + } + + @Nested + @DisplayName("ResponseAudioDeltaEvent Tests") + class ResponseAudioDeltaEventTests { + + @Test + @DisplayName("should deserialize response audio delta event") + void shouldDeserializeResponseAudioDeltaEvent() { + String json = "{\"type\":\"response.audio.delta\",\"delta\":\"base64audio==\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseAudioDeltaEvent); + assertEquals("response.audio.delta", event.getType()); + RealtimeTTSResponseEvent.ResponseAudioDeltaEvent audioEvent = + (RealtimeTTSResponseEvent.ResponseAudioDeltaEvent) event; + assertEquals("base64audio==", audioEvent.getDelta()); + } + } + + @Nested + @DisplayName("ResponseAudioDoneEvent Tests") + class ResponseAudioDoneEventTests { + + @Test + @DisplayName("should deserialize response audio done event") + void shouldDeserializeResponseAudioDoneEvent() { + String json = "{\"type\":\"response.audio.done\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseAudioDoneEvent); + assertEquals("response.audio.done", event.getType()); + } + } + + @Nested + @DisplayName("ResponseDoneEvent Tests") + class ResponseDoneEventTests { + + @Test + @DisplayName("should deserialize response done event") + void shouldDeserializeResponseDoneEvent() { + String json = "{\"type\":\"response.done\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.ResponseDoneEvent); + assertEquals("response.done", event.getType()); + } + } + + @Nested + @DisplayName("SessionFinishedEvent Tests") + class SessionFinishedEventTests { + + @Test + @DisplayName("should deserialize session finished event") + void shouldDeserializeSessionFinishedEvent() { + String json = "{\"type\":\"session.finished\"}"; + + RealtimeTTSResponseEvent event = + JsonUtils.getJsonCodec().fromJson(json, RealtimeTTSResponseEvent.class); + + assertNotNull(event); + assertTrue(event instanceof RealtimeTTSResponseEvent.SessionFinishedEvent); + assertEquals("session.finished", event.getType()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/SessionConfigTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/SessionConfigTest.java new file mode 100644 index 000000000..c788bfcd0 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/SessionConfigTest.java @@ -0,0 +1,158 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.agentscope.core.util.JsonUtils; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for SessionConfig. + */ +class SessionConfigTest { + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should build with all properties") + void shouldBuildWithAllProperties() { + SessionConfig config = + SessionConfig.builder() + .mode("server_commit") + .voice("Cherry") + .languageType("Chinese") + .responseFormat("wav") + .sampleRate(24000) + .build(); + + assertEquals("server_commit", config.getMode()); + assertEquals("Cherry", config.getVoice()); + assertEquals("Chinese", config.getLanguageType()); + assertEquals("wav", config.getResponseFormat()); + assertEquals(24000, config.getSampleRate()); + } + + @Test + @DisplayName("should build with partial properties") + void shouldBuildWithPartialProperties() { + SessionConfig config = + SessionConfig.builder() + .mode("commit") + .voice("Serena") + .sampleRate(16000) + .build(); + + assertEquals("commit", config.getMode()); + assertEquals("Serena", config.getVoice()); + assertEquals(16000, config.getSampleRate()); + // Null values are allowed + } + + @Test + @DisplayName("should build with minimal properties") + void shouldBuildWithMinimalProperties() { + SessionConfig config = SessionConfig.builder().mode("server_commit").build(); + + assertNotNull(config); + assertEquals("server_commit", config.getMode()); + } + + @Test + @DisplayName("builder should return new instance") + void builderShouldReturnNewInstance() { + SessionConfig.Builder builder1 = SessionConfig.builder(); + SessionConfig.Builder builder2 = SessionConfig.builder(); + + assertNotNull(builder1); + assertNotNull(builder2); + } + } + + @Nested + @DisplayName("JSON Serialization Tests") + class JsonSerializationTests { + + @Test + @DisplayName("should serialize to JSON correctly") + void shouldSerializeToJson() { + SessionConfig config = + SessionConfig.builder() + .mode("server_commit") + .voice("Cherry") + .languageType("Chinese") + .responseFormat("wav") + .sampleRate(24000) + .build(); + + String json = JsonUtils.getJsonCodec().toJson(config); + + assertNotNull(json); + // Verify JSON contains expected fields + assertTrue(json.contains("\"mode\":\"server_commit\"")); + assertTrue(json.contains("\"voice\":\"Cherry\"")); + assertTrue(json.contains("\"language_type\":\"Chinese\"")); + assertTrue(json.contains("\"response_format\":\"wav\"")); + assertTrue(json.contains("\"sample_rate\":24000")); + } + + @Test + @DisplayName("should deserialize from JSON correctly") + void shouldDeserializeFromJson() { + String json = + "{\"mode\":\"commit\",\"voice\":\"Serena\",\"language_type\":\"English\"," + + "\"response_format\":\"mp3\",\"sample_rate\":48000}"; + + SessionConfig config = JsonUtils.getJsonCodec().fromJson(json, SessionConfig.class); + + assertNotNull(config); + assertEquals("commit", config.getMode()); + assertEquals("Serena", config.getVoice()); + assertEquals("English", config.getLanguageType()); + assertEquals("mp3", config.getResponseFormat()); + assertEquals(48000, config.getSampleRate()); + } + + @Test + @DisplayName("should handle round-trip serialization") + void shouldHandleRoundTripSerialization() { + SessionConfig original = + SessionConfig.builder() + .mode("server_commit") + .voice("Cherry") + .languageType("Chinese") + .responseFormat("wav") + .sampleRate(24000) + .build(); + + String json = JsonUtils.getJsonCodec().toJson(original); + SessionConfig deserialized = + JsonUtils.getJsonCodec().fromJson(json, SessionConfig.class); + + assertEquals(original.getMode(), deserialized.getMode()); + assertEquals(original.getVoice(), deserialized.getVoice()); + assertEquals(original.getLanguageType(), deserialized.getLanguageType()); + assertEquals(original.getResponseFormat(), deserialized.getResponseFormat()); + assertEquals(original.getSampleRate(), deserialized.getSampleRate()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSEventTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSEventTest.java new file mode 100644 index 000000000..c9779cbb7 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSEventTest.java @@ -0,0 +1,272 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.agentscope.core.util.JsonUtils; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for TTSEvent and its subclasses. + */ +class TTSEventTest { + + @Nested + @DisplayName("SessionUpdateEvent Tests") + class SessionUpdateEventTests { + + @Test + @DisplayName("should create SessionUpdateEvent with session config") + void shouldCreateSessionUpdateEvent() { + SessionConfig sessionConfig = + SessionConfig.builder() + .mode("server_commit") + .voice("Cherry") + .sampleRate(24000) + .build(); + + TTSEvent.SessionUpdateEvent event = + new TTSEvent.SessionUpdateEvent("event-123", sessionConfig); + + assertEquals("session.update", event.getType()); + assertEquals("event-123", event.getEventId()); + assertNotNull(event.getSession()); + assertEquals("server_commit", event.getSession().getMode()); + assertEquals("Cherry", event.getSession().getVoice()); + } + + @Test + @DisplayName("should serialize SessionUpdateEvent to JSON") + void shouldSerializeSessionUpdateEvent() { + SessionConfig sessionConfig = + SessionConfig.builder() + .mode("commit") + .voice("Serena") + .languageType("English") + .responseFormat("wav") + .sampleRate(16000) + .build(); + + TTSEvent.SessionUpdateEvent event = + new TTSEvent.SessionUpdateEvent("event-456", sessionConfig); + + String json = JsonUtils.getJsonCodec().toJson(event); + + assertNotNull(json); + assertTrue(json.contains("\"type\":\"session.update\"")); + assertTrue(json.contains("\"event_id\":\"event-456\"")); + assertTrue(json.contains("\"session\"")); + } + } + + @Nested + @DisplayName("AppendTextEvent Tests") + class AppendTextEventTests { + + @Test + @DisplayName("should create AppendTextEvent with text") + void shouldCreateAppendTextEvent() { + TTSEvent.AppendTextEvent event = + new TTSEvent.AppendTextEvent("event-789", "Hello, world!"); + + assertEquals("input_text_buffer.append", event.getType()); + assertEquals("event-789", event.getEventId()); + assertEquals("Hello, world!", event.getText()); + } + + @Test + @DisplayName("should serialize AppendTextEvent to JSON") + void shouldSerializeAppendTextEvent() { + TTSEvent.AppendTextEvent event = new TTSEvent.AppendTextEvent("event-abc", "Test text"); + + String json = JsonUtils.getJsonCodec().toJson(event); + + assertNotNull(json); + assertTrue(json.contains("\"type\":\"input_text_buffer.append\"")); + assertTrue(json.contains("\"event_id\":\"event-abc\"")); + assertTrue(json.contains("\"text\":\"Test text\"")); + } + + @Test + @DisplayName("should handle empty text") + void shouldHandleEmptyText() { + TTSEvent.AppendTextEvent event = new TTSEvent.AppendTextEvent("event-empty", ""); + + assertEquals("", event.getText()); + } + } + + @Nested + @DisplayName("CommitEvent Tests") + class CommitEventTests { + + @Test + @DisplayName("should create CommitEvent") + void shouldCreateCommitEvent() { + TTSEvent.CommitEvent event = new TTSEvent.CommitEvent("event-commit"); + + assertEquals("input_text_buffer.commit", event.getType()); + assertEquals("event-commit", event.getEventId()); + } + + @Test + @DisplayName("should serialize CommitEvent to JSON") + void shouldSerializeCommitEvent() { + TTSEvent.CommitEvent event = new TTSEvent.CommitEvent("event-xyz"); + + String json = JsonUtils.getJsonCodec().toJson(event); + + assertNotNull(json); + assertTrue(json.contains("\"type\":\"input_text_buffer.commit\"")); + assertTrue(json.contains("\"event_id\":\"event-xyz\"")); + } + } + + @Nested + @DisplayName("ClearEvent Tests") + class ClearEventTests { + + @Test + @DisplayName("should create ClearEvent") + void shouldCreateClearEvent() { + TTSEvent.ClearEvent event = new TTSEvent.ClearEvent("event-clear"); + + assertEquals("input_text_buffer.clear", event.getType()); + assertEquals("event-clear", event.getEventId()); + } + + @Test + @DisplayName("should serialize ClearEvent to JSON") + void shouldSerializeClearEvent() { + TTSEvent.ClearEvent event = new TTSEvent.ClearEvent("event-clear-123"); + + String json = JsonUtils.getJsonCodec().toJson(event); + + assertNotNull(json); + assertTrue(json.contains("\"type\":\"input_text_buffer.clear\"")); + assertTrue(json.contains("\"event_id\":\"event-clear-123\"")); + } + } + + @Nested + @DisplayName("FinishEvent Tests") + class FinishEventTests { + + @Test + @DisplayName("should create FinishEvent") + void shouldCreateFinishEvent() { + TTSEvent.FinishEvent event = new TTSEvent.FinishEvent("event-finish"); + + assertEquals("session.finish", event.getType()); + assertEquals("event-finish", event.getEventId()); + } + + @Test + @DisplayName("should serialize FinishEvent to JSON") + void shouldSerializeFinishEvent() { + TTSEvent.FinishEvent event = new TTSEvent.FinishEvent("event-finish-456"); + + String json = JsonUtils.getJsonCodec().toJson(event); + + assertNotNull(json); + assertTrue(json.contains("\"type\":\"session.finish\"")); + assertTrue(json.contains("\"event_id\":\"event-finish-456\"")); + } + } + + @Nested + @DisplayName("JSON Deserialization Tests") + class JsonDeserializationTests { + + @Test + @DisplayName("should deserialize SessionUpdateEvent from JSON") + void shouldDeserializeSessionUpdateEvent() { + String json = + "{\"type\":\"session.update\",\"event_id\":\"event-123\"," + + "\"session\":{\"mode\":\"server_commit\",\"voice\":\"Cherry\"," + + "\"language_type\":\"Chinese\",\"response_format\":\"wav\",\"sample_rate\":24000}}"; + + TTSEvent event = JsonUtils.getJsonCodec().fromJson(json, TTSEvent.class); + + assertNotNull(event); + assertEquals(TTSEvent.SessionUpdateEvent.class, event.getClass()); + assertEquals("session.update", event.getType()); + assertEquals("event-123", event.getEventId()); + + TTSEvent.SessionUpdateEvent updateEvent = (TTSEvent.SessionUpdateEvent) event; + assertNotNull(updateEvent.getSession()); + assertEquals("server_commit", updateEvent.getSession().getMode()); + } + + @Test + @DisplayName("should deserialize AppendTextEvent from JSON") + void shouldDeserializeAppendTextEvent() { + String json = + "{\"type\":\"input_text_buffer.append\",\"event_id\":\"event-456\"," + + "\"text\":\"Hello, world!\"}"; + + TTSEvent event = JsonUtils.getJsonCodec().fromJson(json, TTSEvent.class); + + assertNotNull(event); + assertEquals(TTSEvent.AppendTextEvent.class, event.getClass()); + assertEquals("input_text_buffer.append", event.getType()); + + TTSEvent.AppendTextEvent appendEvent = (TTSEvent.AppendTextEvent) event; + assertEquals("Hello, world!", appendEvent.getText()); + } + + @Test + @DisplayName("should deserialize CommitEvent from JSON") + void shouldDeserializeCommitEvent() { + String json = "{\"type\":\"input_text_buffer.commit\",\"event_id\":\"event-789\"}"; + + TTSEvent event = JsonUtils.getJsonCodec().fromJson(json, TTSEvent.class); + + assertNotNull(event); + assertEquals(TTSEvent.CommitEvent.class, event.getClass()); + assertEquals("input_text_buffer.commit", event.getType()); + } + + @Test + @DisplayName("should deserialize ClearEvent from JSON") + void shouldDeserializeClearEvent() { + String json = "{\"type\":\"input_text_buffer.clear\",\"event_id\":\"event-clear\"}"; + + TTSEvent event = JsonUtils.getJsonCodec().fromJson(json, TTSEvent.class); + + assertNotNull(event); + assertEquals(TTSEvent.ClearEvent.class, event.getClass()); + assertEquals("input_text_buffer.clear", event.getType()); + } + + @Test + @DisplayName("should deserialize FinishEvent from JSON") + void shouldDeserializeFinishEvent() { + String json = "{\"type\":\"session.finish\",\"event_id\":\"event-finish\"}"; + + TTSEvent event = JsonUtils.getJsonCodec().fromJson(json, TTSEvent.class); + + assertNotNull(event); + assertEquals(TTSEvent.FinishEvent.class, event.getClass()); + assertEquals("session.finish", event.getType()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSExceptionTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSExceptionTest.java new file mode 100644 index 000000000..2f8719bc0 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSExceptionTest.java @@ -0,0 +1,78 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for TTSException. + */ +class TTSExceptionTest { + + @Test + @DisplayName("should create exception with message only") + void shouldCreateWithMessageOnly() { + TTSException ex = new TTSException("Test error"); + + assertEquals("Test error", ex.getMessage()); + assertNull(ex.getStatusCode()); + assertNull(ex.getErrorCode()); + assertNull(ex.getResponseBody()); + assertNull(ex.getCause()); + } + + @Test + @DisplayName("should create exception with message and cause") + void shouldCreateWithMessageAndCause() { + RuntimeException cause = new RuntimeException("root cause"); + TTSException ex = new TTSException("Test error", cause); + + assertEquals("Test error", ex.getMessage()); + assertSame(cause, ex.getCause()); + assertNull(ex.getStatusCode()); + assertNull(ex.getErrorCode()); + assertNull(ex.getResponseBody()); + } + + @Test + @DisplayName("should create exception with HTTP status code") + void shouldCreateWithStatusCode() { + TTSException ex = new TTSException("HTTP error", 500, "{\"error\":\"server error\"}"); + + assertEquals("HTTP error", ex.getMessage()); + assertEquals(500, ex.getStatusCode()); + assertEquals("{\"error\":\"server error\"}", ex.getResponseBody()); + assertNull(ex.getErrorCode()); + } + + @Test + @DisplayName("should create exception with error code") + void shouldCreateWithErrorCode() { + TTSException ex = + new TTSException( + "API error", "InvalidParameter", "{\"code\":\"InvalidParameter\"}"); + + assertEquals("API error", ex.getMessage()); + assertEquals("InvalidParameter", ex.getErrorCode()); + assertEquals("{\"code\":\"InvalidParameter\"}", ex.getResponseBody()); + assertNull(ex.getStatusCode()); + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSOptionsTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSOptionsTest.java new file mode 100644 index 000000000..bf25bf6fd --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSOptionsTest.java @@ -0,0 +1,90 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for TTSOptions. + */ +class TTSOptionsTest { + + @Test + @DisplayName("should build with all options") + void shouldBuildWithAllOptions() { + TTSOptions options = + TTSOptions.builder() + .voice("Cherry") + .sampleRate(24000) + .format("wav") + .speed(1.5f) + .volume(80f) + .pitch(1.2f) + .language("Chinese") + .build(); + + assertEquals("Cherry", options.getVoice()); + assertEquals(24000, options.getSampleRate()); + assertEquals("wav", options.getFormat()); + assertEquals(1.5f, options.getSpeed()); + assertEquals(80f, options.getVolume()); + assertEquals(1.2f, options.getPitch()); + assertEquals("Chinese", options.getLanguage()); + } + + @Test + @DisplayName("should build with default values") + void shouldBuildWithDefaults() { + TTSOptions options = TTSOptions.builder().build(); + + assertNotNull(options); + assertNull(options.getVoice()); + assertNull(options.getSampleRate()); + assertNull(options.getFormat()); + assertNull(options.getSpeed()); + assertNull(options.getVolume()); + assertNull(options.getPitch()); + assertNull(options.getLanguage()); + } + + @Test + @DisplayName("should build with partial options") + void shouldBuildWithPartialOptions() { + TTSOptions options = + TTSOptions.builder().voice("Serena").sampleRate(16000).language("English").build(); + + assertEquals("Serena", options.getVoice()); + assertEquals(16000, options.getSampleRate()); + assertEquals("English", options.getLanguage()); + assertNull(options.getFormat()); + assertNull(options.getSpeed()); + } + + @Test + @DisplayName("builder method should return new instance") + void builderShouldReturnNewInstance() { + TTSOptions.Builder builder1 = TTSOptions.builder(); + TTSOptions.Builder builder2 = TTSOptions.builder(); + + assertNotNull(builder1); + assertNotNull(builder2); + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSResponseTest.java b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSResponseTest.java new file mode 100644 index 000000000..61f0c2a6a --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/model/tts/TTSResponseTest.java @@ -0,0 +1,182 @@ +/* + * 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 + * + * https://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.model.tts; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.message.URLSource; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +/** + * Unit tests for TTSResponse. + */ +class TTSResponseTest { + + @Nested + @DisplayName("Builder Tests") + class BuilderTests { + + @Test + @DisplayName("should build with all properties") + void shouldBuildWithAllProperties() { + byte[] data = "audio".getBytes(); + TTSResponse response = + TTSResponse.builder() + .audioData(data) + .audioUrl("https://example.com/audio.wav") + .format("wav") + .sampleRate(24000) + .durationMs(1000L) + .requestId("req-123") + .build(); + + assertArrayEquals(data, response.getAudioData()); + assertEquals("https://example.com/audio.wav", response.getAudioUrl()); + assertEquals("wav", response.getFormat()); + assertEquals(24000, response.getSampleRate()); + assertEquals(1000L, response.getDurationMs()); + assertEquals("req-123", response.getRequestId()); + } + + @Test + @DisplayName("should build with minimal properties") + void shouldBuildWithMinimalProperties() { + TTSResponse response = TTSResponse.builder().requestId("req-456").build(); + + assertNotNull(response); + assertEquals("req-456", response.getRequestId()); + } + } + + @Nested + @DisplayName("toAudioBlock Tests") + class ToAudioBlockTests { + + @Test + @DisplayName("should convert base64 audio to AudioBlock") + void shouldConvertBase64ToAudioBlock() { + byte[] audioData = "test audio data".getBytes(); + TTSResponse response = TTSResponse.builder().audioData(audioData).format("wav").build(); + + AudioBlock audioBlock = response.toAudioBlock(); + + assertNotNull(audioBlock); + assertNotNull(audioBlock.getSource()); + assertEquals(Base64Source.class, audioBlock.getSource().getClass()); + } + + @Test + @DisplayName("should convert URL to AudioBlock") + void shouldConvertUrlToAudioBlock() { + TTSResponse response = + TTSResponse.builder() + .audioUrl("https://example.com/audio.mp3") + .format("mp3") + .build(); + + AudioBlock audioBlock = response.toAudioBlock(); + + assertNotNull(audioBlock); + assertNotNull(audioBlock.getSource()); + assertEquals(URLSource.class, audioBlock.getSource().getClass()); + } + + @Test + @DisplayName("should throw when no audio data or URL") + void shouldThrowWhenNoAudioData() { + TTSResponse response = TTSResponse.builder().requestId("test").build(); + + assertThrows(IllegalStateException.class, response::toAudioBlock); + } + + @Test + @DisplayName("should prefer audio data over URL") + void shouldPreferAudioDataOverUrl() { + byte[] audioData = "audio bytes".getBytes(); + TTSResponse response = + TTSResponse.builder() + .audioData(audioData) + .audioUrl("https://example.com/audio.wav") + .format("wav") + .build(); + + AudioBlock audioBlock = response.toAudioBlock(); + + assertNotNull(audioBlock); + assertEquals(Base64Source.class, audioBlock.getSource().getClass()); + } + + @Test + @DisplayName("should handle different audio formats") + void shouldHandleDifferentFormats() { + byte[] audioData = "audio".getBytes(); + + // Test MP3 + TTSResponse mp3Response = + TTSResponse.builder().audioData(audioData).format("mp3").build(); + AudioBlock mp3Block = mp3Response.toAudioBlock(); + Base64Source mp3Source = (Base64Source) mp3Block.getSource(); + assertEquals("audio/mpeg", mp3Source.getMediaType()); + + // Test OGG + TTSResponse oggResponse = + TTSResponse.builder().audioData(audioData).format("ogg").build(); + AudioBlock oggBlock = oggResponse.toAudioBlock(); + Base64Source oggSource = (Base64Source) oggBlock.getSource(); + assertEquals("audio/ogg", oggSource.getMediaType()); + + // Test PCM + TTSResponse pcmResponse = + TTSResponse.builder().audioData(audioData).format("pcm").build(); + AudioBlock pcmBlock = pcmResponse.toAudioBlock(); + Base64Source pcmSource = (Base64Source) pcmBlock.getSource(); + assertEquals("audio/pcm", pcmSource.getMediaType()); + + // Test WAV + TTSResponse wavResponse = + TTSResponse.builder().audioData(audioData).format("wav").build(); + AudioBlock wavBlock = wavResponse.toAudioBlock(); + Base64Source wavSource = (Base64Source) wavBlock.getSource(); + assertEquals("audio/wav", wavSource.getMediaType()); + + // Test unknown format + TTSResponse unknownResponse = + TTSResponse.builder().audioData(audioData).format("flac").build(); + AudioBlock unknownBlock = unknownResponse.toAudioBlock(); + Base64Source unknownSource = (Base64Source) unknownBlock.getSource(); + assertEquals("audio/flac", unknownSource.getMediaType()); + } + + @Test + @DisplayName("should default to wav when format is null") + void shouldDefaultToWavWhenFormatNull() { + byte[] audioData = "audio".getBytes(); + TTSResponse response = TTSResponse.builder().audioData(audioData).build(); + + AudioBlock audioBlock = response.toAudioBlock(); + Base64Source source = (Base64Source) audioBlock.getSource(); + + assertEquals("audio/wav", source.getMediaType()); + } + } +} diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolE2ETest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolE2ETest.java index 7e25ea43a..164f19be8 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolE2ETest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolE2ETest.java @@ -194,7 +194,8 @@ void testImageToTextWithUrlAndFile() { @DisplayName("Text to audio") void testTextToAudio() { Mono result = - multiModalTool.dashscopeTextToAudio("hello", "sambert-zhichu-v1", 48000); + multiModalTool.dashscopeTextToAudio( + "hello", "sambert-zhichu-v1", null, null, 48000); StepVerifier.create(result) .assertNext( diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolTest.java index 7f5ad7ba0..2e99db059 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeMultiModalToolTest.java @@ -69,6 +69,7 @@ import java.util.Map; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Test; import org.mockito.MockedConstruction; import org.mockito.MockedStatic; @@ -592,8 +593,8 @@ void testImageToTextError() { } @Test - @DisplayName("Text to audio call success") - void testTextToAudioSuccess() { + @DisplayName("Text to audio with Sambert model - success") + void testTextToAudioWithSambertSuccess() { MockedConstruction mockCtor = Mockito.mockConstruction( SpeechSynthesizer.class, @@ -603,7 +604,8 @@ void testTextToAudioSuccess() { }); Mono result = - multiModalTool.dashscopeTextToAudio("hello", "sambert-zhichu-v1", 48000); + multiModalTool.dashscopeTextToAudio( + "hello", "sambert-zhichu-v1", null, null, 48000); StepVerifier.create(result) .assertNext( @@ -622,6 +624,172 @@ void testTextToAudioSuccess() { mockCtor.close(); } + @Nested + @DisplayName("Qwen TTS Response Parsing Tests") + class QwenTTSResponseParsingTests { + + /** + * Use reflection to call private parseQwenTTSResponse method for unit testing. + */ + private ToolResultBlock invokeParseQwenTTSResponse(String responseBody) throws Exception { + java.lang.reflect.Method method = + DashScopeMultiModalTool.class.getDeclaredMethod( + "parseQwenTTSResponse", String.class); + method.setAccessible(true); + return (ToolResultBlock) method.invoke(multiModalTool, responseBody); + } + + @Test + @DisplayName("Parse Qwen TTS response with URL") + void testParseQwenTTSResponseWithUrl() throws Exception { + String responseJson = + "{\"output\":{\"audio\":{\"url\":\"https://example.com/audio.wav\"}},\"request_id\":\"test-request-id\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof AudioBlock); + AudioBlock audioBlock = (AudioBlock) result.getOutput().get(0); + assertTrue(audioBlock.getSource() instanceof URLSource); + assertEquals( + "https://example.com/audio.wav", ((URLSource) audioBlock.getSource()).getUrl()); + } + + @Test + @DisplayName("Parse Qwen TTS response with Base64 data") + void testParseQwenTTSResponseWithBase64() throws Exception { + String testBase64 = "dGVzdA=="; + String responseJson = + "{\"output\":{\"audio\":{\"data\":\"" + + testBase64 + + "\"}},\"request_id\":\"test-request-id\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof AudioBlock); + AudioBlock audioBlock = (AudioBlock) result.getOutput().get(0); + assertTrue(audioBlock.getSource() instanceof Base64Source); + assertEquals(testBase64, ((Base64Source) audioBlock.getSource()).getData()); + assertEquals("audio/wav", ((Base64Source) audioBlock.getSource()).getMediaType()); + } + + @Test + @DisplayName("Parse Qwen TTS response with error code") + void testParseQwenTTSResponseWithError() throws Exception { + String responseJson = "{\"code\":\"InvalidParameter\",\"message\":\"Invalid request\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue( + ((TextBlock) result.getOutput().get(0)).getText().contains("Invalid request")); + } + + @Test + @DisplayName("Parse Qwen TTS response with missing output") + void testParseQwenTTSResponseMissingOutput() throws Exception { + String responseJson = "{\"request_id\":\"test-request-id\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue( + ((TextBlock) result.getOutput().get(0)) + .getText() + .contains("No output in response")); + } + + @Test + @DisplayName("Parse Qwen TTS response with missing audio") + void testParseQwenTTSResponseMissingAudio() throws Exception { + String responseJson = "{\"output\":{},\"request_id\":\"test-request-id\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue( + ((TextBlock) result.getOutput().get(0)) + .getText() + .contains("No audio in response")); + } + + @Test + @DisplayName("Parse Qwen TTS response with no audio data") + void testParseQwenTTSResponseNoAudioData() throws Exception { + String responseJson = "{\"output\":{\"audio\":{}},\"request_id\":\"test-request-id\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue( + ((TextBlock) result.getOutput().get(0)) + .getText() + .contains("No audio data in response")); + } + + @Test + @DisplayName("Parse Qwen TTS response with invalid JSON") + void testParseQwenTTSResponseInvalidJson() throws Exception { + String responseJson = "invalid json"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue( + ((TextBlock) result.getOutput().get(0)) + .getText() + .contains("Failed to parse response")); + } + + @Test + @DisplayName("Parse Qwen TTS response with error code but no message") + void testParseQwenTTSResponseErrorNoMessage() throws Exception { + String responseJson = "{\"code\":\"InvalidParameter\"}"; + + ToolResultBlock result = invokeParseQwenTTSResponse(responseJson); + + assertNotNull(result); + assertEquals(1, result.getOutput().size()); + assertTrue(result.getOutput().get(0) instanceof TextBlock); + assertTrue(((TextBlock) result.getOutput().get(0)).getText().contains("Unknown error")); + } + } + + @Test + @DisplayName("Text to audio with Qwen TTS model - default model and parameters") + void testTextToAudioWithQwenTTSDefaults() { + // Test that Qwen TTS models are correctly identified + // This tests the model detection logic without requiring HTTP mocking + Mono result = + multiModalTool.dashscopeTextToAudio("hello", null, null, null, null); + + // Will fail with network error, but tests the model selection logic + StepVerifier.create(result) + .assertNext( + toolResultBlock -> { + assertNotNull(toolResultBlock); + // Either success or error, both are valid test outcomes + assertTrue( + toolResultBlock.getOutput().get(0) instanceof AudioBlock + || toolResultBlock.getOutput().get(0) + instanceof TextBlock); + }) + .verifyComplete(); + } + @Test @DisplayName("Should return error TextBlock when call text to audio response empty") void testTextToAudioResponseEmpty() { @@ -634,7 +802,8 @@ void testTextToAudioResponseEmpty() { }); Mono result = - multiModalTool.dashscopeTextToAudio("hello", "sambert-zhichu-v1", 48000); + multiModalTool.dashscopeTextToAudio( + "hello", "sambert-zhichu-v1", null, null, 48000); StepVerifier.create(result) .assertNext( @@ -662,7 +831,8 @@ void testTextToAudioResponseNull() { }); Mono result = - multiModalTool.dashscopeTextToAudio("hello", "sambert-zhichu-v1", 48000); + multiModalTool.dashscopeTextToAudio( + "hello", "sambert-zhichu-v1", null, null, 48000); StepVerifier.create(result) .assertNext( @@ -690,7 +860,8 @@ void testTextToAudioError() { }); Mono result = - multiModalTool.dashscopeTextToAudio("hello", "sambert-zhichu-v1", 48000); + multiModalTool.dashscopeTextToAudio( + "hello", "sambert-zhichu-v1", null, null, 48000); StepVerifier.create(result) .assertNext( diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeTTSE2ETest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeTTSE2ETest.java new file mode 100644 index 000000000..21f0b19e1 --- /dev/null +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/multimodal/DashScopeTTSE2ETest.java @@ -0,0 +1,55 @@ +/* + * 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 + * + * https://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.tool.multimodal; + +import io.agentscope.core.message.ToolResultBlock; + +/** + * E2E test for DashScope TTS. + * + *

    Usage: export DASHSCOPE_API_KEY=sk-xxx && mvn exec:java -pl agentscope-core \ + * -Dexec.mainClass="io.agentscope.core.tool.multimodal.DashScopeTTSE2ETest" + */ +public class DashScopeTTSE2ETest { + + public static void main(String[] args) { + String apiKey = System.getenv("DASHSCOPE_API_KEY"); + if (apiKey == null || apiKey.isEmpty()) { + System.err.println("Please set DASHSCOPE_API_KEY"); + return; + } + + DashScopeMultiModalTool tool = new DashScopeMultiModalTool(apiKey); + + // Test Qwen TTS + System.out.println("=== Testing Qwen TTS (qwen3-tts-flash) ==="); + String text = "你好，欢迎使用语音合成功能。"; + System.out.println("Text: " + text); + + ToolResultBlock result = + tool.dashscopeTextToAudio(text, "qwen3-tts-flash", "Cherry", "Chinese", null) + .block(); + + if (result.getOutput() != null && !result.getOutput().isEmpty()) { + System.out.println("Result: SUCCESS"); + System.out.println("Audio generated successfully!"); + } else { + System.out.println("Result: ERROR - No output"); + } + + System.out.println("\nDone!"); + } +} diff --git a/agentscope-examples/chat-tts/pom.xml b/agentscope-examples/chat-tts/pom.xml new file mode 100644 index 000000000..43d18e032 --- /dev/null +++ b/agentscope-examples/chat-tts/pom.xml @@ -0,0 +1,83 @@ + + + + + 4.0.0 + + io.agentscope + agentscope-examples + ${revision} + ../pom.xml + + + chat-tts + jar + + AgentScope Java - Examples - Chat with TTS + ReActAgent chat with real-time Text-to-Speech streaming to frontend + + + 17 + 17 + UTF-8 + true + + + + + + + org.springframework.boot + spring-boot-dependencies + ${spring.boot.version} + pom + import + + + + + + + io.agentscope + agentscope-core + + + org.springframework.boot + spring-boot-starter-webflux + + + + + + + org.springframework.boot + spring-boot-maven-plugin + ${spring.boot.version} + + + + repackage + + + + + + + + diff --git a/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatController.java b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatController.java new file mode 100644 index 000000000..3cf28c6c2 --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatController.java @@ -0,0 +1,215 @@ +/* + * 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.examples.chattts; + +import io.agentscope.core.ReActAgent; +import io.agentscope.core.agent.EventType; +import io.agentscope.core.agent.StreamOptions; +import io.agentscope.core.hook.TTSHook; +import io.agentscope.core.message.Base64Source; +import io.agentscope.core.message.Msg; +import io.agentscope.core.message.MsgRole; +import io.agentscope.core.message.TextBlock; +import io.agentscope.core.model.DashScopeChatModel; +import io.agentscope.core.model.tts.DashScopeRealtimeTTSModel; +import java.util.Map; +import org.springframework.http.MediaType; +import org.springframework.http.codec.ServerSentEvent; +import org.springframework.web.bind.annotation.CrossOrigin; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; +import reactor.core.publisher.Flux; +import reactor.core.publisher.Sinks; +import reactor.core.scheduler.Schedulers; + +/** + * Chat controller with real-time TTS streaming. + * + *

    Provides SSE endpoint that streams both text and audio to frontend: + *

      + *
    • event: "text" - LLM generated text chunks
      • + *
    • event: "audio" - Base64 encoded audio chunks
      • + *
    • event: "done" - Stream completed
      • + *
    + */ +@RestController +@RequestMapping("/api") +@CrossOrigin(origins = "*") +public class ChatController { + + private final DashScopeChatModel chatModel; + private final String apiKey; + + /** + * Creates a new ChatController. + * + *

    Requires DASHSCOPE_API_KEY environment variable to be set. + * + * @throws IllegalStateException if DASHSCOPE_API_KEY is not set + */ + public ChatController() { + String apiKey = System.getenv("DASHSCOPE_API_KEY"); + if (apiKey == null || apiKey.isEmpty()) { + throw new IllegalStateException("DASHSCOPE_API_KEY environment variable is required"); + } + + this.apiKey = apiKey; + this.chatModel = DashScopeChatModel.builder().apiKey(apiKey).modelName("qwen-plus").build(); + } + + /** + * Chat endpoint with real-time TTS. + * + *

    Returns SSE stream with text and audio events: + * 

    +     * event: text
+     * data: {"text": "你好"}
+     *
+     * event: audio
+     * data: {"audio": "base64..."}
+     *
+     * event: done
+     * data: {"status": "completed"}
+     *
    + * + * @param request containing "message" field + * @return SSE stream of text and audio + */ + @PostMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE) + public Flux>> chat( + @RequestBody Map request) { + String message = request.get("message"); + if (message == null || message.isEmpty()) { + return Flux.just( + ServerSentEvent.>builder() + .event("error") + .data(Map.of("error", "Message is required")) + .build()); + } + + Sinks.Many>> sink = + Sinks.many().multicast().onBackpressureBuffer(); + + // Create a new TTS model instance for this request + // Each request needs its own WebSocket session to avoid audio mixing + DashScopeRealtimeTTSModel requestTtsModel = + DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") // WebSocket realtime model + .voice("Cherry") + .sampleRate(24000) + .format("pcm") + .build(); + + // Create TTSHook that sends audio to frontend via SSE + TTSHook ttsHook = + TTSHook.builder() + .ttsModel(requestTtsModel) + .audioCallback( + audio -> { + if (audio.getSource() instanceof Base64Source src) { + sink.tryEmitNext( + ServerSentEvent.>builder() + .event("audio") + .data(Map.of("audio", src.getData())) + .build()); + } + }) + .build(); + + // Create agent with TTS hook + ReActAgent agent = + ReActAgent.builder() + .name("Assistant") + .sysPrompt("你是一个友好的中文助手。请用简洁的中文回答问题。") + .model(chatModel) + .hook(ttsHook) + .maxIters(3) + .build(); + + // Create user message + Msg userMsg = + Msg.builder() + .name("user") + .role(MsgRole.USER) + .content(TextBlock.builder().text(message).build()) + .build(); + + // Stream agent response + agent.stream( + userMsg, + StreamOptions.builder() + .eventTypes(EventType.REASONING) + .incremental(true) + .build()) + .subscribeOn(Schedulers.boundedElastic()) + .doOnNext( + event -> { + String text = event.getMessage().getTextContent(); + if (text != null && !text.isEmpty()) { + sink.tryEmitNext( + ServerSentEvent.>builder() + .event("text") + .data( + Map.of( + "text", + text, + "isLast", + event.isLast())) + .build()); + } + }) + .doOnComplete( + () -> { + // Stop TTS hook and close WebSocket session for this request + ttsHook.stop(); + requestTtsModel.close(); + + sink.tryEmitNext( + ServerSentEvent.>builder() + .event("done") + .data(Map.of("status", "completed")) + .build()); + sink.tryEmitComplete(); + }) + .doOnError( + e -> { + // Stop TTS hook and close WebSocket session on error + ttsHook.stop(); + requestTtsModel.close(); + + sink.tryEmitNext( + ServerSentEvent.>builder() + .event("error") + .data(Map.of("error", e.getMessage())) + .build()); + sink.tryEmitComplete(); + }) + .subscribe(); + + // Return flux with cleanup on cancel (when client disconnects) + return sink.asFlux() + .doOnCancel( + () -> { + // Clean up when client disconnects or request is cancelled + ttsHook.stop(); + requestTtsModel.close(); + sink.tryEmitComplete(); + }); + } +} diff --git a/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatTTSSpringBootApplication.java b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatTTSSpringBootApplication.java new file mode 100644 index 000000000..ac28078cf --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ChatTTSSpringBootApplication.java @@ -0,0 +1,42 @@ +/* + * 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.examples.chattts; + +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +/** + * Chat with TTS Application. + * + *

    Demonstrates ReActAgent with real-time Text-to-Speech streaming. + * The agent's response text and synthesized audio are streamed to the + * frontend via Server-Sent Events (SSE). + * + *

    Usage: + * 

    + * export DASHSCOPE_API_KEY=sk-xxx
+ * mvn spring-boot:run -pl agentscope-examples/chat-tts
+ *
    + * + *

    Then open http://localhost:8080 in your browser. + */ +@SpringBootApplication +public class ChatTTSSpringBootApplication { + + public static void main(String[] args) { + SpringApplication.run(ChatTTSSpringBootApplication.class, args); + } +} diff --git a/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ReActAgentWithTTSDemo.java b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ReActAgentWithTTSDemo.java new file mode 100644 index 000000000..1dbdbe800 --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/java/io/agentscope/examples/chattts/ReActAgentWithTTSDemo.java @@ -0,0 +1,92 @@ +/* + * 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 + * + * https://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.examples.chattts; + +import io.agentscope.core.ReActAgent; +import io.agentscope.core.agent.user.UserAgent; +import io.agentscope.core.hook.TTSHook; +import io.agentscope.core.message.Msg; +import io.agentscope.core.model.DashScopeChatModel; +import io.agentscope.core.model.tts.DashScopeRealtimeTTSModel; + +/** + * Interactive CLI demo of ReActAgent with real-time TTS. + * + *

    Features: + *

      + *
    • Real-time TTS: Agent speaks while generating response
      • + *
    • Auto-interrupt: When user sends a new message while Agent is speaking, + * the current audio is automatically interrupted and new audio starts
      • + *
    + * + *

    Usage: + * 

    + * export DASHSCOPE_API_KEY=sk-xxx
+ * mvn exec:java -pl agentscope-examples/chat-tts \
+ *   -Dexec.mainClass="io.agentscope.examples.chattts.ReActAgentWithTTSDemo"
+ *
    + */ +public class ReActAgentWithTTSDemo { + + /** + * Main entry point. + * + * @param args command line arguments + */ + public static void main(String[] args) { + String apiKey = System.getenv("DASHSCOPE_API_KEY"); + + // Create TTS model and hook + // Use qwen3-tts-flash-realtime which supports system voices (Cherry, Serena, etc.) + // VD model requires voice design, VC model requires voice cloning + DashScopeRealtimeTTSModel ttsModel = + DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") + .voice("Cherry") + .build(); + + // TTSHook will automatically create a default AudioPlayer if not provided + TTSHook ttsHook = TTSHook.builder().ttsModel(ttsModel).build(); + + // Create agents + ReActAgent agent = + ReActAgent.builder() + .name("Assistant") + .sysPrompt("你是一个友好的中文助手。请用简洁的语言回答问题。") + .model( + DashScopeChatModel.builder() + .apiKey(apiKey) + .modelName("qwen-plus") + .build()) + .hook(ttsHook) + .build(); + + UserAgent user = UserAgent.builder().name("User").build(); + + // Main loop + Msg msg = null; + while (true) { + msg = user.call(msg).block(); + if ("exit".equalsIgnoreCase(msg.getTextContent())) { + break; + } + msg = agent.call(msg).block(); + } + + ttsHook.stop(); + } +} diff --git a/agentscope-examples/chat-tts/src/main/resources/application.yml b/agentscope-examples/chat-tts/src/main/resources/application.yml new file mode 100644 index 000000000..d1e48a900 --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/resources/application.yml @@ -0,0 +1,24 @@ +# 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. + +server: + port: 8080 + +spring: + application: + name: chat-tts + +logging: + level: + io.agentscope: DEBUG diff --git a/agentscope-examples/chat-tts/src/main/resources/logback.xml b/agentscope-examples/chat-tts/src/main/resources/logback.xml new file mode 100644 index 000000000..95ee58ed4 --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/resources/logback.xml @@ -0,0 +1,31 @@ + + + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + + + + + + + diff --git a/agentscope-examples/chat-tts/src/main/resources/static/index.html b/agentscope-examples/chat-tts/src/main/resources/static/index.html new file mode 100644 index 000000000..61c0bb360 --- /dev/null +++ b/agentscope-examples/chat-tts/src/main/resources/static/index.html @@ -0,0 +1,945 @@ + + + + + + + Chat TTS - 边回复边播放 + + + + +
    + +
    + + 边回复边播放 +
    +
    + +
    +
    +
    +
    💬
    +
    开始对话吧
    +
    AI 会一边回复，一边用语音朗读
    +
    +
    + +
    +
    + + + +
    + AI 正在思考... +
    + +
    +
    + + +
    +
    +
    + + + + + + diff --git a/agentscope-examples/pom.xml b/agentscope-examples/pom.xml index 71c31684d..e14e836b6 100644 --- a/agentscope-examples/pom.xml +++ b/agentscope-examples/pom.xml @@ -45,6 +45,7 @@ chat-completions-web hitl-chat a2a + chat-tts diff --git a/agentscope-examples/quickstart/pom.xml b/agentscope-examples/quickstart/pom.xml index ff88c69a2..39f715c1f 100644 --- a/agentscope-examples/quickstart/pom.xml +++ b/agentscope-examples/quickstart/pom.xml @@ -59,6 +59,12 @@ agentscope-core + + + com.alibaba + dashscope-sdk-java + + io.agentscope diff --git a/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/TTSExample.java b/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/TTSExample.java new file mode 100644 index 000000000..f3fec6820 --- /dev/null +++ b/agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/TTSExample.java @@ -0,0 +1,467 @@ +/* + * 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 + * + * https://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.examples.quickstart; + +import io.agentscope.core.ReActAgent; +import io.agentscope.core.hook.TTSHook; +import io.agentscope.core.message.AudioBlock; +import io.agentscope.core.message.ContentBlock; +import io.agentscope.core.message.Msg; +import io.agentscope.core.message.MsgRole; +import io.agentscope.core.message.TextBlock; +import io.agentscope.core.model.DashScopeChatModel; +import io.agentscope.core.model.tts.AudioPlayer; +import io.agentscope.core.model.tts.DashScopeRealtimeTTSModel; +import io.agentscope.core.model.tts.DashScopeTTSModel; +import io.agentscope.core.model.tts.TTSOptions; +import io.agentscope.core.model.tts.TTSResponse; +import io.agentscope.core.tool.Toolkit; +import io.agentscope.core.tool.multimodal.DashScopeMultiModalTool; + +/** + * Example demonstrating all three TTS usage patterns in AgentScope Java. + * + *

    This example covers: + *

      + *
    • Example 1: ReActAgent with realtime TTS - Agent speaks while generating response
      • + *
    • Example 2: Standalone TTSModel - Use TTS independently without Agent
      • + *
    • Example 3: TTS as Agent Tool - Agent decides when to invoke TTS tool
      • + *
    + * + *

    Prerequisites: + *

      + *
    • Set DASHSCOPE_API_KEY environment variable
      • + *
    + * + *

    Usage: + * 

    + * export DASHSCOPE_API_KEY=sk-xxx
+ * mvn exec:java -pl agentscope-examples/quickstart \
+ *   -Dexec.mainClass="io.agentscope.examples.quickstart.TTSExample"
+ *
    + */ +public class TTSExample { + + /** + * Main entry point. + * + * @param args command line arguments + */ + public static void main(String[] args) { + String apiKey = System.getenv("DASHSCOPE_API_KEY"); + if (apiKey == null || apiKey.isEmpty()) { + System.err.println("Please set DASHSCOPE_API_KEY environment variable"); + return; + } + + System.out.println("========================================"); + System.out.println(" AgentScope Java TTS Examples"); + System.out.println("========================================"); + System.out.println(); + + // Example 1: ReActAgent speaks while generating response + realtimeAgentWithTTS(apiKey); + + // Example 2: Use TTSModel independently without Agent + standaloneTTSModel(apiKey); + + // Example 3: Realtime TTS with push/finish pattern (WebSocket streaming) + standaloneRealtimeTTSDemo(apiKey); + + // Example 4: Agent invokes TTS as a tool + agentWithTTSTool(apiKey); + + System.out.println("All examples completed!"); + } + + // ======================================================================== + // Example 1: ReActAgent with Realtime TTS + // ======================================================================== + + /** + * Demonstrates ReActAgent speaking while generating response. + * + *

    Using TTSHook, the Agent synthesizes and plays audio in real-time as it + * generates text. This creates a natural conversational experience where the + * user hears the response as it's being produced. + * + * @param apiKey DashScope API key + */ + private static void realtimeAgentWithTTS(String apiKey) { + System.out.println("=== Example 1: ReActAgent with Realtime TTS ==="); + System.out.println("Agent will speak while generating response..."); + System.out.println(); + + // 1. Create realtime TTS model (WebSocket-based, streaming input + output) + DashScopeRealtimeTTSModel ttsModel = + DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") // WebSocket realtime model + .voice("Cherry") + .sampleRate(24000) + .format("pcm") + .build(); + + // 2. Create audio player for local playback + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(24000) + .sampleSizeInBits(16) + .channels(1) + .signed(true) + .bigEndian(false) + .build(); + + // 3. Create TTSHook with realtime TTS model (WebSocket streaming) + TTSHook ttsHook = TTSHook.builder().ttsModel(ttsModel).audioPlayer(player).build(); + + // 4. Create chat model + DashScopeChatModel chatModel = + DashScopeChatModel.builder().apiKey(apiKey).modelName("qwen-plus").build(); + + // 5. Create agent with TTS hook + ReActAgent agent = + ReActAgent.builder() + .name("Assistant") + .sysPrompt("你是一个友善的助手，请用不多于30字的简洁文字回复") + .model(chatModel) + .hook(ttsHook) + .maxIters(3) + .build(); + + // 6. Call agent - it will speak while generating! + System.out.println("User: 告诉我一个有趣的冷知识"); + System.out.println("Assistant (speaking in real-time): "); + + Msg userMsg = + Msg.builder() + .role(MsgRole.USER) + .content(TextBlock.builder().text("告诉我一个有趣的冷知识").build()) + .build(); + Msg response = agent.call(userMsg).block(); + + if (response != null) { + System.out.println(response.getTextContent()); + } + + // 7. Clean up + try { + Thread.sleep(4000); // Wait for audio to finish + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + ttsHook.stop(); + + System.out.println(); + } + + // ======================================================================== + // Example 2: Standalone TTSModel + // ======================================================================== + + /** + * Demonstrates using TTSModel independently without Agent. + * + *

    Use this when you need text-to-speech synthesis outside of Agent context, + * such as generating audio files, voice notifications, or any scenario where + * you have text and want to convert it to speech directly. + * + * @param apiKey DashScope API key + */ + private static void standaloneTTSModel(String apiKey) { + System.out.println("=== Example 2: Standalone TTSModel ==="); + System.out.println("Using TTSModel directly without Agent..."); + System.out.println(); + + // 2.1 Non-streaming synthesis + System.out.println("--- 2.1 Non-streaming synthesis ---"); + + DashScopeTTSModel ttsModel = + DashScopeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash") + .voice("Cherry") + .build(); + + TTSOptions options = + TTSOptions.builder().sampleRate(24000).format("wav").language("Auto").build(); + + String text = "你好, 欢迎来到 AgentScope Java 的 TTS demo."; + System.out.println("Text: " + text); + + TTSResponse response = ttsModel.synthesize(text, options).block(); + + if (response != null) { + System.out.println("Request ID: " + response.getRequestId()); + if (response.getAudioData() != null) { + System.out.println( + "Audio Data: " + response.getAudioData().length + " bytes, playing..."); + + // Play audio using AudioPlayer + AudioPlayer nonStreamPlayer = + AudioPlayer.builder() + .sampleRate(24000) + .sampleSizeInBits(16) + .channels(1) + .signed(true) + .bigEndian(false) + .build(); + nonStreamPlayer.start(); + nonStreamPlayer.play(response.toAudioBlock()); + nonStreamPlayer.drain(); + try { + Thread.sleep(500); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + nonStreamPlayer.stop(); + System.out.println("Playback completed."); + } else if (response.getAudioUrl() != null) { + System.out.println("Audio URL: " + response.getAudioUrl()); + } + } + + // 2.2 Streaming synthesis + System.out.println(); + System.out.println("--- 2.2 Streaming synthesis ---"); + + DashScopeRealtimeTTSModel realtimeTts = + DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") // WebSocket realtime model + .voice("Cherry") + .sampleRate(24000) + .format("pcm") + .build(); + + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(24000) + .sampleSizeInBits(16) + .channels(1) + .signed(true) + .bigEndian(false) + .build(); + + String longText = "这是一个语音合成流式返回的演示，音频片段会分片到达。"; + System.out.println("Text: " + longText); + System.out.println("Playing streaming audio..."); + + player.start(); + realtimeTts.synthesizeStream(longText).doOnNext(audio -> player.play(audio)).blockLast(); + player.drain(); + + try { + Thread.sleep(500); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + player.stop(); + + System.out.println("Streaming playback completed."); + System.out.println(); + } + + // ======================================================================== + // Example 3: Agent with TTS Tool + // ======================================================================== + + /** + * Demonstrates using TTS as an Agent tool. + * + *

    The Agent is given access to the TTS tool and decides when to invoke it + * based on user requests. This is useful when the Agent should autonomously + * decide whether to respond with audio, such as when the user explicitly asks + * for spoken output. + * + * @param apiKey DashScope API key + */ + private static void agentWithTTSTool(String apiKey) { + System.out.println("=== Example 4: Agent with TTS Tool ==="); + System.out.println("Agent will invoke TTS tool when appropriate..."); + System.out.println(); + + // 1. Create chat model + DashScopeChatModel chatModel = + DashScopeChatModel.builder().apiKey(apiKey).modelName("qwen-plus").build(); + + // 2. Create multimodal tool and register it + DashScopeMultiModalTool multiModalTool = new DashScopeMultiModalTool(apiKey); + Toolkit toolkit = new Toolkit(); + toolkit.registerTool(multiModalTool); + + // 3. Create agent with multimodal toolkit + ReActAgent agent = + ReActAgent.builder() + .name("MultiModalAssistant") + .sysPrompt( + "You are a multimodal assistant. " + + "When user asks you to speak or generate audio, " + + "use the dashscope_text_to_audio tool.") + .model(chatModel) + .toolkit(toolkit) + .maxIters(3) + .build(); + + // 4. Ask agent to generate audio + System.out.println("User: Please say 'Welcome to AgentScope' in audio"); + + Msg userMsg = + Msg.builder() + .role(MsgRole.USER) + .content( + TextBlock.builder() + .text("Please say 'Welcome to AgentScope' in audio") + .build()) + .build(); + Msg response = agent.call(userMsg).block(); + + if (response != null) { + System.out.println("Agent response:"); + + // Extract audio from response + boolean foundAudio = false; + for (ContentBlock block : response.getContent()) { + if (block instanceof TextBlock textBlock) { + System.out.println(" Text: " + textBlock.getText()); + } else if (block instanceof AudioBlock audio) { + foundAudio = true; + System.out.println(" Audio: [AudioBlock generated]"); + System.out.println( + " Source type: " + audio.getSource().getClass().getSimpleName()); + } + } + + if (!foundAudio) { + System.out.println(" (Agent may have responded with text instead of audio)"); + System.out.println(" Full response: " + response.getTextContent()); + } + } + + System.out.println(); + } + + // ======================================================================== + // Example 4: Realtime TTS with Push/Finish Pattern + // ======================================================================== + + /** + * Demonstrates DashScopeRealtimeTTSModel with push/finish pattern. + * + *

    This example shows how to use the WebSocket-based realtime TTS model + * with incremental text input. Key features: + *

      + *
    • startSession() - Establish WebSocket connection
      • + *
    • push(text) - Send text incrementally (context is maintained)
      • + *
    • finish() - Signal end of input, get remaining audio
      • + *
    • getAudioStream() - Subscribe to receive audio as it's generated
      • + *
    + * + *

    This pattern is ideal for: + *

      + *
    • Streaming LLM output to TTS in real-time
      • + *
    • Building voice assistants with low latency
      • + *
    • Scenarios where text arrives incrementally
      • + *
    + * + * @param apiKey DashScope API key + */ + private static void standaloneRealtimeTTSDemo(String apiKey) { + System.out.println("=== Example 3: Realtime TTS with Push/Finish Pattern ==="); + System.out.println("Using WebSocket streaming with incremental text input..."); + System.out.println(); + + // 1. Create realtime TTS model with server_commit mode + // server_commit: Server automatically commits text for synthesis + // commit: Client must manually call commitTextBuffer() + DashScopeRealtimeTTSModel ttsModel = + DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") + .voice("Cherry") + .sampleRate(24000) + .format("pcm") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) + .languageType("Auto") + .build(); + + // 2. Create audio player + AudioPlayer player = + AudioPlayer.builder() + .sampleRate(24000) + .sampleSizeInBits(16) + .channels(1) + .signed(true) + .bigEndian(false) + .build(); + + // 3. Start player + player.start(); + + // 4. Start TTS session (establishes WebSocket connection) + System.out.println("Starting TTS session..."); + ttsModel.startSession(); + + // 5. Subscribe to audio stream BEFORE pushing text + // Audio arrives asynchronously via WebSocket callback + System.out.println("Subscribing to audio stream..."); + ttsModel.getAudioStream() + .doOnNext( + audio -> { + player.play(audio); + }) + .doOnComplete(() -> System.out.println("Audio stream completed.")) + .subscribe(); + + // 6. Push text incrementally (simulating LLM streaming output) + String[] textChunks = {"你好，", "我是", "你的", "语音", "助手，", "很高兴", "为你", "服务！"}; + + System.out.println("Pushing text chunks: "); + for (String chunk : textChunks) { + System.out.print(chunk); + ttsModel.push(chunk); + + // Simulate delay between chunks (like LLM streaming) + try { + Thread.sleep(100); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + System.out.println(); + + // 7. Finish session and wait for all audio to complete + System.out.println("Finishing session, waiting for audio..."); + ttsModel.finish().blockLast(); + + // 8. Drain player to ensure all audio is played + player.drain(); + + // 9. Wait a bit for audio playback to complete + try { + Thread.sleep(1000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + + // 10. Clean up + player.stop(); + ttsModel.close(); + + System.out.println("Push/Finish pattern example completed."); + System.out.println(); + } +} diff --git a/docs/en/task/tts.md b/docs/en/task/tts.md new file mode 100644 index 000000000..8e174248b --- /dev/null +++ b/docs/en/task/tts.md @@ -0,0 +1,203 @@ +# Text-to-Speech (TTS) + +AgentScope Java provides comprehensive TTS capabilities, enabling Agents not only to think and respond, but also to speak. Compared to text-only scenarios, voice is a more natural interaction method, suitable for intelligent customer service, in-car assistants, and real-time conversation scenarios that generate and speak simultaneously. + +## Choosing the Right Model + +**Non-real-time Model**: Suitable for scenarios that require high audio quality and can accept a few seconds of delay, such as podcasts, audiobooks, and short video dubbing. Uses `DashScopeTTSModel` and `qwen3-tts-flash` model, sending complete text at once and waiting for the server to process the entire audio before returning. The model can globally optimize stress, intonation, and emotion for the entire speech, achieving the best audio quality. + +**Real-time Model**: Suitable for scenarios that require high response speed and need to generate and play simultaneously, such as AI assistants and real-time translation. Uses `DashScopeRealtimeTTSModel` and `qwen3-tts-flash-realtime` model, streaming text chunks and the server returns audio chunks in real-time with lower latency. Although synthesized in chunks, the model also maintains a context window to preserve naturalness. + +## Usage Methods + +AgentScope provides three ways to use TTS: + +**ReActAgent Integration**: By adding TTSHook to ReActAgent, you can achieve automatic speech for all Agent responses. Simply adding TTSHook enables the speak-while-generating effect. + +**Standalone TTSModel Usage**: Independent of Agent, directly call TTSModel for standalone speech synthesis, providing flexible usage suitable for scenarios that require separate voice conversion. + +**Using DashScopeMultiModalTool as a Tool**: Provide TTS as a multimodal tool to Agent, allowing Agent to decide when to convert text to speech. + +--- + +## Method 1: ReActAgent Integration + +By adding TTSHook to ReActAgent, ReActAgent can automatically speak when responding. + +**Working Principle**: + +- **Event Listening Mechanism**: TTSHook implements the Hook interface and listens to events during Agent execution. When Agent starts reasoning, it triggers `PreReasoningEvent`, when generating text chunks it triggers `ReasoningChunkEvent`, and when reasoning completes it triggers `PostReasoningEvent`. + +- **Real-time Streaming Synthesis**: In real-time mode, TTSHook listens to `ReasoningChunkEvent`. Whenever Agent generates a text chunk, it immediately pushes it to the TTS model via WebSocket for speech synthesis. This achieves the "speak-while-generating" effect, with users feeling almost no delay. + +- **Session Lifecycle Management**: When receiving the first text chunk, TTSHook starts a TTS session (establishes WebSocket connection) and subscribes to the audio stream. When Agent reasoning completes, it calls `finish()` to commit remaining text and close the session, ensuring all audio is synthesized and played. + +- **Audio Distribution Mechanism**: Generated audio blocks are distributed in three ways: 1) Sent to reactive stream (`audioSink`) for SSE/WebSocket frontend subscription; 2) Call `audioCallback` callback function for custom processing; 3) Play locally via `AudioPlayer`, suitable for CLI/desktop applications. + +- **Playback Interruption Handling**: When new reasoning starts (`PreReasoningEvent`), TTSHook interrupts currently playing audio, closes the old TTS session, ensuring new response audio can start playing immediately, avoiding audio confusion. + +### Local Playback Mode (CLI/Desktop Application) + +Uses WebSocket real-time streaming synthesis, supporting speak-while-generating: + +```java +// 1. Create real-time TTS model (WebSocket streaming) +DashScopeRealtimeTTSModel ttsModel = DashScopeRealtimeTTSModel.builder() + .apiKey(System.getenv("DASHSCOPE_API_KEY")) + .modelName("qwen3-tts-flash-realtime") // WebSocket real-time model + .voice("Cherry") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) // Server auto-commit + .build(); + +// 2. Create TTS Hook +TTSHook ttsHook = TTSHook.builder().ttsModel(ttsModel).build(); + +// 3. Create Agent with TTS +ReActAgent agent = ReActAgent.builder() + .name("Assistant") + .sysPrompt("你是一个友好的助手") + .model(chatModel) + .hook(ttsHook) // Add TTS Hook + .build(); + +// 4. Chat with Agent - Agent will speak while generating response +Msg response = agent.call(Msg.user("你好，今天天气怎么样？")).block(); +``` + +### Server Mode (Web/SSE) + +In web applications, audio needs to be sent to the frontend for playback. You can send audio to the frontend via SSE or use reactive streams. Complete code can be found in the `agentscope-examples/chat-tts` module, which includes frontend and backend interaction. + +--- + +## Method 2: Standalone TTSModel Usage + +Independent of Agent, directly call TTS model for speech synthesis. + +### 2.1 Non-real-time Mode + +Suitable for returning complete audio at once: + +```java +// Create TTS model +DashScopeTTSModel ttsModel = DashScopeTTSModel.builder() + .apiKey(System.getenv("DASHSCOPE_API_KEY")) + .modelName("qwen3-tts-flash") + .build(); + +// Synthesize speech +TTSOptions options = TTSOptions.builder().voice("Cherry").sampleRate(24000).format("wav").build(); + +TTSResponse response = ttsModel.synthesize("你好，欢迎使用语音合成功能！", options).block(); + +// Get audio data +byte[] audioData = response.getAudioData(); +AudioBlock audioBlock = response.toAudioBlock(); +``` + +### 2.2 Real-time Mode - Incremental Input (Push/Finish Mode) + +Suitable for LLM streaming output scenarios, synthesize while receiving text: + +```java +// Create real-time TTS model +DashScopeRealtimeTTSModel ttsModel = DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") + .voice("Cherry") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) // Server auto-commit + .languageType("Auto") // Auto-detect language + .build(); + +// Create audio player +AudioPlayer player = AudioPlayer.builder().sampleRate(24000).build(); + +// 1. Start session (establish WebSocket connection) +ttsModel.startSession(); + +// 2. Subscribe to audio stream +ttsModel.getAudioStream() + .doOnNext(audio -> player.play(audio)) + .subscribe(); + +// 3. Incrementally push text (simulate LLM streaming output) +ttsModel.push("你好，"); +ttsModel.push("我是你的"); +ttsModel.push("智能助手。"); + +// 4. End session, wait for all audio to complete +ttsModel.finish().blockLast(); + +// 5. Close connection +ttsModel.close(); +``` + +#### SessionMode Description + +| Mode | Description | +|------|-------------| +| `SERVER_COMMIT` | Server automatically commits text for synthesis (recommended) | +| `COMMIT` | Client needs to manually call `commitTextBuffer()` to commit | + +--- + +## Method 3: DashScopeMultiModalTool (As Agent Tool) + +Agent calls TTS via tool, Agent decides when to convert text to speech: + +```java +// 1. Create multimodal tool +DashScopeMultiModalTool multiModalTool = new DashScopeMultiModalTool(apiKey); + +// 2. Create Agent, register tool +ReActAgent agent = ReActAgent.builder() + .name("MultiModalAssistant") + .sysPrompt("你是一个多模态助手。当用户要求朗读时，使用 dashscope_text_to_audio 工具。") + .model(chatModel) + .tools(multiModalTool) + .build(); + +// 3. Agent can actively call TTS tool +Msg response = agent.call(Msg.user("请用语音说一句'欢迎光临'")).block(); +``` + +--- + +## Complete Examples + +- Quick Start: `agentscope-examples/quickstart/TTSExample.java` +- Complete Example: `agentscope-examples/chat-tts` module, includes frontend and backend interaction + +--- + +## Core Component Configuration Parameters + +### DashScopeRealtimeTTSModel + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| apiKey | String | - | DashScope API Key (required) | +| modelName | String | qwen3-tts-flash-realtime | Model name | +| voice | String | Cherry | Voice name | +| sampleRate | int | 24000 | Sample rate (8000/16000/24000) | +| format | String | pcm | Audio format (pcm/mp3/opus) | +| mode | SessionMode | SERVER_COMMIT | Session mode | +| languageType | String | Auto | Language type (Chinese/English/Auto, etc.) | + +### DashScopeTTSModel + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| apiKey | String | - | DashScope API Key (required) | +| modelName | String | qwen3-tts-flash | Model name | +| voice | String | Cherry | Voice name | + +### TTSHook + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| ttsModel | DashScopeRealtimeTTSModel | - | TTS model (required) | +| audioPlayer | AudioPlayer | null | Local player (optional) | +| audioCallback | Consumer | null | Audio callback (optional) | +| realtimeMode | boolean | true | Whether to enable real-time mode | +| autoStartPlayer | boolean | true | Whether to auto-start player | \ No newline at end of file diff --git a/docs/zh/task/tts.md b/docs/zh/task/tts.md new file mode 100644 index 000000000..b2daf2378 --- /dev/null +++ b/docs/zh/task/tts.md @@ -0,0 +1,205 @@ +# Text-to-Speech (TTS) 语音合成 + +AgentScope Java 提供了完整的 TTS 能力支持，让 Agent 不仅能思考和回复，还能开口说话。相比于纯文本的场景，语音是更自然的交互方式，适用于 智能客服、车载助手，以及边生成边朗读的实时对话场景。 + + +## 选择合适的模型 + +**非实时模型**：适合对音频质量要求高、可以接受几秒延迟的场景，例如播客、有声书、短视频配音等。使用 `DashScopeTTSModel` 和 `qwen3-tts-flash` 模型，一次性发送完整文本，等待服务器处理完整个音频后返回，模型可以全局优化整段话的重音、语调和情感，获得最佳的音频质量。 + + +**实时模型**：适合对响应速度要求高、需要边生成边播放的场景，例如 AI 助手、实时翻译等。使用 `DashScopeRealtimeTTSModel` 和 `qwen3-tts-flash-realtime` 模型，流式发送文本块片段，服务器实时返回音频块，延迟更低。虽然是分块合成，但模型也会保留上下文窗口来维持自然度。 + +## 使用方式 + +AgentScope 提供三种使用 TTS 的方式： + +**ReActAgent 集成**：通过在 ReActAgent 中添加 TTSHook，可以实现 Agent 所有回复的自动朗读，只需添加 TTSHook 就能实现边生成边播放的效果。 + +**独立使用 TTSModel**：不依赖 Agent，直接调用 TTSModel 进行独立语音合成，可以灵活使用，适合需要单独进行语音转换的场景。 + +**作为工具使用 DashScopeMultiModalTool**：将 TTS 作为多模态工具提供给 Agent，Agent 可以自行判断在需要时将文字转成语音。 + +--- + +## 方式一：ReActAgent 集成 + +通过在 ReactAgent 添加 TTSHook 的方式，支持 ReactAgent 在回复时自动朗读。 + +**工作原理**： + +- **事件监听机制**：TTSHook 实现了 Hook 接口，监听 Agent 执行过程中的事件。当 Agent 开始推理时触发 `PreReasoningEvent`，生成文本块时触发 `ReasoningChunkEvent`，推理完成时触发 `PostReasoningEvent`。 + +- **实时流式合成**：在实时模式下，TTSHook 监听 `ReasoningChunkEvent`，每当 Agent 生成一个文本块时，立即通过 WebSocket 推送到 TTS 模型进行语音合成。这样实现了"边生成边播放"的效果，用户几乎感觉不到延迟。 + +- **会话生命周期管理**：在第一次收到文本块时，TTSHook 会启动 TTS 会话（建立 WebSocket 连接）并订阅音频流。当 Agent 推理完成时，调用 `finish()` 提交剩余文本并关闭会话，确保所有音频都被合成和播放。 + +- **音频分发机制**：生成的音频块通过三种方式分发：1) 发送到响应式流（`audioSink`），供 SSE/WebSocket 前端订阅；2) 调用 `audioCallback` 回调函数，用于自定义处理；3) 通过 `AudioPlayer` 本地播放，适用于 CLI/桌面应用。 + +- **播放中断处理**：当新的推理开始时（`PreReasoningEvent`），TTSHook 会中断当前正在播放的音频，关闭旧的 TTS 会话，确保新回复的音频能够立即开始播放，避免音频混乱。 + +### 本地播放模式（CLI/桌面应用） + +使用 WebSocket 实时流式合成，支持边生成边播放： + +```java +// 1. 创建实时 TTS 模型（WebSocket 流式） +DashScopeRealtimeTTSModel ttsModel = DashScopeRealtimeTTSModel.builder() + .apiKey(System.getenv("DASHSCOPE_API_KEY")) + .modelName("qwen3-tts-flash-realtime") // WebSocket 实时模型 + .voice("Cherry") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) // 服务端自动提交 + .build(); + +// 2. 创建 TTS Hook +TTSHook ttsHook = TTSHook.builder().ttsModel(ttsModel).build(); + +// 3. 创建带 TTS 的 Agent +ReActAgent agent = ReActAgent.builder() + .name("Assistant") + .sysPrompt("你是一个友好的助手") + .model(chatModel) + .hook(ttsHook) // 添加 TTS Hook + .build(); + +// 4. 与 Agent 对话 - Agent 会边生成回复边朗读 +Msg response = agent.call(Msg.user("你好，今天天气怎么样？")).block(); +``` + +### 服务器模式（Web/SSE） + +在 Web 应用中，音频需要发送到前端播放，可以将音频通过 SSE 发送到前端，或者使用响应式流，完整的代码可以参考 `agentscope-examples/chat-tts` 模块，包含前后端交互。 + +--- + +## 方式二：独立使用 TTSModel + +不依赖 Agent，直接调用 TTS 模型进行语音合成。 + +### 2.1 非实时模式 + +适合一次性返回完整音频： + +```java +// 创建 TTS 模型 +DashScopeTTSModel ttsModel = DashScopeTTSModel.builder() + .apiKey(System.getenv("DASHSCOPE_API_KEY")) + .modelName("qwen3-tts-flash") + .build(); + +// 合成语音 +TTSOptions options = TTSOptions.builder().voice("Cherry").sampleRate(24000).format("wav").build(); + +TTSResponse response = ttsModel.synthesize("你好，欢迎使用语音合成功能！", options).block(); + +// 获取音频数据 +byte[] audioData = response.getAudioData(); +AudioBlock audioBlock = response.toAudioBlock(); +``` + +### 2.2 实时模式 - 增量输入（Push/Finish 模式） + +适用于 LLM 流式输出场景，边接收文本边合成： + +```java +// 创建实时 TTS 模型 +DashScopeRealtimeTTSModel ttsModel = DashScopeRealtimeTTSModel.builder() + .apiKey(apiKey) + .modelName("qwen3-tts-flash-realtime") + .voice("Cherry") + .mode(DashScopeRealtimeTTSModel.SessionMode.SERVER_COMMIT) // 服务端自动提交 + .languageType("Auto") // 自动检测语言 + .build(); + +// 创建音频播放器 +AudioPlayer player = AudioPlayer.builder().sampleRate(24000).build(); + +// 1. 开始会话（建立 WebSocket 连接） +ttsModel.startSession(); + +// 2. 订阅音频流 +ttsModel.getAudioStream() + .doOnNext(audio -> player.play(audio)) + .subscribe(); + +// 3. 增量推送文本（模拟 LLM 流式输出） +ttsModel.push("你好，"); +ttsModel.push("我是你的"); +ttsModel.push("智能助手。"); + +// 4. 结束会话，等待所有音频完成 +ttsModel.finish().blockLast(); + +// 5. 关闭连接 +ttsModel.close(); +``` + +#### SessionMode 说明 + +| 模式 | 说明 | +|------|------| +| `SERVER_COMMIT` | 服务端自动提交文本进行合成（推荐） | +| `COMMIT` | 客户端需要手动调用 `commitTextBuffer()` 提交 | + +--- + +## 方式三：DashScopeMultiModalTool（作为 Agent 工具） + +Agent 通过工具方式调用 TTS，Agent 自行判断在需要时将文字转成语音 + +```java +// 1. 创建多模态工具 +DashScopeMultiModalTool multiModalTool = new DashScopeMultiModalTool(apiKey); + +// 2. 创建 Agent，注册工具 +ReActAgent agent = ReActAgent.builder() + .name("MultiModalAssistant") + .sysPrompt("你是一个多模态助手。当用户要求朗读时，使用 dashscope_text_to_audio 工具。") + .model(chatModel) + .tools(multiModalTool) + .build(); + +// 3. Agent 可以主动调用 TTS 工具 +Msg response = agent.call(Msg.user("请用语音说一句'欢迎光临'")).block(); +``` + +--- + +## 完整示例 + +- 快速开始：`agentscope-examples/quickstart/TTSExample.java` +- 完整示例：`agentscope-examples/chat-tts` 模块，包含前后端交互 + +--- + +## 核心组件配置参数 + +### DashScopeRealtimeTTSModel + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| apiKey | String | - | DashScope API Key（必需） | +| modelName | String | qwen3-tts-flash-realtime | 模型名称 | +| voice | String | Cherry | 声音名称 | +| sampleRate | int | 24000 | 采样率 (8000/16000/24000) | +| format | String | pcm | 音频格式 (pcm/mp3/opus) | +| mode | SessionMode | SERVER_COMMIT | 会话模式 | +| languageType | String | Auto | 语言类型 (Chinese/English/Auto 等) | + +### DashScopeTTSModel + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| apiKey | String | - | DashScope API Key（必需） | +| modelName | String | qwen3-tts-flash | 模型名称 | +| voice | String | Cherry | 声音名称 | + +### TTSHook + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| ttsModel | DashScopeRealtimeTTSModel | - | TTS 模型（必需） | +| audioPlayer | AudioPlayer | null | 本地播放器（可选） | +| audioCallback | Consumer | null | 音频回调（可选） | +| realtimeMode | boolean | true | 是否启用实时模式 | +| autoStartPlayer | boolean | true | 是否自动启动播放器 | \ No newline at end of file From e84d7dd0ce59837e47b323784894280e492c1e9f Mon Sep 17 00:00:00 2001 From: fang-tech Date: Fri, 23 Jan 2026 16:20:39 +0800 Subject: [PATCH 44/53] feat(skill): refactor code execution API with builder pattern (#646) ## AgentScope-Java Version 1.0.7 ## Description - Replace enableCodeExecution() with fluent builder API - Support selective tool enabling and ShellCommandTool customization - Add cross-platform tests (Unix/Mac + Windows) - Update documentation with new API examples **BREAKING CHANGE**: enableCodeExecution() methods removed, use codeExecution().enable() instead ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review --- .../io/agentscope/core/skill/SkillBox.java | 336 ++++++++++--- .../core/tool/coding/ShellCommandTool.java | 36 ++ .../agentscope/core/skill/SkillBoxTest.java | 169 ++++++- .../tool/coding/ShellCommandToolTest.java | 442 +++++++++++++++++- docs/en/task/agent-skill.md | 56 ++- docs/zh/task/agent-skill.md | 56 ++- 6 files changed, 999 insertions(+), 96 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java index 478a43afc..8e7cb1fae 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java +++ b/agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java @@ -19,6 +19,7 @@ import io.agentscope.core.tool.AgentTool; import io.agentscope.core.tool.ExtendedModel; import io.agentscope.core.tool.Toolkit; +import io.agentscope.core.tool.coding.CommandValidator; import io.agentscope.core.tool.coding.ShellCommandTool; import io.agentscope.core.tool.file.ReadFileTool; import io.agentscope.core.tool.file.WriteFileTool; @@ -34,6 +35,7 @@ import java.util.List; import java.util.Map; import java.util.Set; +import java.util.function.Function; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -549,82 +551,45 @@ public void registerSkillLoadTool() { // ==================== Code Execution ==================== /** - * Enables code execution capabilities for skills with temporary working directory. + * Create a fluent builder for configuring code execution with custom options. * - *

    This method creates a sandboxed environment for executing scripts from skills. - * A temporary directory will be created when scripts are written. + *

    This is the recommended way to enable code execution capabilities for skills. + * The builder allows selective enabling of tools and customization of ShellCommandTool. * - * @throws IllegalStateException if toolkit is not bound - */ - public void enableCodeExecution() { - enableCodeExecution(null); - } - - /** - * Enables code execution capabilities for skills. - * - *

    This method creates a sandboxed environment for executing scripts from skills by: - *

      - *
    • Registering ShellCommandTool with allowed commands (python, python3, node, nodejs)
      • - *
    • Registering ReadFileTool and WriteFileTool restricted to the working directory
      • - *
    • Creating and activating the "skill_code_execution_tool_group" tool group
      • - *
    - * - *

    After calling this method, scripts from registered skills will be written to the - * working directory when the agent is configured. + *

    Example usage: + * 

    {@code
+     * // Simple - enable all tools with default configuration
+     * skillBox.codeExecution()
+     *     .withShell()
+     *     .withRead()
+     *     .withWrite()
+     *     .enable();
+     *
+     * // Custom shell tool with approval callback
+     * ShellCommandTool customShell = new ShellCommandTool(
+     *     null,  // baseDir will be overridden
+     *     Set.of("python3", "node", "npm"),
+     *     command -> askUserApproval(command)
+     * );
+     *
+     * skillBox.codeExecution()
+     *     .workDir("/path/to/workdir")
+     *     .withShell(customShell)  // Clone with workDir
+     *     .withRead()
+     *     .withWrite()
+     *     .enable();
+     *
+     * // Only enable read and write tools
+     * skillBox.codeExecution()
+     *     .withRead()
+     *     .withWrite()
+     *     .enable();
+     * }
    * - *

    - * Note: This method should only be called once. Calling it multiple - * times - * will throw an IllegalStateException. - * - * @param workDir Working directory for code execution. If null or empty, a - * temporary - * directory will be created when scripts are written. - * @throws IllegalStateException if toolkit is not bound or if code execution is - * already enabled + * @return A new CodeExecutionBuilder for configuration */ - public void enableCodeExecution(String workDir) { - if (toolkit == null) { - throw new IllegalStateException("Must bind toolkit before enabling code execution"); - } - - // Prevent duplicate enablement - if (isCodeExecutionEnabled()) { - throw new IllegalStateException( - "Code execution is already enabled. This method should only be called once."); - } - - // Set workDir (null means temporary directory will be created later) - if (workDir == null || workDir.isEmpty()) { - this.codeExecutionWorkDir = null; - } else { - this.codeExecutionWorkDir = Paths.get(workDir).toAbsolutePath().normalize(); - } - - // Create tool group - if (toolkit.getToolGroup("skill_code_execution_tool_group") == null) { - toolkit.createToolGroup( - "skill_code_execution_tool_group", "Code execution tools for skills", true); - } - - // Create and register three tools - Set allowedCommands = Set.of("python", "python3", "node", "nodejs"); - String workDirStr = codeExecutionWorkDir != null ? codeExecutionWorkDir.toString() : null; - ShellCommandTool shellTool = new ShellCommandTool(workDirStr, allowedCommands, null); - ReadFileTool readTool = new ReadFileTool(workDirStr); - WriteFileTool writeTool = new WriteFileTool(workDirStr); - - toolkit.registration() - .agentTool(shellTool) - .group("skill_code_execution_tool_group") - .apply(); - toolkit.registration().tool(readTool).group("skill_code_execution_tool_group").apply(); - toolkit.registration().tool(writeTool).group("skill_code_execution_tool_group").apply(); - - logger.info( - "Code execution enabled with workDir: {}", - codeExecutionWorkDir != null ? codeExecutionWorkDir : "temporary directory"); + public CodeExecutionBuilder codeExecution() { + return new CodeExecutionBuilder(this); } /** @@ -787,4 +752,231 @@ public void writeSkillScriptsToWorkDir() { } logger.info("Wrote {} skill scripts to workDir: {}", scriptCount, workDir); } + + // ==================== Code Execution Builder ==================== + + /** + * Fluent builder for configuring code execution with custom options. + * + *

    This builder provides a flexible way to enable code execution capabilities + * with selective tool enabling and custom ShellCommandTool configuration. + * + *

    Key features: + *

      + *
    • Selective tool enabling: choose which tools (shell/read/write) to enable
      • + *
    • Custom ShellCommandTool: provide your own tool with custom security policies
      • + *
    • WorkDir enforcement: all tools use the same working directory
      • + *
    • Tool cloning: custom ShellCommandTool is cloned with workDir override
      • + *
    + */ + public static class CodeExecutionBuilder { + private final SkillBox skillBox; + private String workDir; + private ShellCommandTool customShellTool; + private boolean withShellCalled = false; + private boolean enableRead = false; + private boolean enableWrite = false; + + CodeExecutionBuilder(SkillBox skillBox) { + this.skillBox = skillBox; + } + + /** + * Set the working directory for code execution. + * + *

    All code execution tools (shell, read, write) will use this directory. + * If not set, a temporary directory will be created when scripts are written. + * + * @param workDir The working directory path (null or empty for temporary directory) + * @return This builder for chaining + */ + public CodeExecutionBuilder workDir(String workDir) { + this.workDir = workDir; + return this; + } + + /** + * Enable shell command execution with default configuration. + * + *

    Default configuration: + *

      + *
    • Allowed commands: python, python3, node, nodejs
      • + *
    • No approval callback
      • + *
    • Platform-specific validator (Unix or Windows)
      • + *
    + * + * @return This builder for chaining + */ + public CodeExecutionBuilder withShell() { + this.withShellCalled = true; + this.customShellTool = null; + return this; + } + + /** + * Enable shell command execution with a custom ShellCommandTool. + * + *

    The provided tool will be cloned with the following behavior: + *

      + *
    • allowedCommands: copied from the source tool
      • + *
    • approvalCallback: copied from the source tool
      • + *
    • commandValidator: copied from the source tool
      • + *
    • baseDir: OVERRIDDEN with the builder's workDir
      • + *
    + * + *

    This ensures all code execution tools use the same working directory + * while preserving your custom security policies. + * + * @param shellTool The custom ShellCommandTool to clone (must not be null) + * @return This builder for chaining + * @throws IllegalArgumentException if shellTool is null + */ + public CodeExecutionBuilder withShell(ShellCommandTool shellTool) { + if (shellTool == null) { + throw new IllegalArgumentException("ShellCommandTool cannot be null"); + } + this.withShellCalled = true; + this.customShellTool = shellTool; + return this; + } + + /** + * Enable file reading capabilities. + * + *

    Registers ReadFileTool with the builder's workDir as base directory. + * + * @return This builder for chaining + */ + public CodeExecutionBuilder withRead() { + this.enableRead = true; + return this; + } + + /** + * Enable file writing capabilities. + * + *

    Registers WriteFileTool with the builder's workDir as base directory. + * + * @return This builder for chaining + */ + public CodeExecutionBuilder withWrite() { + this.enableWrite = true; + return this; + } + + /** + * Apply the configuration and enable code execution. + * + *

    This method: + *

      + *
    • Validates toolkit is bound
      • + *
    • Removes existing code execution configuration if present
      • + *
    • Creates the code execution tool group
      • + *
    • Registers selected tools (shell, read, write)
      • + *
    + * + * @throws IllegalStateException if toolkit is not bound + */ + public void enable() { + if (skillBox.toolkit == null) { + throw new IllegalStateException("Must bind toolkit before enabling code execution"); + } + + // Handle replacement: remove existing tool group if present + if (skillBox.isCodeExecutionEnabled()) { + skillBox.toolkit.removeToolGroups(List.of("skill_code_execution_tool_group")); + logger.info("Replacing existing code execution configuration"); + } + + // Set workDir + if (workDir == null || workDir.isEmpty()) { + skillBox.codeExecutionWorkDir = null; + } else { + skillBox.codeExecutionWorkDir = Paths.get(workDir).toAbsolutePath().normalize(); + } + + // Create tool group + skillBox.toolkit.createToolGroup( + "skill_code_execution_tool_group", "Code execution tools for skills", true); + + String workDirStr = + skillBox.codeExecutionWorkDir != null + ? skillBox.codeExecutionWorkDir.toString() + : null; + + boolean shellEnabled = false; + + // Shell Tool - check if withShell() was called + if (withShellCalled) { + ShellCommandTool shellTool; + if (customShellTool != null) { + // Clone custom tool with workDir override + shellTool = cloneShellToolWithWorkDir(customShellTool, workDirStr); + } else { + // Create default shell tool + shellTool = + new ShellCommandTool( + workDirStr, + Set.of("python", "python3", "node", "nodejs"), + null); + } + skillBox.toolkit + .registration() + .agentTool(shellTool) + .group("skill_code_execution_tool_group") + .apply(); + shellEnabled = true; + } + + // Read Tool + if (enableRead) { + ReadFileTool readTool = new ReadFileTool(workDirStr); + skillBox.toolkit + .registration() + .tool(readTool) + .group("skill_code_execution_tool_group") + .apply(); + } + + // Write Tool + if (enableWrite) { + WriteFileTool writeTool = new WriteFileTool(workDirStr); + skillBox.toolkit + .registration() + .tool(writeTool) + .group("skill_code_execution_tool_group") + .apply(); + } + + logger.info( + "Code execution enabled with workDir: {}, tools: [shell={}, read={}, write={}]", + skillBox.codeExecutionWorkDir != null + ? skillBox.codeExecutionWorkDir + : "temporary", + shellEnabled, + enableRead, + enableWrite); + } + + /** + * Clone a ShellCommandTool with a new base directory. + * + *

    This ensures all code execution tools use the same working directory + * while preserving the custom security policies from the source tool. + * + * @param source The source ShellCommandTool to clone + * @param workDir The new working directory (can be null for temporary) + * @return A new ShellCommandTool with the same configuration but different baseDir + */ + private ShellCommandTool cloneShellToolWithWorkDir( + ShellCommandTool source, String workDir) { + // Get configuration from source tool + Set allowedCommands = source.getAllowedCommands(); + Function approvalCallback = source.getApprovalCallback(); + CommandValidator validator = source.getCommandValidator(); + + // Create new instance with workDir override + return new ShellCommandTool(workDir, allowedCommands, approvalCallback, validator); + } + } } diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java index b3be297c9..5496055de 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java @@ -250,6 +250,42 @@ public boolean isCommandAllowed(String command) { return allowedCommands.contains(command); } + /** + * Get the approval callback function. + * Returns the callback that is used to request user approval for non-whitelisted commands. + * + *

    This method is useful for cloning ShellCommandTool instances with the same configuration. + * + * @return The approval callback function, or null if not configured + */ + public Function getApprovalCallback() { + return approvalCallback; + } + + /** + * Get the command validator. + * Returns the validator used for command security validation. + * + *

    This method is useful for cloning ShellCommandTool instances with the same configuration. + * + * @return The command validator instance + */ + public CommandValidator getCommandValidator() { + return commandValidator; + } + + /** + * Get the base directory for command execution. + * Returns the directory where commands will be executed. + * + *

    This method is useful for cloning ShellCommandTool instances with a different base directory. + * + * @return The base directory path, or null if using current directory + */ + public Path getBaseDir() { + return baseDir; + } + // ========================= AgentTool interface implementation ========================= @Override diff --git a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java index 8de0d8665..d97d9e87f 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java @@ -33,14 +33,20 @@ import io.agentscope.core.tool.ToolCallParam; import io.agentscope.core.tool.ToolParam; import io.agentscope.core.tool.Toolkit; +import io.agentscope.core.tool.coding.CommandValidator; +import io.agentscope.core.tool.coding.ShellCommandTool; +import io.agentscope.core.tool.coding.UnixCommandValidator; import io.agentscope.core.tool.mcp.McpClientWrapper; import io.modelcontextprotocol.spec.McpSchema; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.util.HashMap; +import java.util.HashSet; import java.util.List; import java.util.Map; +import java.util.Set; +import java.util.function.Function; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Nested; @@ -260,7 +266,7 @@ class CodeExecutionTest { @Test @DisplayName("Should enable code execution with default temporary directory") void testEnableCodeExecutionWithDefaultTempDir() { - skillBox.enableCodeExecution(); + skillBox.codeExecution().withShell().withRead().withWrite().enable(); assertTrue(skillBox.isCodeExecutionEnabled()); // workDir is null, meaning temporary directory will be created later @@ -276,7 +282,7 @@ void testEnableCodeExecutionWithDefaultTempDir() { void testEnableCodeExecutionWithCustomWorkDir() { String customDir = tempDir.resolve("custom-code-exec").toString(); - skillBox.enableCodeExecution(customDir); + skillBox.codeExecution().workDir(customDir).withShell().withRead().withWrite().enable(); assertTrue(skillBox.isCodeExecutionEnabled()); assertEquals( @@ -293,7 +299,12 @@ void testEnableCodeExecutionWithExistingDir() throws IOException { String existingDir = tempDir.resolve("existing-dir").toString(); Files.createDirectories(Path.of(existingDir)); - skillBox.enableCodeExecution(existingDir); + skillBox.codeExecution() + .workDir(existingDir) + .withShell() + .withRead() + .withWrite() + .enable(); assertTrue(skillBox.isCodeExecutionEnabled()); assertEquals( @@ -312,7 +323,7 @@ void testEnableCodeExecutionWithoutToolkit() { IllegalStateException exception = assertThrows( IllegalStateException.class, - () -> skillBoxWithoutToolkit.enableCodeExecution(null)); + () -> skillBoxWithoutToolkit.codeExecution().withShell().enable()); assertEquals( "Must bind toolkit before enabling code execution", exception.getMessage()); } @@ -321,7 +332,7 @@ void testEnableCodeExecutionWithoutToolkit() { @DisplayName("Should write skill scripts to working directory organized by skill ID") void testWriteSkillScriptsToWorkDir() throws IOException { String workDir = tempDir.resolve("scripts").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); // Verify directory not created yet assertFalse(Files.exists(Path.of(workDir))); @@ -380,7 +391,7 @@ void testWriteScriptsWithoutEnabling() { @DisplayName("Should handle empty scripts gracefully and not create skill directory") void testWriteEmptyScripts() throws IOException { String workDir = tempDir.resolve("empty-scripts").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); // Skill with no script resources Map resources = new HashMap<>(); @@ -404,7 +415,7 @@ void testWriteEmptyScripts() throws IOException { @DisplayName("Should overwrite existing scripts in skill directory") void testOverwriteExistingScripts() throws IOException { String workDir = tempDir.resolve("overwrite").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); // Create initial script in skill directory Path scriptPath = Path.of(workDir).resolve("skill_custom/test.py"); @@ -428,7 +439,7 @@ void testOverwriteExistingScripts() throws IOException { @DisplayName("Should create nested directories for scripts in skill directory") void testNestedDirectories() throws IOException { String workDir = tempDir.resolve("nested").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); Map resources = new HashMap<>(); resources.put("scripts/utils/helper.py", "def help(): pass"); @@ -448,7 +459,7 @@ void testNestedDirectories() throws IOException { @DisplayName("Should register three tools when code execution is enabled") void testToolsRegistration() { String workDir = tempDir.resolve("tools").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); var toolGroup = toolkit.getToolGroup("skill_code_execution_tool_group"); assertNotNull(toolGroup); @@ -464,7 +475,7 @@ void testToolsRegistration() { @Test @DisplayName("Should create temporary directory when workDir is null and verify it exists") void testCreateTemporaryDirectory() throws IOException { - skillBox.enableCodeExecution(); // null workDir + skillBox.codeExecution().withShell().withRead().withWrite().enable(); // null workDir Map resources = new HashMap<>(); resources.put("test.py", "print('test')"); @@ -485,7 +496,7 @@ void testCreateTemporaryDirectory() throws IOException { @DisplayName("Should prevent path traversal attacks") void testPathTraversalPrevention() throws IOException { String workDir = tempDir.resolve("secure").toString(); - skillBox.enableCodeExecution(workDir); + skillBox.codeExecution().workDir(workDir).withShell().withRead().withWrite().enable(); // Create skill with malicious path traversal attempts Map resources = new HashMap<>(); @@ -508,15 +519,135 @@ void testPathTraversalPrevention() throws IOException { } @Test - @DisplayName("Should throw exception when enableCodeExecution called multiple times") - void testDuplicateEnableCodeExecution() { - skillBox.enableCodeExecution(); + @DisplayName("Should replace existing code execution configuration") + void testReplaceCodeExecutionConfiguration() { + // Initial configuration - enable all three tools + skillBox.codeExecution().withShell().withRead().withWrite().enable(); - IllegalStateException exception = - assertThrows(IllegalStateException.class, () -> skillBox.enableCodeExecution()); - assertEquals( - "Code execution is already enabled. This method should only be called once.", - exception.getMessage()); + assertTrue(skillBox.isCodeExecutionEnabled()); + assertNotNull(toolkit.getTool("execute_shell_command")); + assertNotNull(toolkit.getTool("view_text_file")); + assertNotNull(toolkit.getTool("write_text_file")); + + // Replace configuration - only enable read and write + skillBox.codeExecution().withRead().withWrite().enable(); + + assertTrue(skillBox.isCodeExecutionEnabled()); + // Shell tool should be removed + assertNull(toolkit.getTool("execute_shell_command")); + // Read and write tools should still exist + assertNotNull(toolkit.getTool("view_text_file")); + assertNotNull(toolkit.getTool("write_text_file")); + } + + @Test + @DisplayName("Should enable only selected tools") + void testEnableOnlySelectedTools() { + // Enable only read and write, not shell + skillBox.codeExecution().withRead().withWrite().enable(); + + assertTrue(skillBox.isCodeExecutionEnabled()); + assertNull(toolkit.getTool("execute_shell_command")); + assertNotNull(toolkit.getTool("view_text_file")); + assertNotNull(toolkit.getTool("write_text_file")); + } + + @Test + @DisplayName("Should enable only shell tool") + void testEnableOnlyShellTool() { + skillBox.codeExecution().withShell().enable(); + + assertTrue(skillBox.isCodeExecutionEnabled()); + assertNotNull(toolkit.getTool("execute_shell_command")); + assertNull(toolkit.getTool("view_text_file")); + assertNull(toolkit.getTool("write_text_file")); + } + + @Test + @DisplayName("Should create empty tool group when no tools enabled") + void testEmptyToolGroupWhenNoToolsEnabled() { + skillBox.codeExecution().enable(); + + assertTrue(skillBox.isCodeExecutionEnabled()); + assertNull(toolkit.getTool("execute_shell_command")); + assertNull(toolkit.getTool("view_text_file")); + assertNull(toolkit.getTool("write_text_file")); + } + + @Test + @DisplayName("Should clone custom ShellCommandTool with workDir") + void testCloneCustomShellTool() { + // Create custom shell tool with specific configuration + Set customCommands = new HashSet<>(Set.of("python3", "npm", "node")); + Function callback = cmd -> true; + ShellCommandTool customShell = new ShellCommandTool(null, customCommands, callback); + + String workDir = tempDir.resolve("custom-shell").toString(); + skillBox.codeExecution().workDir(workDir).withShell(customShell).enable(); + + // Verify tool is registered + AgentTool registered = toolkit.getTool("execute_shell_command"); + assertNotNull(registered); + + // Verify it's a ShellCommandTool and check configuration + assertTrue(registered instanceof ShellCommandTool); + ShellCommandTool shellTool = (ShellCommandTool) registered; + + // Verify configuration was preserved + assertEquals(customCommands, shellTool.getAllowedCommands()); + assertEquals(callback, shellTool.getApprovalCallback()); + + // Verify baseDir was set to workDir + assertEquals(Path.of(workDir).toAbsolutePath().normalize(), shellTool.getBaseDir()); + } + + @Test + @DisplayName("Should throw exception when withShell receives null") + void testWithShellNullThrowsException() { + assertThrows( + IllegalArgumentException.class, () -> skillBox.codeExecution().withShell(null)); + } + + @Test + @DisplayName( + "Should use default shell configuration when withShell called without argument") + void testDefaultShellConfiguration() { + skillBox.codeExecution().withShell().enable(); + + AgentTool registered = toolkit.getTool("execute_shell_command"); + assertNotNull(registered); + + assertTrue(registered instanceof ShellCommandTool); + ShellCommandTool shellTool = (ShellCommandTool) registered; + + // Verify default configuration + Set allowedCommands = shellTool.getAllowedCommands(); + assertTrue(allowedCommands.contains("python")); + assertTrue(allowedCommands.contains("python3")); + assertTrue(allowedCommands.contains("node")); + assertTrue(allowedCommands.contains("nodejs")); + assertEquals(4, allowedCommands.size()); + + // Verify no approval callback + assertNull(shellTool.getApprovalCallback()); + } + + @Test + @DisplayName("Should preserve custom validator when cloning ShellCommandTool") + void testPreserveCustomValidator() { + CommandValidator customValidator = new UnixCommandValidator(); + ShellCommandTool customShell = new ShellCommandTool(null, null, customValidator); + + skillBox.codeExecution().withShell(customShell).enable(); + + AgentTool registered = toolkit.getTool("execute_shell_command"); + assertNotNull(registered); + + assertTrue(registered instanceof ShellCommandTool); + ShellCommandTool shellTool = (ShellCommandTool) registered; + + // Verify validator was preserved + assertEquals(customValidator, shellTool.getCommandValidator()); } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java index e4a75b19d..4940adb1d 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java @@ -24,6 +24,9 @@ import io.agentscope.core.message.TextBlock; import io.agentscope.core.message.ToolResultBlock; import io.agentscope.core.tool.ToolCallParam; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; import java.util.HashMap; import java.util.HashSet; import java.util.Map; @@ -824,7 +827,7 @@ void reproducePipeBufferDeadlockWithSeq() { @EnabledOnOs({OS.LINUX, OS.MAC}) void reproduceLargeFileCatDeadlock() throws Exception { // Create a temporary large file - java.nio.file.Path tempFile = java.nio.file.Files.createTempFile("test_large_", ".txt"); + Path tempFile = Files.createTempFile("test_large_", ".txt"); try { // Write 20KB of data (far exceeds typical pipe buffer size) StringBuilder content = new StringBuilder(); @@ -834,7 +837,7 @@ void reproduceLargeFileCatDeadlock() throws Exception { .append(": ") .append("Some test content to fill the buffer\n"); } - java.nio.file.Files.writeString(tempFile, content.toString()); + Files.writeString(tempFile, content.toString()); String command = "cat " + tempFile.toString(); @@ -861,7 +864,7 @@ void reproduceLargeFileCatDeadlock() throws Exception { }) .verifyComplete(); } finally { - java.nio.file.Files.deleteIfExists(tempFile); + Files.deleteIfExists(tempFile); } } @@ -928,4 +931,437 @@ void reproducePipeBufferDeadlockWithYesCommand() { .verifyComplete(); } } + + @Nested + @DisplayName("Getter Methods") + class GetterMethodsTests { + + @Test + @DisplayName("Should return unmodifiable allowed commands set") + void testGetAllowedCommandsReturnsUnmodifiable() { + Set original = new HashSet<>(Set.of("python", "node")); + ShellCommandTool tool = new ShellCommandTool(original); + + Set retrieved = tool.getAllowedCommands(); + + // Verify it's unmodifiable + assertThrows( + UnsupportedOperationException.class, + () -> retrieved.add("malicious"), + "Should not be able to modify returned set"); + + // Verify it contains the expected commands + assertEquals(2, retrieved.size()); + assertTrue(retrieved.contains("python")); + assertTrue(retrieved.contains("node")); + } + + @Test + @DisplayName("Should return approval callback") + void testGetApprovalCallback() { + Function callback = cmd -> true; + ShellCommandTool tool = new ShellCommandTool(null, callback); + + Function retrieved = tool.getApprovalCallback(); + + assertEquals(callback, retrieved, "Should return the same callback instance"); + } + + @Test + @DisplayName("Should return null approval callback when not set") + void testGetApprovalCallbackNull() { + ShellCommandTool tool = new ShellCommandTool(); + + Function retrieved = tool.getApprovalCallback(); + + assertEquals(null, retrieved, "Should return null when callback not set"); + } + + @Test + @DisplayName("Should return command validator") + void testGetCommandValidator() { + CommandValidator validator = new UnixCommandValidator(); + ShellCommandTool tool = new ShellCommandTool(null, null, validator); + + CommandValidator retrieved = tool.getCommandValidator(); + + assertEquals(validator, retrieved, "Should return the same validator instance"); + } + + @Test + @DisplayName("Should return default command validator when not set") + void testGetCommandValidatorDefault() { + ShellCommandTool tool = new ShellCommandTool(); + + CommandValidator retrieved = tool.getCommandValidator(); + + assertNotNull(retrieved, "Should return default validator"); + // Verify it's the correct platform-specific validator + String os = System.getProperty("os.name").toLowerCase(); + if (os.contains("win")) { + assertTrue( + retrieved instanceof WindowsCommandValidator, + "Should be WindowsCommandValidator on Windows"); + } else { + assertTrue( + retrieved instanceof UnixCommandValidator, + "Should be UnixCommandValidator on Unix/Linux/Mac"); + } + } + + @Test + @DisplayName("Should return base directory") + void testGetBaseDir() { + String baseDirStr = "/tmp/test"; + ShellCommandTool tool = new ShellCommandTool(baseDirStr, null, null); + + Path expectedPath = Paths.get(baseDirStr).toAbsolutePath().normalize(); + Path retrieved = tool.getBaseDir(); + + assertEquals(expectedPath, retrieved, "Should return the normalized base directory"); + } + + @Test + @DisplayName("Should return null base directory when not set") + void testGetBaseDirNull() { + ShellCommandTool tool = new ShellCommandTool(); + + Path retrieved = tool.getBaseDir(); + + assertEquals(null, retrieved, "Should return null when baseDir not set"); + } + } + + @Nested + @DisplayName("Base Directory Enforcement Tests") + class BaseDirectoryEnforcementTests { + + // Test 1: baseDir sets working directory (Unix/Mac) + @Test + @DisplayName("Should set working directory to baseDir (Unix)") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void testBaseDirSetsWorkingDirectoryUnix() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path testFile = tempDir.resolve("test.txt"); + Files.writeString(testFile, "test content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("ls", "pwd"), null); + + // Verify baseDir is set + assertEquals( + tempDir.toAbsolutePath().normalize(), + tool.getBaseDir(), + "Base directory should be set"); + + // Verify ls lists files in baseDir + Mono lsResult = tool.executeShellCommand("ls", 10); + StepVerifier.create(lsResult) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "ls should execute successfully"); + assertTrue( + text.contains("test.txt"), + "ls should list test.txt in baseDir"); + }) + .verifyComplete(); + + // Verify pwd shows baseDir + Mono pwdResult = tool.executeShellCommand("pwd", 10); + StepVerifier.create(pwdResult) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "pwd should execute successfully"); + assertTrue( + text.contains( + tempDir.toAbsolutePath() + .normalize() + .toString()), + "pwd should show baseDir path"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(testFile); + Files.deleteIfExists(tempDir); + } + } + + // Test 1: baseDir sets working directory (Windows) + @Test + @DisplayName("Should set working directory to baseDir (Windows)") + @EnabledOnOs(OS.WINDOWS) + void testBaseDirSetsWorkingDirectoryWindows() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path testFile = tempDir.resolve("test.txt"); + Files.writeString(testFile, "test content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("dir", "cd"), null); + + assertEquals( + tempDir.toAbsolutePath().normalize(), + tool.getBaseDir(), + "Base directory should be set"); + + // dir lists files + Mono dirResult = tool.executeShellCommand("dir", 10); + StepVerifier.create(dirResult) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "dir should execute successfully"); + assertTrue( + text.contains("test.txt"), + "dir should list test.txt in baseDir"); + }) + .verifyComplete(); + + // cd (no args) shows current directory + Mono cdResult = tool.executeShellCommand("cd", 10); + StepVerifier.create(cdResult) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "cd should execute successfully"); + String expectedPath = + tempDir.toAbsolutePath().normalize().toString(); + assertTrue( + text.contains(expectedPath), + "cd should show baseDir path"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(testFile); + Files.deleteIfExists(tempDir); + } + } + + // Test 2: Relative path resolution (Unix/Mac) + @Test + @DisplayName("Should resolve relative paths from baseDir (Unix)") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void testRelativePathResolutionUnix() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path restrictedDir = tempDir.resolve("restricted"); + Files.createDirectories(restrictedDir); + + Path secretFile = tempDir.resolve("secret.txt"); + Files.writeString(secretFile, "secret content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(restrictedDir.toString(), Set.of("cat"), null); + + // Access parent directory file using relative path + Mono result = tool.executeShellCommand("cat ../secret.txt", 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Relative path should resolve from baseDir"); + assertTrue( + text.contains("secret content"), + "Should access parent directory file"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(secretFile); + Files.deleteIfExists(restrictedDir); + Files.deleteIfExists(tempDir); + } + } + + // Test 2: Relative path resolution (Windows) + @Test + @DisplayName("Should resolve relative paths from baseDir (Windows)") + @EnabledOnOs(OS.WINDOWS) + void testRelativePathResolutionWindows() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path restrictedDir = tempDir.resolve("restricted"); + Files.createDirectories(restrictedDir); + + Path secretFile = tempDir.resolve("secret.txt"); + Files.writeString(secretFile, "secret content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(restrictedDir.toString(), Set.of("type"), null); + + // Windows uses backslash for relative paths + Mono result = tool.executeShellCommand("type ..\\secret.txt", 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Relative path should resolve from baseDir"); + assertTrue( + text.contains("secret content"), + "Should access parent directory file"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(secretFile); + Files.deleteIfExists(restrictedDir); + Files.deleteIfExists(tempDir); + } + } + + // Test 3: Absolute paths with baseDir (Unix/Mac) + @Test + @DisplayName("Should handle absolute paths with baseDir set (Unix)") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void testAbsolutePathsWithBaseDirUnix() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path testFile = tempDir.resolve("test.txt"); + Files.writeString(testFile, "test content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("cat"), null); + + // Access file using absolute path + String absolutePath = testFile.toAbsolutePath().toString(); + Mono result = tool.executeShellCommand("cat " + absolutePath, 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Absolute path should work with baseDir"); + assertTrue( + text.contains("test content"), + "Should read file with absolute path"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(testFile); + Files.deleteIfExists(tempDir); + } + } + + // Test 3: Absolute paths with baseDir (Windows) + @Test + @DisplayName("Should handle absolute paths with baseDir set (Windows)") + @EnabledOnOs(OS.WINDOWS) + void testAbsolutePathsWithBaseDirWindows() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + Path testFile = tempDir.resolve("test.txt"); + Files.writeString(testFile, "test content"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("type"), null); + + // Access file using absolute path + String absolutePath = testFile.toAbsolutePath().toString(); + Mono result = tool.executeShellCommand("type " + absolutePath, 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Absolute path should work with baseDir"); + assertTrue( + text.contains("test content"), + "Should read file with absolute path"); + }) + .verifyComplete(); + } finally { + Files.deleteIfExists(testFile); + Files.deleteIfExists(tempDir); + } + } + + // Test 4: baseDir persistence across executions (Unix/Mac) + @Test + @DisplayName("Should maintain baseDir across multiple executions (Unix)") + @EnabledOnOs({OS.LINUX, OS.MAC}) + void testBaseDirPersistenceUnix() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("pwd"), null); + + String expectedPath = tempDir.toAbsolutePath().normalize().toString(); + + // Execute pwd multiple times - should always show same baseDir + for (int i = 0; i < 3; i++) { + Mono result = tool.executeShellCommand("pwd", 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Command should execute successfully"); + assertTrue( + text.contains(expectedPath), + "Each execution should use same baseDir"); + }) + .verifyComplete(); + } + } finally { + Files.deleteIfExists(tempDir); + } + } + + // Test 4: baseDir persistence across executions (Windows) + @Test + @DisplayName("Should maintain baseDir across multiple executions (Windows)") + @EnabledOnOs(OS.WINDOWS) + void testBaseDirPersistenceWindows() throws Exception { + Path tempDir = Files.createTempDirectory("shell-test-"); + + try { + ShellCommandTool tool = + new ShellCommandTool(tempDir.toString(), Set.of("cd"), null); + + String expectedPath = tempDir.toAbsolutePath().normalize().toString(); + + // Execute cd multiple times - should always show same baseDir + for (int i = 0; i < 3; i++) { + Mono result = tool.executeShellCommand("cd", 10); + + StepVerifier.create(result) + .assertNext( + block -> { + String text = extractText(block); + assertTrue( + text.contains("0"), + "Command should execute successfully"); + assertTrue( + text.contains(expectedPath), + "Each execution should use same baseDir"); + }) + .verifyComplete(); + } + } finally { + Files.deleteIfExists(tempDir); + } + } + } } diff --git a/docs/en/task/agent-skill.md b/docs/en/task/agent-skill.md index 748eefc56..315744e75 100644 --- a/docs/en/task/agent-skill.md +++ b/docs/en/task/agent-skill.md @@ -14,6 +14,11 @@ Adopts **three-stage on-demand loading** to optimize context: Initially loads on **Workflow:** User Query → AI Identifies Relevant Skill → Calls `load_skill_through_path` Tool to Load Content and Activate Bound Tools → On-Demand Resource Access → Task Completion +**Unified Loading Tool**: `load_skill_through_path(skillId, resourcePath)` provides a single entry point for loading skill resources +- `skillId` uses an enum field, ensuring selection only from registered Skills, guaranteeing accuracy +- `resourcePath` is the resource path relative to the Skill root directory (e.g., `references/api-doc.md`) +- Returns a list of all available resource paths when the path is incorrect, helping the LLM correct errors + ### Adaptive Design We have further abstracted skills so that their discovery and content loading are no longer dependent on the file system. Instead, the LLM discovers and loads skill content and resources through tools. At the same time, to maintain compatibility with the existing skill ecosystem and resources, skills are still organized according to file system structure for their content and resources. @@ -165,6 +170,8 @@ ReActAgent agent = ReActAgent.builder() Bind Tools to Skills for on-demand activation. Avoids context pollution from pre-registering all Tools, only passing relevant Tools to LLM when the Skill is actively used. +**Lifecycle of Progressively Disclosed Tools**: Tool lifecycle remains consistent with Skill lifecycle. Once a Skill is activated, Tools remain available throughout the entire session, avoiding the call failures caused by Tool deactivation after each conversation round in the old mechanism. + **Example Code**: ```java @@ -192,7 +199,54 @@ ReActAgent agent = ReActAgent.builder() .build(); ``` -### Feature 2: Skill Persistence Storage +### Feature 2: Code Execution Capabilities + +Provides an isolated code execution folder for Skills, supporting Shell commands, file read/write operations, etc. Uses Builder pattern for flexible configuration of required tools. + +**Basic Usage**: + +```java +SkillBox skillBox = new SkillBox(toolkit); + +// Enable all code execution tools (Shell, read file, write file) +skillBox.codeExecution() + .withShell() + .withRead() + .withWrite() + .enable(); +``` + +**Custom Configuration**: + +```java +// Customize working directory and Shell command whitelist +ShellCommandTool customShell = new ShellCommandTool( + null, // baseDir will be automatically set to workDir + Set.of("python3", "node", "npm"), + command -> askUserApproval(command) // Optional command approval callback +); + +skillBox.codeExecution() + .workDir("/path/to/workdir") // Specify working directory + .withShell(customShell) // Use custom Shell tool + .withRead() // Enable file reading + .withWrite() // Enable file writing + .enable(); + +// Or enable only file operations, without Shell +skillBox.codeExecution() + .withRead() + .withWrite() + .enable(); +``` + +**Core Features**: +- **Unified Working Directory**: All tools share the same `workDir`, ensuring file isolation +- **Selective Enabling**: Flexibly combine Shell, read file, and write file tools as needed +- **Flexible Configuration**: Supports custom ShellCommandTool to meet customization requirements +- **Automatic Management**: Automatically creates temporary directory when `workDir` is not specified, with automatic cleanup on program exit + +### Feature 3: Skill Persistence Storage **Why is this feature needed?** diff --git a/docs/zh/task/agent-skill.md b/docs/zh/task/agent-skill.md index 1b3b486e4..1e74406bb 100644 --- a/docs/zh/task/agent-skill.md +++ b/docs/zh/task/agent-skill.md @@ -14,6 +14,11 @@ Agent Skill 是扩展智能体能力的模块化技能包。每个 Skill 包含 **工作流程:** 用户提问 → AI 识别相关 Skill → 调用 `load_skill_through_path` 工具加载内容并激活绑定的 Tool → 按需访问资源 → 完成任务 +**统一加载工具**: `load_skill_through_path(skillId, resourcePath)` 提供单一入口加载技能资源 +- `skillId` 使用枚举字段, 确保只能从已注册的 Skill 中选择, 保证准确性 +- `resourcePath` 是相对于 Skill 根目录的资源路径(如 `references/api-doc.md`) +- 路径错误时会返回所有可用的资源路径列表,帮助 LLM 纠正 + ### 适应性设计 我们将 Skill 进行了进一步的抽象,使其的发现和内容加载不再依赖于文件系统,而是 LLM 通过 Tool 来发现和加载 Skill 的内容和资源。同时为了兼容已有的 Skill 生态与资源,Skill 的组织形式依旧按照文件系统的结构来组织它的内容和资源。 @@ -162,6 +167,8 @@ ReActAgent agent = ReActAgent.builder() 将 Tool 与 Skill 绑定,实现按需激活。避免预先注册所有 Tool 导致的上下文污染,仅在 Skill 被 LLM 使用时才传递相关 Tool。 +**渐进式暴露的Tool的生命周期**: Tool 与 Skill 生命周期保持一致, Skill 激活后 Tool 在整个会话期间保持可用, 避免了旧机制中每轮对话后 Tool 失活导致的调用失败问题。 + **示例代码**: ```java @@ -189,7 +196,54 @@ ReActAgent agent = ReActAgent.builder() .build(); ``` -### 功能 2: Skill 持久化存储 +### 功能 2: 代码执行能力 + +为 Skill 提供隔离的代码执行文件夹,支持 Shell 命令、文件读写等操作。使用 Builder 模式灵活配置所需工具。 + +**基础用法**: + +```java +SkillBox skillBox = new SkillBox(toolkit); + +// 启用所有代码执行工具(Shell、读文件、写文件) +skillBox.codeExecution() + .withShell() + .withRead() + .withWrite() + .enable(); +``` + +**自定义配置**: + +```java +// 自定义工作目录和 Shell 命令白名单 +ShellCommandTool customShell = new ShellCommandTool( + null, // baseDir 会被自动设置为 workDir + Set.of("python3", "node", "npm"), + command -> askUserApproval(command) // 可选的命令审批回调 +); + +skillBox.codeExecution() + .workDir("/path/to/workdir") // 指定工作目录 + .withShell(customShell) // 使用自定义 Shell 工具 + .withRead() // 启用文件读取 + .withWrite() // 启用文件写入 + .enable(); + +// 或仅启用文件操作,不启用 Shell +skillBox.codeExecution() + .withRead() + .withWrite() + .enable(); +``` + +**核心特性**: +- **统一工作目录**: 所有工具共享同一 `workDir`,确保文件隔离 +- **选择性启用**: 根据需求灵活组合 Shell、读文件、写文件工具 +- **灵活配置**: 支持自定义 ShellCommandTool, 满足定制化的ShellCommandTool需求 +- **自动管理**: 未指定 `workDir` 时自动创建临时目录,程序退出时自动清理 + +### 功能 3: Skill 持久化存储 **为什么需要这个功能?** From 21a8812db952683df23e2d0345bd5c21a6af3de8 Mon Sep 17 00:00:00 2001 From: Albumen Kevin Date: Sat, 24 Jan 2026 10:04:18 +0800 Subject: [PATCH 45/53] fix: empty content in ToolCalls (#643) Change-Id: I9d13239d03f01ebebf281b0af1d0766a882c86b7 ## 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] ## 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 --- .../agentscope/core/agent/accumulator/ToolCallsAccumulator.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java index 06b8a75c2..8f6864dff 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java @@ -105,7 +105,7 @@ ToolUseBlock build() { .id(toolId != null ? toolId : generateId()) .name(name) .input(finalArgs) - .content(rawContentStr.isEmpty() ? null : rawContentStr) + .content(rawContentStr.isEmpty() ? "{}" : rawContentStr) .metadata(metadata.isEmpty() ? null : metadata) .build(); } From 66fa8603a20f839399cdf4a67a8ec9e88b6af299 Mon Sep 17 00:00:00 2001 From: JgoP <52067013+JGoP-L@users.noreply.github.com> Date: Sat, 24 Jan 2026 10:04:35 +0800 Subject: [PATCH 46/53] fix(ollama): handle no-parameter tool calls with empty arguments (#572) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AgentScope-Java Version 1.0.8-SNAPSHOT Description Background When using OllamaChatModel to call tools with no parameters (like getTime()), the tool execution fails with a validation error, while the same tool works correctly with OpenAIChatModel. Reported in issue #569. Problem The root cause is in OllamaResponseParser. When Ollama returns a tool call with no parameters, the arguments field is an empty map {}. The parser was passing null as the content parameter when creating ToolUseBlock: // Before fix contentBlocks.add( new ToolUseBlock(callId, fn.getName(), input, null) // content = null ); However, ToolValidator.validateInput(toolCall.getContent(), ...) expects a JSON string for schema validation. When content is null, validation fails with: Parameter validation failed for tool 'getTime': Schema validation error: argument "content" is null Solution Convert the input map to a JSON string for the content parameter. For tools with no parameters, use the empty JSON object "{}": // After fix String argumentsJson = "{}"; // default for no parameters if (input != null && !input.isEmpty()) { argumentsJson = JsonUtils.getJsonCodec().toJson(input); } contentBlocks.add( new ToolUseBlock(callId, fn.getName(), input, argumentsJson, null) ); This aligns with how other formatters handle tool arguments, ensuring ToolValidator receives a valid JSON string. Changes Made - Modified: OllamaResponseParser.java - Convert input map to JSON string for content parameter - Added: Test case testParseToolCallWithNoParameters in OllamaResponseParserTest.java to prevent regression - Added: Test case testEmptyInputWithEmptySchema in ToolValidatorTest.java to verify empty object validation How to Test Run the Ollama formatter tests: mvn test -Dtest=OllamaResponseParserTest Or test with a real Ollama instance: @Tool(description = "获取当前时间") public String getTime() { return LocalDateTime.now().toString(); } Using OllamaChatModel with a tool like getTime (no parameters) should now work correctly. 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 --- .../ollama/OllamaResponseParser.java | 13 ++++-- .../ollama/OllamaResponseParserTest.java | 42 +++++++++++++++++++ .../core/tool/ToolValidatorTest.java | 15 +++++++ 3 files changed, 67 insertions(+), 3 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/formatter/ollama/OllamaResponseParser.java b/agentscope-core/src/main/java/io/agentscope/core/formatter/ollama/OllamaResponseParser.java index 8b5ef7b88..96aa6587a 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/formatter/ollama/OllamaResponseParser.java +++ b/agentscope-core/src/main/java/io/agentscope/core/formatter/ollama/OllamaResponseParser.java @@ -24,6 +24,7 @@ import io.agentscope.core.message.ToolUseBlock; import io.agentscope.core.model.ChatResponse; import io.agentscope.core.model.ChatUsage; +import io.agentscope.core.util.JsonUtils; import java.util.ArrayList; import java.util.HashMap; import java.util.List; @@ -66,10 +67,16 @@ public ChatResponse parseResponse(OllamaResponse response) { // AgentScope requirement. String callId = UUID.randomUUID().toString(); + // Convert input to JSON string for validation in ToolExecutor + // For tools with no parameters, input will be null or an empty map {} + String argumentsJson; + if (input == null || input.isEmpty()) { + argumentsJson = "{}"; + } else { + argumentsJson = JsonUtils.getJsonCodec().toJson(input); + } contentBlocks.add( - new ToolUseBlock( - callId, fn.getName(), input, null // raw content - )); + new ToolUseBlock(callId, fn.getName(), input, argumentsJson, null)); } } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaResponseParserTest.java b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaResponseParserTest.java index 3f62e56bb..bc9fc3725 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaResponseParserTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/formatter/ollama/OllamaResponseParserTest.java @@ -268,4 +268,46 @@ void testFallbackFinishReason() { // Assert assertEquals("stop", chatResponse.getFinishReason()); } + + @Test + @DisplayName("Should parse tool call with no parameters (empty arguments map)") + void testParseToolCallWithNoParameters() { + // Arrange - This reproduces the bug from issue #569 + // Ollama returns empty map {} for tools with no parameters + OllamaResponse response = new OllamaResponse(); + response.setModel("test-model"); + + OllamaMessage message = new OllamaMessage("assistant", ""); + + OllamaToolCall toolCall = new OllamaToolCall(); + OllamaFunction function = new OllamaFunction(); + function.setName("getTime"); + function.setArguments(Map.of()); // Empty map for no parameters + toolCall.setFunction(function); + + message.setToolCalls(Arrays.asList(toolCall)); + response.setMessage(message); + + // Act + ChatResponse chatResponse = parser.parseResponse(response); + + // Assert + assertNotNull(chatResponse); + List content = chatResponse.getContent(); + assertEquals(1, content.size()); + assertTrue(content.get(0) instanceof ToolUseBlock); + + ToolUseBlock toolBlock = (ToolUseBlock) content.get(0); + assertEquals("getTime", toolBlock.getName()); + assertTrue(toolBlock.getInput().isEmpty(), "Input should be empty map"); + + // Verify that getContent() returns "{}" (not null) for no-parameter tools + assertNotNull( + toolBlock.getContent(), + "ToolUseBlock content should not be null for validation in ToolExecutor"); + assertEquals( + "{}", + toolBlock.getContent(), + "ToolUseBlock content should be empty JSON object string for no-parameter tools"); + } } diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java index 898d8fcec..4e3182781 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java @@ -54,6 +54,21 @@ void testNullSchema() { assertNull(result); } + @Test + @DisplayName("Should pass when input is empty object with empty schema") + void testEmptyInputWithEmptySchema() { + // This simulates a tool with no parameters (like getTime()) + Map schema = + Map.of( + "type", + "object", + "properties", + Map.of()); // Empty properties = no parameters + + String result = ToolValidator.validateInput("{}", schema); + assertNull(result, "Empty object {} should pass validation with empty schema"); + } + @Test @DisplayName("Should pass when schema is empty") void testEmptySchema() { From fb85a6e983e6f47856b02e09cb85a184f00d9c84 Mon Sep 17 00:00:00 2001 From: wuji1428 <83492426+wuji1428@users.noreply.github.com> Date: Sat, 24 Jan 2026 10:13:05 +0800 Subject: [PATCH 47/53] fix(ReActAgent): When ReactAgent resumes, it only executes tools that do not yet have corresponding results (#650) ## 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 In the `acting` function, based on extracting the calling tools from the previous assistant message, tools that already have calling results are filtered out. ## Checklist Please check the following items before code is ready to be reviewed. - [x] Code has been formatted with `mvn spotless:apply` - [x] All tests are passing (`mvn test`) - [x] Javadoc comments are complete and follow project conventions - [x] Related documentation has been updated (e.g. links, examples, etc.) - [x] Code is ready for review ## Related Issues Ref [#649](https://github.com/agentscope-ai/agentscope-java/issues/649) --- .../java/io/agentscope/core/ReActAgent.java | 34 ++++- .../core/hook/HookStopAgentTest.java | 134 +++++++++++++++++- 2 files changed, 161 insertions(+), 7 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java index e37ed93bb..fdcc9e77b 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java +++ b/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java @@ -489,7 +489,7 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { /** * Execute the acting phase. * - *

    This method executes all tools (including external ones which return pending results), + *

    This method executes only pending tools (those without results in memory), * notifies hooks for successful tool results, and decides whether to continue iteration * or return (HITL stop, suspended tools, or structured output). * @@ -504,17 +504,19 @@ private Mono reasoning(int iter, boolean ignoreMaxIters) { * @return Mono containing the final result message */ private Mono acting(int iter) { - List allToolCalls = extractRecentToolCalls(); + // Extract only pending tool calls (those without results in memory) + List pendingToolCalls = extractPendingToolCalls(); - if (allToolCalls.isEmpty()) { + if (pendingToolCalls.isEmpty()) { + // No pending tools have been executed, continue to next iteration return executeIteration(iter + 1); } // Set chunk callback for streaming tool responses toolkit.setChunkCallback((toolUse, chunk) -> notifyActingChunk(toolUse, chunk).subscribe()); - // Execute all tools (including external ones which will return pending results) - return notifyPreActingHooks(allToolCalls) + // Execute only pending tools (those without results in memory) + return notifyPreActingHooks(pendingToolCalls) .flatMap(this::executeToolCalls) .flatMap( results -> { @@ -760,6 +762,28 @@ private List extractRecentToolCalls() { return MessageUtils.extractRecentToolCalls(memory.getMessages(), getName()); } + /** + * Extract only pending tool calls (those without results in memory) from the most recent + * assistant message. + * + *

    This method filters out tool calls that already have corresponding results in memory, + * preventing duplicate execution when resuming from HITL or partial tool result scenarios. + * + * @return List of tool use blocks that don't have results yet, or empty list if all tools + * have been executed + */ + private List extractPendingToolCalls() { + List allToolCalls = extractRecentToolCalls(); + if (allToolCalls.isEmpty()) { + return List.of(); + } + + Set pendingIds = getPendingToolUseIds(); + return allToolCalls.stream() + .filter(toolUse -> pendingIds.contains(toolUse.getId())) + .toList(); + } + @Override protected GenerateOptions buildGenerateOptions() { GenerateOptions.Builder builder = GenerateOptions.builder(); diff --git a/agentscope-core/src/test/java/io/agentscope/core/hook/HookStopAgentTest.java b/agentscope-core/src/test/java/io/agentscope/core/hook/HookStopAgentTest.java index 345fa671b..242057d1d 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/hook/HookStopAgentTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/hook/HookStopAgentTest.java @@ -30,6 +30,7 @@ import io.agentscope.core.agent.Agent; import io.agentscope.core.memory.InMemoryMemory; import io.agentscope.core.memory.Memory; +import io.agentscope.core.message.ContentBlock; import io.agentscope.core.message.Msg; import io.agentscope.core.message.MsgRole; import io.agentscope.core.message.TextBlock; @@ -40,6 +41,8 @@ import io.agentscope.core.tool.Toolkit; import io.agentscope.core.util.JsonUtils; import java.time.Duration; +import java.util.ArrayList; +import java.util.List; import java.util.Map; import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicInteger; @@ -488,10 +491,93 @@ public int priority() { } } - // ==================== F. Edge Case Tests ==================== + // ==================== F. Partial Tool Results Tests ==================== @Nested - @DisplayName("F. Edge Case Tests") + @DisplayName("F. Partial Tool Results Tests") + class PartialToolResultsTests { + + @Test + @DisplayName("Partial tool results should NOT cause duplicate tool execution") + void testPartialToolResultsExecution() { + // Track tool execution count + AtomicInteger tool1Count = new AtomicInteger(0); + AtomicInteger tool2Count = new AtomicInteger(0); + + // Register three tools + toolkit.registerTool(new CountingToolClass(tool1Count, tool2Count)); + + // Setup model to return 2 tool calls first, then text response + Msg threeToolsMsg = + createMultipleToolUseMsg( + List.of(Map.entry("call1", "tool1"), Map.entry("call2", "tool2"))); + Msg textResponse = createAssistantTextMsg("All tools completed!"); + + when(mockModel.stream(anyList(), anyList(), any())) + .thenReturn(createFluxFromMsg(threeToolsMsg)) + .thenReturn(createFluxFromMsg(textResponse)); + + // Create hook that stops after reasoning + Hook stopHook = createPostReasoningStopHook(); + + ReActAgent agent = + ReActAgent.builder() + .name("test-agent") + .model(mockModel) + .toolkit(toolkit) + .memory(memory) + .checkRunning(false) + .hook(stopHook) + .build(); + + // First call - gets stopped, returns 2 pending tool calls + Msg result1 = agent.call(createUserMsg("test")).block(TEST_TIMEOUT); + assertTrue( + result1.hasContentBlocks(ToolUseBlock.class), + "First call should return ToolUse message"); + List pendingTools = result1.getContentBlocks(ToolUseBlock.class); + assertEquals(2, pendingTools.size(), "Should have 2 pending tool calls"); + + // Verify no tools executed yet + assertEquals(0, tool1Count.get(), "Tool1 should not be executed yet"); + assertEquals(0, tool2Count.get(), "Tool2 should not be executed yet"); + + // User provides only partial results (tool1) + Msg partialResultMsg = + Msg.builder() + .name("user") + .role(MsgRole.TOOL) + .content( + List.of( + ToolResultBlock.of( + "call1", + "tool1", + TextBlock.builder().text("canceled").build()))) + .build(); + + // Resume with partial results + Msg result2 = agent.call(partialResultMsg).block(TEST_TIMEOUT); + + // BUG: Currently all 2 tools will be executed + // Expected behavior: Only tool2 should be executed + // Actual behavior: All 2 tools are executed + assertTrue( + tool1Count.get() == 0 && tool2Count.get() == 1, + "BUG REPRODUCED: Tools with existing results were re-executed. " + + "tool1Count=" + + tool1Count.get() + + ", tool2Count=" + + tool2Count.get()); + assertTrue( + result1.hasContentBlocks(ToolUseBlock.class), + "First call should return ToolUse message"); + } + } + + // ==================== G. Edge Case Tests ==================== + + @Nested + @DisplayName("G. Edge Case Tests") class EdgeCaseTests { @Test @@ -671,6 +757,27 @@ public Mono onEvent(T event) { }; } + // ==================== Helper Methods for Multiple Tools ==================== + + private Msg createMultipleToolUseMsg(List> toolIdNamePairs) { + List toolUseBlocks = new ArrayList<>(); + for (Map.Entry pair : toolIdNamePairs) { + Map emptyInput = Map.of(); + toolUseBlocks.add( + ToolUseBlock.builder() + .id(pair.getKey()) + .name(pair.getValue()) + .input(emptyInput) + .content(JsonUtils.getJsonCodec().toJson(emptyInput)) + .build()); + } + return Msg.builder() + .name("assistant") + .role(MsgRole.ASSISTANT) + .content(toolUseBlocks) + .build(); + } + // ==================== Test Tool Classes ==================== /** Simple test tool class for verifying tool execution. */ @@ -687,4 +794,27 @@ public ToolResultBlock testTool() { return ToolResultBlock.text("Tool executed"); } } + + /** Tool class that counts executions for testing duplicate calls. */ + static class CountingToolClass { + private final AtomicInteger executionCount1; + private final AtomicInteger executionCount2; + + CountingToolClass(AtomicInteger executionCount1, AtomicInteger executionCount2) { + this.executionCount1 = executionCount1; + this.executionCount2 = executionCount2; + } + + @io.agentscope.core.tool.Tool(name = "tool1", description = "Counting tool 1") + public ToolResultBlock tool1() { + executionCount1.incrementAndGet(); + return ToolResultBlock.text("Tool1 executed: " + executionCount1.get()); + } + + @io.agentscope.core.tool.Tool(name = "tool2", description = "Counting tool 2") + public ToolResultBlock tool2() { + executionCount2.incrementAndGet(); + return ToolResultBlock.text("Tool2 executed: " + executionCount2.get()); + } + } } From 2b581da858e9b0eaa993eebc4ea88e0d13474306 Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Wed, 28 Jan 2026 00:50:34 +0800 Subject: [PATCH 48/53] fix: fix for cr --- .../agent/accumulator/ReasoningContext.java | 25 +++++++++-------- .../io/agentscope/core/tool/ToolExecutor.java | 27 ++++++++----------- 2 files changed, 23 insertions(+), 29 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java index a898580f9..0ccad5701 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java @@ -211,26 +211,25 @@ private Msg buildChunkMsg(ContentBlock block) { * @return The fragment with ID enriched if needed */ private ToolUseBlock enrichToolUseBlockWithId(ToolUseBlock block) { - // If block already has an ID, return as-is (it's a delta fragment) + // If the block already has an ID, return it as-is if (block.getId() != null && !block.getId().isEmpty()) { return block; } - // For fragments without ID, assign the current tool call ID + // Get the current tool call ID from the accumulator String currentId = toolCallsAcc.getCurrentToolCallId(); - if (currentId != null && !currentId.isEmpty()) { - // Return a new block with the ID set, but keeping original content (delta) - return ToolUseBlock.builder() - .id(currentId) - .name(block.getName()) - .input(block.getInput()) - .content(block.getContent()) - .metadata(block.getMetadata()) - .build(); + if (currentId == null || currentId.isEmpty()) { + return block; } - // Fallback: return original block - return block; + // Create a new block with the correct ID + return ToolUseBlock.builder() + .id(currentId) + .name(block.getName()) + .input(block.getInput()) + .content(block.getContent()) + .metadata(block.getMetadata()) + .build(); } /** diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java index baa7df872..4738e33b5 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutor.java @@ -150,22 +150,17 @@ private Mono executeCore(ToolCallParam param) { } } - // Skip parameter validation for schema-only tools - // They will be executed externally, so validation should happen on the client side - boolean isSchemaOnlyTool = tool instanceof SchemaOnlyTool; - if (!isSchemaOnlyTool) { - // Validate input against schema for regular tools - String validationError = - ToolValidator.validateInput(toolCall.getContent(), tool.getParameters()); - if (validationError != null) { - String errorMsg = - String.format( - "Parameter validation failed for tool '%s': %s\n" - + "Please correct the parameters and try again.", - toolCall.getName(), validationError); - logger.debug(errorMsg); - return Mono.just(ToolResultBlock.error(errorMsg)); - } + // Validate input against schema + String validationError = + ToolValidator.validateInput(toolCall.getContent(), tool.getParameters()); + if (validationError != null) { + String errorMsg = + String.format( + "Parameter validation failed for tool '%s': %s\n" + + "Please correct the parameters and try again.", + toolCall.getName(), validationError); + logger.debug(errorMsg); + return Mono.just(ToolResultBlock.error(errorMsg)); } // Merge context From e3e9e33fb1f81b173cf5250d737bc3b8d0dce702 Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Wed, 28 Jan 2026 00:58:13 +0800 Subject: [PATCH 49/53] revert(test): remove unnecessary test method from ReasoningContextTest Remove testToolCallStreamingEmitsDeltaNotAccumulated test as it was added unnecessarily. The test is not required for the core functionality and should not have been part of this PR. Revert to main branch version of ReasoningContextTest.java --- .../accumulator/ReasoningContextTest.java | 48 ------------------- 1 file changed, 48 deletions(-) diff --git a/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java b/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java index de920b425..467b93949 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java @@ -296,52 +296,4 @@ void testToolCallsDoNotBlockTextEmission() { // Verify text is accumulated correctly assertEquals("Let me check the weather for you.", context.getAccumulatedText()); } - - @Test - @DisplayName("Should emit delta fragments not accumulated content for streaming tool calls") - void testToolCallStreamingEmitsDeltaNotAccumulated() { - // First chunk - tool call start with partial arguments - ToolUseBlock toolUse1 = - ToolUseBlock.builder().id("call_1").name("search").content("{\"q").build(); - - // Second chunk - continuation (fragment without ID) - ToolUseBlock toolUse1Fragment1 = - ToolUseBlock.builder().name("__fragment__").content("uery\": \"").build(); - - // Third chunk - completion (fragment without ID) - ToolUseBlock toolUse1Fragment2 = - ToolUseBlock.builder().name("__fragment__").content("test\"}").build(); - - ChatResponse chunk1 = ChatResponse.builder().id("msg-1").content(List.of(toolUse1)).build(); - - ChatResponse chunk2 = - ChatResponse.builder().id("msg-1").content(List.of(toolUse1Fragment1)).build(); - - ChatResponse chunk3 = - ChatResponse.builder().id("msg-1").content(List.of(toolUse1Fragment2)).build(); - - List msgs1 = context.processChunk(chunk1); - List msgs2 = context.processChunk(chunk2); - List msgs3 = context.processChunk(chunk3); - - // All chunks should be emitted - assertEquals(1, msgs1.size()); - assertEquals(1, msgs2.size()); - assertEquals(1, msgs3.size()); - - // Verify emitted chunks contain delta content, not accumulated - ToolUseBlock emitted1 = msgs1.get(0).getFirstContentBlock(ToolUseBlock.class); - assertEquals("{\"q", emitted1.getContent()); - - ToolUseBlock emitted2 = msgs2.get(0).getFirstContentBlock(ToolUseBlock.class); - assertEquals("uery\": \"", emitted2.getContent()); - - ToolUseBlock emitted3 = msgs3.get(0).getFirstContentBlock(ToolUseBlock.class); - assertEquals("test\"}", emitted3.getContent()); - - // Verify accumulated tool call has complete content - ToolUseBlock accumulated = context.getAccumulatedToolCall("call_1"); - assertNotNull(accumulated); - assertEquals("{\"query\": \"test\"}", accumulated.getContent()); - } } From ea3bbd8bc66b4bd5f3b4567dcf91c28d2b8ba85a Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Wed, 28 Jan 2026 01:09:23 +0800 Subject: [PATCH 50/53] refactor(core): revert ReasoningContext to main version and improve code style - Revert ReasoningContext.java to main branch version (only javadoc changes) - Improve exception handling in ToolCallsAccumulator (Exception e -> ignored) Both changes maintain the same functional logic and all tests pass. --- .../core/agent/accumulator/ReasoningContext.java | 12 +++++------- .../core/agent/accumulator/ToolCallsAccumulator.java | 2 +- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java index 0ccad5701..d2cec4a9a 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java @@ -199,16 +199,14 @@ private Msg buildChunkMsg(ContentBlock block) { } /** - * Enrich a ToolUseBlock with accumulated content from the accumulator. + * Enrich a ToolUseBlock with the correct tool call ID. * *

    For fragments (placeholder names like "__fragment__"), the original block may not have - * the correct ID. This method assigns the current tool call ID if missing. + * the correct ID. This method retrieves the ID from the accumulator and creates a new block + * with the correct ID, allowing users to properly concatenate chunks. * - *

    IMPORTANT: For streaming responses, this returns the ORIGINAL fragment (delta), NOT the - * accumulated content. OpenAI's streaming API requires deltas, and clients accumulate them. - * - * @param block The original ToolUseBlock fragment - * @return The fragment with ID enriched if needed + * @param block The original ToolUseBlock + * @return A ToolUseBlock with the correct ID */ private ToolUseBlock enrichToolUseBlockWithId(ToolUseBlock block) { // If the block already has an ID, return it as-is diff --git a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java index 8f6864dff..289e02382 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java +++ b/agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ToolCallsAccumulator.java @@ -96,7 +96,7 @@ ToolUseBlock build() { if (parsed != null) { finalArgs.putAll(parsed); } - } catch (Exception e) { + } catch (Exception ignored) { // Parsing failed, keep empty args } } From 64806316195608c64e2db367984ca272bdfcfdd6 Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Wed, 25 Feb 2026 11:15:57 +0800 Subject: [PATCH 51/53] style: fix spotless format violations Fix code formatting issues in McpClientBuilder and VersionTest to comply with spotless:check requirements. - McpClientBuilder.java: Break long constructor call into multiple lines - VersionTest.java: Break long assertion into multiple lines --- .../java/io/agentscope/core/tool/mcp/McpClientBuilder.java | 4 +++- .../src/test/java/io/agentscope/core/VersionTest.java | 3 ++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java b/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java index 47dd7dcb1..2798721ba 100644 --- a/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java +++ b/agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java @@ -296,7 +296,9 @@ public Mono buildAsync() { McpSchema.Implementation clientInfo = new McpSchema.Implementation( - "agentscope-java", "AgentScope Java Framework", "1.0.10-SNAPSHOT"); + "agentscope-java", + "AgentScope Java Framework", + "1.0.10-SNAPSHOT"); McpSchema.ClientCapabilities clientCapabilities = McpSchema.ClientCapabilities.builder().build(); diff --git a/agentscope-core/src/test/java/io/agentscope/core/VersionTest.java b/agentscope-core/src/test/java/io/agentscope/core/VersionTest.java index a2a4921dd..67cb43be3 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/VersionTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/VersionTest.java @@ -30,7 +30,8 @@ void testVersionConstant() { // Verify version constant is set Assertions.assertNotNull(Version.VERSION, "VERSION constant should not be null"); Assertions.assertFalse(Version.VERSION.isEmpty(), "VERSION constant should not be empty"); - Assertions.assertEquals("1.0.10-SNAPSHOT", Version.VERSION, "VERSION should match current version"); + Assertions.assertEquals( + "1.0.10-SNAPSHOT", Version.VERSION, "VERSION should match current version"); } @Test From cfbe7d07cd3a13db3c260173b260b401d08ef4d9 Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Sun, 1 Mar 2026 17:35:39 +0800 Subject: [PATCH 52/53] fix(test): correct version in McpClientBuilderTest to match project version Update X-Client-Version from 1.0.8 to 1.0.10-SNAPSHOT to align with current project version defined in pom.xml. --- .../java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java index 9cf10195a..f1440a11d 100644 --- a/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java +++ b/agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java @@ -1135,7 +1135,7 @@ void testCustomizeStreamableHttpClient_WithHttp2() { void testCompleteConfiguration_WithClientCustomization() { Map headers = new HashMap<>(); headers.put("Authorization", "Bearer token123"); - headers.put("X-Client-Version", "1.0.8"); + headers.put("X-Client-Version", "1.0.10-SNAPSHOT"); Map queryParams = new HashMap<>(); queryParams.put("tenant", "acme"); From 8e64653701534e9e78de3f85ae87bd625311f7ca Mon Sep 17 00:00:00 2001 From: "alexgangxi@163.com" Date: Sun, 1 Mar 2026 17:45:54 +0800 Subject: [PATCH 53/53] fix(streaming): align finish_reason logic with non-streaming path The streaming path (ChatCompletionsStreamingAdapter) now correctly maps TOOL_SUSPENDED and MAX_ITERATIONS to finish_reason, matching the behavior of the non-streaming path (ChatCompletionsResponseBuilder). Previously, the streaming path only checked for ToolUseBlock presence, which could lead to inconsistent behavior: - TOOL_SUSPENDED was typically unaffected (ToolUseBlock always present) - MAX_ITERATIONS would incorrectly return 'stop' instead of 'length' Changes: - Check event.getMessage().getGenerateReason() in isLast branch - Map TOOL_SUSPENDED -> 'tool_calls' - Map MAX_ITERATIONS -> 'length' - Fall back to ToolUseBlock check for other cases This ensures consistent finish_reason behavior between streaming and non-streaming responses. Resolves review comment from LearningGp. --- .../ChatCompletionsStreamingAdapter.java | 21 ++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java index 800de52ee..fa67d8c69 100644 --- a/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java +++ b/agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/streaming/ChatCompletionsStreamingAdapter.java @@ -24,6 +24,7 @@ import io.agentscope.core.chat.completions.model.ChatCompletionsChunk; import io.agentscope.core.chat.completions.model.ToolCall; import io.agentscope.core.message.ContentBlock; +import io.agentscope.core.message.GenerateReason; import io.agentscope.core.message.Msg; import io.agentscope.core.message.TextBlock; import io.agentscope.core.message.ToolResultBlock; @@ -250,9 +251,23 @@ private Flux convertEventToChunksInternal( // Add finish chunk if this is the last event if (event.isLast()) { - boolean hasToolCalls = - contentBlocks.stream().anyMatch(block -> block instanceof ToolUseBlock); - String finishReason = hasToolCalls ? "tool_calls" : "stop"; + // Determine finish reason based on GenerateReason or tool calls + // This mirrors the logic in ChatCompletionsResponseBuilder + String finishReason; + GenerateReason generateReason = + event.getMessage() != null ? event.getMessage().getGenerateReason() : null; + + if (generateReason == GenerateReason.TOOL_SUSPENDED) { + finishReason = "tool_calls"; + } else if (generateReason == GenerateReason.MAX_ITERATIONS) { + finishReason = "length"; + } else { + // Fall back to checking for tool calls in content + boolean hasToolCalls = + contentBlocks.stream().anyMatch(block -> block instanceof ToolUseBlock); + finishReason = hasToolCalls ? "tool_calls" : "stop"; + } + chunks.add(ChatCompletionsChunk.finishChunk(requestId, model, finishReason)); }