# 第二十章 文字转语音 TTS：用 @Tool 包装上游 SDK，框架不再内置 TTS


>原因：TTS 的业务差异太大。有的团队用火山引擎，有的用阿里云 CosyVoice，有的用 OpenAI。硬塞进框架等于绑死用户。
2.0 的做法：你自己包装上游 SDK 为一个 `@Tool`，agent 调工具拿到音频字节，框架只管调度、不管语音合成。


## 20.1 包装上游 TTS SDK 为 `@Tool`


业务方做三件事：


1. 引入上游 SDK（火山 / 阿里云 CosyVoice / OpenAI TTS / Azure Speech）

2. 写一个 `@Tool` 调用该 SDK

3. 注册到 agent / subagent


例：包装阿里云 CosyVoice SDK 为工具：

```
import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
import io.agentscope.core.message.DataBlock;
import io.agentscope.core.message.Base64Source;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

import java.nio.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class TtsTool {

    private final String apiKey;

    public TtsTool(String apiKey) {
        this.apiKey = apiKey;
    }

    @Tool(name = "tts_synthesize", description = "把文字转成 mp3 音频，返回 DataBlock")
    public DataBlock synthesize(
            @ToolParam(name = "text") String text,
            @ToolParam(name = "voice", required = false) String voice) {

        SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                .apiKey(apiKey)
                .model("cosyvoice-v1")
                .text(text)
                .build();

        SpeechSynthesizer synthesizer = new SpeechSynthesizer();
        ByteBuffer result = synthesizer.call(param);
        byte[] mp3 = new byte[result.remaining()];
        result.get(mp3);

        String b64 = Base64.getEncoder().encodeToString(mp3);
        return DataBlock.builder()
                .source(Base64Source.builder()
                        .data(b64)
                        .mediaType("audio/mp3")
                        .build())
                .name("tts.mp3")
                .build();
    }

    @Tool(name = "tts_to_file", description = "把文字转成 mp3 并写入文件")
    public String synthesizeToFile(
            @ToolParam(name = "text") String text,
            @ToolParam(name = "outPath") String outPath) {

        SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                .apiKey(apiKey)
                .model("cosyvoice-v1")
                .text(text)
                .build();

        SpeechSynthesizer synthesizer = new SpeechSynthesizer();
        ByteBuffer result = synthesizer.call(param);
        byte[] mp3 = new byte[result.remaining()];
        result.get(mp3);

        Files.write(Path.of(outPath), mp3);
        return "已写入 " + outPath;
    }
}
```
注册到 agent：

```
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new TtsTool());                                 // 注册 TTS 包装工具

HarnessAgent agent = HarnessAgent.builder()
        .name("voice_assistant")
        .sysPrompt("你是语音助理，可以用 tts_to_file 把文字转成 mp3 文件。")  // 告诉 LLM 有 TTS 工具可用
        .model(model())
        .workspace(Path.of("./workspace"))
        .toolkit(toolkit)                                            // 传入注册好的工具
        .build();
```
LLM 看到用户要"念给我听"时，**自动**调用 `tts_to_file` 工具——生成的 `tts_output.mp3` 直接用播放器打开就能听到。

>提示：`tts_synthesize` 返回 `DataBlock`，适合把音频推给前端播放；`tts_to_file` 写入磁盘，适合本地验证。


## 20.2 与前端的流式推送


Web 端拿到 `DataBlock` 后：

```
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.toolName === "tts_synthesize") {
    const audioB64 = data.result.media.base64;
    const audioBlob = base64ToBlob(audioB64, "audio/mp3");
    const audio = new Audio(URL.createObjectURL(audioBlob));
    audio.play();
  }
};
```
`agent.streamEvents(...)` 会把 `ToolResultBlock` 推给前端；前端按 `mediaType` 决定是否转成 `<audio>`。

## 20.3 多 TTS 提供商的策略


如果业务同时接火山、OpenAI、CosyVoice，可以在 `tools.json` 里按工具名分别包装：

```
{
  "tools": [
    {
      "name": "tts_cosyvoice",
      "class": "demo.tts.CosyVoiceTool",
      "description": "中文 TTS（CosyVoice）"
    },
    {
      "name": "tts_openai",
      "class": "demo.tts.OpenAiTtsTool",
      "description": "英文 TTS（OpenAI）"
    }
  ]
}
```
主 agent 在 system prompt 里描述路由规则：

```
中文场景用 tts_cosyvoice，英文场景用 tts_openai。
```
## 20.4 完整可运行示例


本地验证时，建议让 agent 直接调用 `tts_to_file`，把 mp3 写到磁盘，这样就能用播放器听到真实语音：

```
public class Chapter20_FullTts {

    public static void main(String[] args) {
        TtsTool ttsTool = new TtsTool();                            // 业务方包装的 TTS 工具（见 20.1 节）

        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(ttsTool);                              // 通过 Toolkit 注册

        String outPath = Path.of("./workspace").resolve("tts_output.mp3").toString();

        HarnessAgent agent = HarnessAgent.builder()
                .name("voice_assistant")
                .sysPrompt("""
                        你是语音助理。
                        用户让你"念" / "读" / "播放"某段文字时，
                        调 tts_to_file 把 mp3 保存到：
                        """ + outPath)
                .model(model())
                .workspace(Path.of("./workspace"))
                .toolkit(toolkit)                                   // 传入注册好的工具
                .build();

        String reply = agent.call(
                        new UserMessage("把'杭州今天 22 度'念给我听，保存成 mp3 文件。"),
                        RuntimeContext.empty())                     // 无 session，单次调完即走
                .block()
                .getTextContent();

        System.out.println(reply);
        System.out.println("音频已保存：" + outPath);                  // 可直接用播放器打开
    }
}
```
运行后打开 `./workspace/tts_output.mp3` 即可听到合成语音。

## 20.5 本章小结


- 2.0 移除了内置 TTS 模块。推荐业务方包装上游 SDK 为 `@Tool`。

- 本地验证用 `tts_to_file` 把 mp3 写到磁盘，可直接播放；上线后可用 `tts_synthesize` 返回 `DataBlock` 推给前端。

- 多个 TTS 提供商共存时，按工具名路由即可。

原因：TTS 的业务差异太大。有的团队用火山引擎，有的用阿里云 CosyVoice，有的用 OpenAI。硬塞进框架等于绑死用户。

【AgentScope Java新手村系列】（20）文字转语音TTS

AgentScope 2.0 移除内置 TTS，教你用 @Tool 包装 DashScope CosyVoice，把文字合成 mp3 写入文件，运行后可直接播放验证。

编程语言

后端

开发工具

本文介绍如何通过@Tool包装不同TTS服务商SDK实现灵活的文字转语音功能。框架不再内置TTS模块，业务方可自由接入火山引擎、阿里云CosyVoice或OpenAI等TTS服务。详细展示了包装阿里云SDK为工具类、注册到agent、前端音频播放及多TTS服务商路由策略的实现方法，提供完整可运行示例代码。

语音合成

代码解释

路由

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【AgentScope Java新手村系列】（20）文字转语音TTS-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（20）文字转语音TTS

【AgentScope Java新手村系列】（20）文字转语音TTS

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐