feat(extensions): support chat completions API spring web starter

agentscope-examples/chat-completions-web/pom.xml

@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ 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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.agentscope</groupId>
+        <artifactId>agentscope-examples</artifactId>
+        <version>${revision}</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <groupId>io.agentscope.examples</groupId>
+    <artifactId>chat-completions-web</artifactId>
+    <packaging>jar</packaging>
+
+    <name>AgentScope Examples - Chat Completions Web</name>
+    <description>Example Spring Boot app using the Chat Completions Web Starter</description>
+
+    <dependencyManagement>
+        <dependencies>
+            <!-- Spring Boot BOM -->
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring.boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <dependencies>
+        <!-- AgentScope Core -->
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-core</artifactId>
+        </dependency>
+
+        <!-- Spring Boot Web (MVC) -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- AgentScope Spring Boot auto-configuration (Model / ReActAgent / Toolkit) -->
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-spring-boot-starter</artifactId>
+        </dependency>
+
+        <!-- Chat Completions Web Starter we implemented -->
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-chat-completions-web-starter</artifactId>
+            <version>${revision}</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <version>${spring.boot.version}</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>repackage</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java

@@ -0,0 +1,105 @@
+/*
+ * 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.chatcompletions;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Minimal Spring Boot application demonstrating how to use
+ * {@code agentscope-chat-completions-web-starter}.
+ *
+ * <p>After starting this app, you can call:
+ *
+ * <p>Non-streaming request (stream=false or omitted):
+ *
+ * <pre>
+ * curl -X POST http://localhost:8080/v1/chat/completions \\
+ *   -H 'Content-Type: application/json' \\
+ *   -d '{
+ *     "model": "qwen3-max",
+ *     "stream": false,
+ *     "messages": [
+ *       { "role": "user", "content": "Hello, can you briefly introduce AgentScope Java?" }
+ *     ]
+ *   }'
+ * </pre>
+ *
+ * <p>Streaming request (stream=true, Accept header is optional):
+ *
+ * <pre>
+ * 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": "Please provide a streamed answer: Describe AgentScope Java in three sentences." }
+ *     ]
+ *   }'
+ * </pre>
+ *
+ * <p><b>Important:</b> If stream=false but Accept: text/event-stream is set, the request will be
+ * rejected with an error for consistency. Use stream=true for streaming, or omit the Accept header
+ * for non-streaming.
+ */
+@SpringBootApplication
+public class ChatCompletionsWebApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(ChatCompletionsWebApplication.class, args);
+        printStartupInfo();
+    }
+
+    private static void printStartupInfo() {
+        System.out.println("\n=== chat completions API spring web Example Application Started ===");
+        System.out.println("\nExample curl command:");
+        System.out.println("\nNon-streaming chat completion (stream=false or omitted).\n");
+        System.out.println(
+                """
+                curl -X POST http://localhost:8080/v1/chat/completions \\
+                  -H 'Content-Type: application/json' \\
+                  -d '{
+                    "model": "qwen3-max",
+                    "stream": false,
+                    "messages": [
+                      { "role": "user", "content": "Please provide a Non streamed answer: Describe AgentScope Java in three sentences." }
+                    ]
+                  }'
+                """);
+        System.out.println("\nNote: stream parameter can be omitted (defaults to false)");
+        System.out.println("===================================================");
+        System.out.println("\nStreaming chat completion (stream=true).\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": "Please provide a streamed answer: Describe AgentScope Java in three sentences." }
+                    ]
+                  }'
+                """);
+        System.out.println("\nNote: Accept: text/event-stream header is optional when stream=true");
+        System.out.println("===================================================");
+        System.out.println(
+                "\n⚠️  Important: stream=false with Accept: text/event-stream will return error");
+        System.out.println(
+                "   Use stream=true for streaming, or omit Accept header for non-streaming");
+    }
+}

agentscope-examples/chat-completions-web/src/main/resources/application.yml

@@ -0,0 +1,43 @@
+# 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
+
+logging:
+  level:
+    root: INFO
+    io.agentscope: INFO
+
+agentscope:
+  # Choose model provider - here we use DashScope as an example.
+  model:
+    provider: dashscope
+
+  dashscope:
+    enabled: true
+    api-key: ${DASHSCOPE_API_KEY:YOUR_DASHSCOPE_API_KEY_HERE}
+    model-name: qwen3-max
+    stream: true
+
+  agent:
+    enabled: true
+    name: "ChatCompletionsAgent"
+    sys-prompt: |
+      You are a helpful assistant built with AgentScope Java.
+      Answer in Chinese when the user speaks Chinese, otherwise answer in English.
+    max-iters: 8
+
+  chat-completions:
+    enabled: true
+    base-path: /v1/chat/completions

agentscope-examples/pom.xml

@@ -42,6 +42,7 @@
         <module>werewolf-hitl</module>
         <module>model-request-compression</module>
         <module>boba-tea-shop</module>
+        <module>chat-completions-web</module>
         <module>hitl-chat</module>
     </modules>
 

agentscope-extensions/agentscope-extensions-chat-completions-web/pom.xml

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ 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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.agentscope</groupId>
+        <artifactId>agentscope-extensions</artifactId>
+        <version>${revision}</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+    <artifactId>agentscope-extensions-chat-completions-web</artifactId>
+
+    <name>AgentScope Java - Extensions - Chat Completions Web</name>
+    <description>AgentScope Extensions - Chat Completions Web Protocol Support</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-core</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
+        <!-- Reactor Core for Flux/Mono support -->
+        <!-- Required by ChatCompletionsStreamingAdapter which uses Flux<T> -->
+        <!-- This is a compile-time dependency since agent.stream() returns Flux<Event> -->
+        <dependency>
+            <groupId>io.projectreactor</groupId>
+            <artifactId>reactor-core</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>io.projectreactor</groupId>
+            <artifactId>reactor-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.junit.jupiter</groupId>
+                    <artifactId>junit-jupiter-api</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>