Feat/chat completions api web starter

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

@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2024-2025 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,95 @@
+/*
+ * Copyright 2024-2025 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:
+ *
+ * <pre>
+ * curl -X POST http://localhost:8080/v1/chat/completions \\
+ *   -H 'Content-Type: application/json' \\
+ *   -d '{
+ *     "model": "qwen3-max",
+ *     "sessionId": "demo-user",
+ *     "messages": [
+ *       { "role": "user", "content": "Hello, can you briefly introduce AgentScope Java?" }
+ *     ]
+ *   }'
+ * </pre>
+ *
+ * Or streaming (SSE):
+ *
+ * <pre>
+ * curl -N http://localhost:8080/v1/chat/completions \\
+ *   -H 'Content-Type: application/json' \\
+ *   -H 'Accept: text/event-stream' \\
+ *   -d '{
+ *     "model": "qwen3-max",
+ *     "stream": true,
+ *     "sessionId": "demo-user",
+ *     "messages": [
+ *       { "role": "user", "content": "Please provide a streamed answer: Describe AgentScope Java in three sentences." }
+ *     ]
+ *   }'
+ * </pre>
+ */
+@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.\n");
+        System.out.println(
+                """
+                curl -X POST http://localhost:8080/v1/chat/completions \\
+                  -H 'Content-Type: application/json' \\
+                  -d '{
+                    "model": "qwen3-max",
+                    "sessionId": "demo-user",
+                    "messages": [
+                      { "role": "user", "content": "Please provide a Non streamed answer: Describe AgentScope Java in three sentences." }
+                    ]
+                  }'
+                """);
+        System.out.println("===================================================");
+        System.out.println("\nStreaming chat completion.\n");
+        System.out.println(
+                """
+                curl -N http://localhost:8080/v1/chat/completions \\
+                  -H 'Content-Type: application/json' \\
+                  -H 'Accept: text/event-stream' \\
+                  -d '{
+                    "model": "qwen3-max",
+                    "sessionId": "demo-user",
+                    "messages": [
+                      { "role": "user", "content": "Please provide a streamed answer: Describe AgentScope Java in three sentences." }
+                    ]
+                  }'
+                """);
+    }
+}

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

@@ -0,0 +1,43 @@
+# Copyright 2024-2025 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>
     </modules>
 
     <properties>

agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/pom.xml

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2024-2025 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.
+-->
+<!--
+  Chat Completions Web Starter
+  - Provides standardized HTTP Chat Completions API based on AgentScope ReActAgent.
+-->
+<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-spring-boot-starters</artifactId>
+        <version>${revision}</version>
+    </parent>
+
+    <artifactId>agentscope-chat-completions-web-starter</artifactId>
+    <name>AgentScope Java - Chat Completions Web Starter</name>
+    <description>Spring Boot starter exposing a Chat Completions style HTTP API for AgentScope agents</description>
+
+    <properties>
+        <spring-boot.version>4.0.1</spring-boot.version>
+        <maven.deploy.skip>false</maven.deploy.skip>
+    </properties>
+
+    <dependencies>
+        <!-- AgentScope Core -->
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-core</artifactId>
+            <optional>true</optional>
+            <scope>provided</scope>
+        </dependency>
+
+        <!-- Reuse core Spring Boot starter for AgentScope configuration -->
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-spring-boot-starter</artifactId>
+        </dependency>
+
+        <!-- Spring Web (MVC) for HTTP endpoint exposure -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- Validation support -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+
+        <!-- Configuration metadata -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-configuration-processor</artifactId>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

agentscope-extensions/agentscope-spring-boot-starters/agentscope-chat-completions-web-starter/src/main/java/io/agentscope/spring/boot/chat/api/ChatChoice.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024-2025 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.spring.boot.chat.api;
+
+/** Single choice in a Chat Completions style response. */
+public class ChatChoice {
+
+    private int index;
+
+    private ChatMessage message;
+
+    private String finishReason;
+
+    public int getIndex() {
+        return index;
+    }
+
+    public void setIndex(int index) {
+        this.index = index;
+    }
+
+    public ChatMessage getMessage() {
+        return message;
+    }
+
+    public void setMessage(ChatMessage message) {
+        this.message = message;
+    }
+
+    public String getFinishReason() {
+        return finishReason;
+    }
+
+    public void setFinishReason(String finishReason) {
+        this.finishReason = finishReason;
+    }
+}