feat(voice-agent-example): implement voice agent pipeline integrating STT, Agent, and TTS via spring-ai-alibaba-extensions. (#445)

feat(voice-agent-example): implement voice agent pipeline integrating STT, Agent, and TTS via spring-ai-alibaba-extensions

Author: buvidk1234

pom.xml

@@ -48,7 +48,7 @@
 		<!-- Spring AI Alibaba -->
 		<!-- Install Spring AI Alibaba in your local. -->
 		<spring-ai-alibaba.version>1.1.0.0</spring-ai-alibaba.version>
-		<spring-ai-alibaba-extensions.version>1.1.2.0</spring-ai-alibaba-extensions.version>
+		<spring-ai-alibaba-extensions.version>1.1.2.1</spring-ai-alibaba-extensions.version>
 
 		<!-- maven plugin -->
 		<maven-deploy-plugin.version>3.1.1</maven-deploy-plugin.version>

spring-ai-alibaba-agent-example/pom.xml

@@ -42,6 +42,7 @@
 		<module>sql-agent-example</module>
 		<module>adk-samples-llm-auditor</module>
 		<module>voice-agent-dashscope-sdk-example</module>
+		<module>voice-agent-example</module>
 	</modules>
 
 	<build>

spring-ai-alibaba-agent-example/voice-agent-example/README.md

@@ -0,0 +1,77 @@
+# Voice Agent Example
+
+基于 Spring AI Alibaba 的语音对话 Agent 示例，实现 Push-to-Talk 模式的 Audio → STT → Agent → TTS → Audio 全链路。
+
+## 功能
+
+- **Push-to-Talk 语音交互**：WebSocket 双向通信，推送录音、流式播放回复
+- **打断控制**：AI 播放中随时点击打断
+- **Reactive Pipeline**：STT → Agent → TTS 基于 Reactor 的流式编排
+- **工具调用**：示例为航班预订助手（查询/改签）
+
+## 快速开始
+
+### 1. 配置 API Key
+
+```bash
+# Linux/Mac
+export AI_DASHSCOPE_API_KEY=sk-xxx
+
+# Windows PowerShell
+$env:AI_DASHSCOPE_API_KEY="sk-xxx"
+```
+
+### 2. 启动
+
+```bash
+mvn spring-boot:run
+```
+
+### 3. 使用
+
+浏览器打开 `http://localhost:8081`，点击 🎤 录音 → 再次点击发送 → AI 语音回复。
+
+## 架构
+
+```
+Browser ──PCM──► VoiceWebSocketHandler ──► VoiceAgentPipeline
+   ◄──PCM+JSON──┘                          │
+                                    ┌──────┴────────────────────────┐
+                                    │ STT (paraformer-realtime-v2)  │
+                                    │      ↓                        │
+                                    │ ReactAgent + Tools            │
+                                    │      ↓                        │
+                                    │ TTS (cosyvoice-v1)            │
+                                    └───────────────────────────────┘
+```
+
+## 项目结构
+
+```
+voice-agent-example/src/main/java/.../voice/
+├── config/
+│   ├── VoiceAgentConfiguration.java  # ReactAgent + Tools 组装
+│   └── WebSocketConfig.java          # WebSocket 端点注册
+├── controller/
+│   ├── PageController.java           # 前端路由
+│   └── VoiceWebSocketHandler.java    # WebSocket 消息处理
+├── service/
+│   ├── VoiceAgentPipeline.java       # 核心管道 STT→Agent→TTS
+│   └── VoiceAgentService.java        # ReactAgent 调用封装
+├── event/                            # Pipeline 事件（sealed interface）
+└── tools/                            # 航班查询/改签工具
+```
+
+## 技术栈
+
+| 组件 | 实现                             |
+|------|--------------------------------|
+| 框架 | Spring Boot 3.x                |
+| AI 集成 | Spring AI Alibaba (ReactAgent) |
+| 流式编排 | Project Reactor                |
+| 实时通信 | WebSocket (PCM 16kHz)          |
+
+## 注意事项
+
+- 端口 `8081`，可在 `application.yml` 修改
+- 浏览器麦克风需 HTTPS 或 localhost

spring-ai-alibaba-agent-example/voice-agent-example/pom.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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>com.alibaba.cloud.ai</groupId>
+        <artifactId>spring-ai-alibaba-agent-example</artifactId>
+        <version>${revision}</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>voice-agent-example</artifactId>
+    <name>Spring AI Alibaba Voice Agent Example</name>
+    <description>Voice Agent Example - STT > Agent > TTS Pipeline</description>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-websocket</artifactId>
+        </dependency>
+
+        <!-- Spring AI Alibaba -->
+        <dependency>
+            <groupId>com.alibaba.cloud.ai</groupId>
+            <artifactId>spring-ai-alibaba-agent-framework</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.alibaba.cloud.ai</groupId>
+            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
+        </dependency>
+
+        <!-- Thymeleaf for HTML templates -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-thymeleaf</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

spring-ai-alibaba-agent-example/voice-agent-example/src/main/java/com/cloud/alibaba/ai/example/agent/voice/Application.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026-2027 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 com.cloud.alibaba.ai.example.agent.voice;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Voice agent bootstrap: Audio -> STT -> Agent -> TTS -> Audio.
+ *
+ * @author buvidk
+ * @since 2026-02-12
+ */
+@SpringBootApplication
+public class Application {
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}

spring-ai-alibaba-agent-example/voice-agent-example/src/main/java/com/cloud/alibaba/ai/example/agent/voice/config/VoiceAgentConfiguration.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026-2027 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 com.cloud.alibaba.ai.example.agent.voice.config;
+
+import com.alibaba.cloud.ai.graph.agent.ReactAgent;
+import com.alibaba.cloud.ai.graph.checkpoint.savers.MemorySaver;
+import com.alibaba.cloud.ai.graph.exception.GraphStateException;
+import com.cloud.alibaba.ai.example.agent.voice.tools.BookingTool;
+import com.cloud.alibaba.ai.example.agent.voice.tools.FlightChangeTool;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Voice Agent Configuration
+ *
+ * @author buvidk
+ * @since 2026-02-12
+ */
+@Configuration
+public class VoiceAgentConfiguration {
+
+    private final ChatModel chatModel;
+    private final BookingTool bookingTool;
+    private final FlightChangeTool flightChangeTool;
+
+    public VoiceAgentConfiguration(ChatModel chatModel, 
+                                 BookingTool bookingTool, 
+                                 FlightChangeTool flightChangeTool) {
+        this.chatModel = chatModel;
+        this.bookingTool = bookingTool;
+        this.flightChangeTool = flightChangeTool;
+    }
+
+    @Bean
+    public ReactAgent voiceReactAgent() throws GraphStateException {
+        return ReactAgent.builder()
+            .name("voice-assistant")
+            .description("""
+                你是一个专业的航空公司语音助手�?
+                
+                你的能力�?
+                1. 查询航班预订详情
+                2. 更改航班日期
+                
+                重要输出规则�?
+                - 只用纯文本，不要�?Markdown、列表符号或表情符号
+                - 保持回复简短，最�?-3句话
+                - 用自然口语化的中文回复，像电话交流一�?
+                - 如果用户没有提供预订号，请礼貌地询问
+                """)
+            .model(chatModel)
+            .saver(new MemorySaver())
+            .tools(bookingTool.toolCallback(), flightChangeTool.toolCallback())
+            .build();
+    }
+}

spring-ai-alibaba-agent-example/voice-agent-example/src/main/java/com/cloud/alibaba/ai/example/agent/voice/config/WebSocketConfig.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026-2027 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 com.cloud.alibaba.ai.example.agent.voice.config;
+
+import com.cloud.alibaba.ai.example.agent.voice.controller.VoiceWebSocketHandler;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.socket.config.annotation.EnableWebSocket;
+import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
+import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;
+import org.springframework.web.socket.server.standard.ServletServerContainerFactoryBean;
+
+/**
+ * WebSocket Configuration
+ *
+ * @author buvidk
+ * @since 2026-02-12
+ */
+@Configuration
+@EnableWebSocket
+public class WebSocketConfig implements WebSocketConfigurer {
+    
+    private final VoiceWebSocketHandler handler;
+
+    public WebSocketConfig(VoiceWebSocketHandler handler) {
+        this.handler = handler;
+    }
+
+    @Override
+    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
+        registry.addHandler(handler, "/ws/voice").setAllowedOrigins("*");
+    }
+
+    @Bean
+    public ServletServerContainerFactoryBean createWebSocketContainer() {
+        ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean();
+        container.setMaxTextMessageBufferSize(1024 * 1024);
+        container.setMaxBinaryMessageBufferSize(1024 * 1024);
+        return container;
+    }
+}

spring-ai-alibaba-agent-example/voice-agent-example/src/main/java/com/cloud/alibaba/ai/example/agent/voice/controller/PageController.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026-2027 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 com.cloud.alibaba.ai.example.agent.voice.controller;
+
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+
+/**
+ * Page Controller for serving frontend pages
+ *
+ * @author buvidk
+ * @since 2026-02-12
+ */
+@Controller
+public class PageController {
+    
+    @GetMapping("/")
+    public String index() {
+        return "index";
+    }
+}