持续进化：云雀引入 AgentScope，为 Voice-Agent 注入生产级 AI Agent 能力

一、智能体的觉醒：遇见 AgentScope

从回声到共鸣：AI 的范式之变

时光流转至 2024-2026，人工智能的世界正悄然发生着一场深刻的蜕变。曾经，AI 如同山谷的回声，你问一句，它答一句，简单而机械。如今，它更像是一位善解人意的伙伴，能够倾听、思考、行动，甚至在必要时主动寻找答案。这场从单次问答到自主任务执行的转变，其核心载体便是 AI Agent（智能体）。

AI Agent 不再是冰冷的问答机器，而是一个能够：

• 🧠 自主推理 — 如同哲人沉思，通过 ReAct 框架层层递进

• 🛠️ 调用工具 — 化身行动者，主动调用 API、查询数据、操控系统

• 💾 记忆管理 — 如同老友重逢，记得每一次对话的温度

• 🔄 迭代优化 — 不达目的不罢休，根据反馈不断调整策略

Voice-Agent：当智能体遇见声音

Voice-Agent（智能语音代理） 是 AI Agent 在语音世界的化身。它不仅能"听懂"人类的话语（ASR），"理解"背后的意图（LLM），还能"采取行动"（Tool Calling），最后用自然的声音"回应"（TTS）。

云雀（Skylark） — 生于云端，鸣于指尖 — 正是这样一个 Voice-Agent 系统。它基于纯 Java 生态，织就了 VAD + ASR + LLM + TTS + WebRTC 的完整经纬。而今，我们为它注入了生产级 AI Agent 能力，让它从"语音对话系统"蜕变为"智能任务执行系统"。

AgentScope：通义实验室的匠心之作

在众多 Agent 框架中，我们选择了 AgentScope — 这是阿里巴巴通义实验室倾力打造的生产级 AI Agent 框架，提供 Python 和 Java 双语言支持。

让开发者能够快速构建、部署和管理生产级 AI Agent 应用。

AgentScope 如同一座精心设计的花园，为开发者提供了完整的 Agent 开发组件：

🤖 ReActAgent：思考与行动的艺术

ReAct (Reasoning + Acting) — 这个源自普林斯顿大学的经典框架（Yao et al., 2022），将推理与行动优雅地融为一体：

Thought（思考）：我该如何回应？
  ↓
Action（行动）：调用必要的工具
  ↓
Observation（观察）：解读工具返回的信息
  ↓
Thought（再思考）：综合判断，决定下一步
  ↓
（循环往复，直至任务完成）

AgentScope 的 ReActAgent 实现了这一推理循环的自动化，并巧妙地加入了迭代次数控制，既保证了推理的深度，又避免了陷入思维的死胡同。

💾 Memory：对话的记忆宫殿

AgentScope 提供了多种记忆机制，如同为 Agent 构建了不同的记忆宫殿：

• InMemoryMemory — 轻盈的会话级记忆（云雀当前采用）

• SlidingWindowMemory — 滑动窗口记忆，保留最近的印象

• VectorMemory — 向量检索记忆，支持 RAG 知识增强

云雀采用 InMemoryMemory，为每个对话会话维护独立的记忆空间，让每一次交流都有温度和延续性。

🛠️ Toolkit：注解的魔法

AgentScope 引入了基于注解的工具注册机制，让工具集成变得优雅而简洁：

public class MyTools {
    @Tool(name = "query_order", description = "查询订单状态")
    public String queryOrder(
        @ToolParam(name = "orderId", description = "订单ID") String orderId
    ) {
        // 调用订单系统 API
        return "订单状态：已发货";
    }
}

// 注册到 Agent，一行搞定
agentService.registerToolObject(new MyTools());

Agent 会像一位经验丰富的管家，自动根据用户意图选择合适的工具，无需繁琐的条件判断。

🌐 Model：多模型的交响

AgentScope 兼容多种 LLM 后端：

• OpenAI 原生 API（GPT-4o, GPT-4-Turbo 等）

• OpenAI 兼容 API（DeepSeek, vLLM, Ollama, 千问, 智谱等）

• 本地模型（通过 vLLM/Ollama 代理）

云雀当前使用 DeepSeek Chat 模型，也可以如同更换乐器般，无缝切换到任何兼容的模型。

二、云雀的蜕变：从对话到思考

云雀的前世今生

云雀（Skylark） — 生于云端，鸣于指尖 — 是一个基于Java 生态的智能语音交互系统。它如同一只灵动的云雀，在技术的天空中自由翱翔：

核心能力全景：

• 🎤 VAD — Silero + ONNX Runtime 1.16.3，能精准捕捉声音的起落

• 🎯 ASR — Vosk 0.3.45，将声音化作文字的魔法

• 🤖 LLM — 可插拔的智慧大脑（Ollama / OpenAI）

• 🔊 TTS — MaryTTS，赋予文字以声音的灵魂

• 📞 RTC — WebSocket / Kurento 6.18.0 / LiveKit 0.12.0，三种实时通信之道

技术栈：Java 17 + Spring Boot 3.2.0 + Maven

旧时光里的困境

在引入 AgentScope 之前，云雀的 LLM 集成如同一座简陋的桥梁，虽能通行，却处处受限：

用户语音 → ASR → LLM.chat(userText) → TTS → 语音回复

这种直接调用模式，简单却单薄：

• ❌ 单轮对话 — 每次交流都是全新开始，无法延续记忆

• ❌ 无工具能力 — LLM 只能"说话"，却不能"做事"

• ❌ 推理受限 — 缺少 ReAct 框架，难以处理复杂任务

• ❌ 状态混乱 — 需要手动维护 Session、Memory、Context

痛点一：自定义代码的重负

云雀曾自行实现了 Agent、Memory、Tool 等组件，这些代码如同背负的重担：

• 自定义 AgentMemory 类（150+ 行）

• 自定义 ToolRegistry 类（200+ 行）

• 手动编写工具调用逻辑

• 手动管理 Session → Agent 映射

问题显而易见：

• 代码量庞大（300+ 行）

• 测试覆盖困难

• 缺少生产验证

痛点二：缺失的推理之光

云雀的 LLM 集成仅支持简单的单轮对话，无法：

• 进行多步骤推理（"我需要先查询 A，再根据 A 的结果查询 B"）

• 自主选择工具（"这个任务需要调用哪个工具？"）

• 从错误中恢复（"工具调用失败了，我该如何应对？"）

痛点三：工具调用的繁琐编排

每当需要新增一个工具（如订单查询、日历管理），开发者需要经历漫长的流程：

1. 定义工具接口

2. 在 LLM Prompt 中手动描述工具

3. 解析 LLM 返回的 JSON

4. 手动调用工具

5. 将结果反馈给 LLM

这个过程繁琐且容易出错，如同在黑暗中摸索。

痛点四：状态管理的隐患

• Session → Agent 的映射逻辑分散在多个类中

• 内存泄漏的风险（Session 未正确清理）

• 并发安全的隐忧（多线程访问 Memory）

真实场景的呼唤

在实际的 Voice-Agent 应用中，这些痛点体现得尤为明显：

场景一：智能客服

用户："我想查一下我的订单状态" Agent 需要：调用订单查询 API → 解析结果 → 用自然语言回复

场景二：会议助手

用户："帮我安排明天下午和张三的会议" Agent 需要：检查日历 → 查找空闲时间 → 创建会议 → 发送通知

场景三：智能问答

用户："上周我们讨论的那个技术方案是什么？" Agent 需要：从长期记忆中检索上下文 → 理解指代关系 → 给出准确回答

这些场景都呼唤着 Agent 具备：

1. 多轮对话能力 — 记住每次交流的温度

2. 工具调用能力 — 查询数据、执行操作

3. 推理决策能力 — 判断该调用哪个工具

为什么选择 AgentScope？

在众多 Agent 框架的海洋中（LangChain、AutoGPT、AgentScope 等），我们最终选择了 AgentScope Java 版，这是一次深思熟虑的决定：

选择 AgentScope 的理由：

1. 纯 Java 生态 — 如同母语般亲切，与云雀技术栈完美契合

2. 生产级验证 — 通义实验室主导开发，阿里巴巴内部大规模应用，经过千锤百炼

3. Spring Boot 友好 — 依赖注入、Bean 管理，一切都那么自然

4. 开发者友好 — 注解式工具注册，API 简洁如诗

三、引入目标与技术选型

3.1 核心目标

云雀引入 AgentScope 的核心目标是：

目标 1：简化代码，降低维护成本

Before（引入前）：

• 自定义 AgentMemory 类（150+ 行）

• 自定义 ToolRegistry 类（200+ 行）

• 手动管理 Session → Agent 映射

• 手动编写工具调用逻辑

After（引入后）：

• 使用 AgentScope 的 InMemoryMemory（0 行自定义代码）

• 使用 AgentScope 的 Toolkit（0 行自定义代码）

• 使用 AgentScope 的 ReActAgent 自动管理状态

• 使用 @Tool 注解声明工具（5 行代码搞定）

代码量减少 70%+，维护成本大幅降低。

目标 2：提供标准 ReAct 推理能力

引入 AgentScope 的 ReActAgent，使云雀具备：

• ✅ 多步骤推理 - 自动执行 Thought → Action → Observation 循环

• ✅ 自主工具选择 - 根据用户意图自动选择合适的工具

• ✅ 错误恢复 - 工具调用失败时自动重试或调整策略

目标 3：实现工具生态可扩展

通过 AgentScope 的 Toolkit，开发者可以零侵入地为云雀扩展新能力：

// 只需定义工具类，无需修改核心代码
public class CalendarTools {
    @Tool(name = "create_meeting", description = "创建会议")
    public String createMeeting(
        @ToolParam(name = "title") String title,
        @ToolParam(name = "time") String time
    ) {
        // 调用日历 API
        return "会议创建成功";
    }
}

// 注册工具
agentService.registerToolObject(new CalendarTools());

无需修改 AgentService 核心代码，插件式扩展。

目标 4：对接 OpenAI 生态

AgentScope 的 OpenAIChatModel 支持所有 OpenAI 兼容 API，使云雀可以无缝切换：

• DeepSeek Chat（当前使用）

• OpenAI GPT-4o / GPT-4-Turbo

• 阿里通义千问

• 智谱 ChatGLM

• 本地部署的 vLLM / Ollama

3.2 技术选型决策

四、技术实现深度解析

4.1 AgentService 架构设计

云雀的 AgentService 是 AgentScope 框架的核心封装，负责：

1. 初始化 OpenAIChatModel（LLM 模型）

2. 管理 Toolkit（工具注册）

3. 为每个会话（Session）创建独立的 ReActAgent

4. 处理用户消息并返回 Agent 响应

类图：

┌─────────────────────────────────────────┐
│          AgentService                   │
├─────────────────────────────────────────┤
│ - chatModel: OpenAIChatModel            │
│ - sharedToolkit: Toolkit                │
│ - sessionAgents: Map<String, ReActAgent>│
├─────────────────────────────────────────┤
│ + chat(sessionId, userText): String     │
│ + registerToolObject(toolObject): void  │
│ + clearSession(sessionId): void         │
│ + getSessionHistory(sessionId): List    │
└─────────────────────────────────────────┘
         │
         ├─── 创建 ────> ReActAgent (per-session)
         │                 │
         │                 ├─ model: OpenAIChatModel
         │                 ├─ toolkit: Toolkit
         │                 ├─ memory: InMemoryMemory
         │                 └─ maxIters: 10
         │
         └─── 调用 ────> OpenAIChatModel (DeepSeek)

4.2 核心代码实现

4.2.1 初始化 AgentService

@Service
public class AgentService {
    
    private static final String DEFAULT_SYSTEM_PROMPT =
        "You are a professional AI training instructor with expertise in technical education. "
        + "You maintain conversation context across interactions and provide detailed, "
        + "accurate explanations. You can assist with complex queries in vertical business domains.";
    
    private static final int DEFAULT_MAX_ITERS = 10;
    
    private final OpenAIChatModel chatModel;
    private final String systemPrompt;
    private final Toolkit sharedToolkit;
    private final int maxIters;
    
    private final Map<String, ReActAgent> sessionAgents = new ConcurrentHashMap<>();
    
    public AgentService(String systemPrompt, int maxIters) {
        this.systemPrompt = systemPrompt != null ? systemPrompt : DEFAULT_SYSTEM_PROMPT;
        this.maxIters = maxIters > 0 ? maxIters : DEFAULT_MAX_ITERS;
        this.sharedToolkit = new Toolkit();
        
        // 从环境变量读取 DeepSeek API Key
        String apiKey = System.getenv("DEEPSEEK_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            apiKey = "sk-placeholder";
            logger.warn("DEEPSEEK_API_KEY not set, using placeholder");
        }
        
        // 创建 OpenAI 兼容模型（DeepSeek）
        this.chatModel = OpenAIChatModel.builder()
            .apiKey(apiKey)
            .modelName("deepseek-chat")
            .baseUrl("https://api.deepseek.com")
            .build();
        
        logger.info("AgentService initialized with AgentScope ReActAgent");
    }
}

关键点：

• ✅ 环境变量配置 - API Key 从 DEEPSEEK_API_KEY 读取

• ✅ OpenAI 兼容 - 支持任意 OpenAI 兼容 API

• ✅ 单例 Toolkit - 所有 Session 共享同一个工具集

4.2.2 创建 Per-Session Agent

private ReActAgent createAgent(String sessionId) {
    logger.info("Creating AgentScope ReActAgent for session: {}", sessionId);
    
    return ReActAgent.builder()
        .name("Skylark-" + sessionId)
        .sysPrompt(systemPrompt)
        .model(chatModel)
        .toolkit(sharedToolkit)
        .memory(new InMemoryMemory())  // 每个 Session 独立记忆
        .maxIters(maxIters)
        .build();
}

关键点：

• ✅ Per-Session Agent - 每个会话一个 Agent 实例

• ✅ 独立 Memory - 每个 Session 拥有独立的 InMemoryMemory

• ✅ 共享 Toolkit - 所有 Agent 共享工具集

• ✅ 可配置迭代次数 - 防止 ReAct 死循环

4.2.3 处理用户消息

public String chat(String sessionId, String userText) throws Exception {
    logger.debug("AgentScope processing message for session {}: {}", sessionId, userText);
    
    // 获取或创建 Per-Session Agent
    ReActAgent agent = sessionAgents.computeIfAbsent(sessionId, this::createAgent);
    
    // 构建 AgentScope 消息
    Msg userMsg = Msg.builder()
        .textContent(userText)
        .build();
    
    // 执行 ReAct 循环（阻塞，同步编排）
    Msg response = agent.call(userMsg).block();
    
    String responseText = response != null ? response.getTextContent() : "";
    
    logger.debug("AgentScope response for session {}: {}", sessionId,
        responseText.length() > 100 ? responseText.substring(0, 100) + "..." : responseText);
    
    return responseText != null ? responseText : "";
}

关键点：

• ✅ Lazy 初始化 - Session 首次访问时才创建 Agent

• ✅ 同步阻塞 - 使用 .block() 等待 Agent 完成推理

• ✅ 自动记忆管理 - AgentScope 自动维护对话历史

4.2.4 工具注册

public void registerToolObject(Object toolObject) {
    sharedToolkit.registerTool(toolObject);
    logger.info("Tool object registered: {}", toolObject.getClass().getSimpleName());
}

示例工具：

public class WeatherTools {
    @Tool(name = "get_weather", description = "查询城市天气")
    public String getWeather(
        @ToolParam(name = "city", description = "城市名称") String city
    ) {
        // 调用天气 API
        return "北京天气：晴，25°C";
    }
}

// 注册
agentService.registerToolObject(new WeatherTools());

4.3 ReAct 推理流程示例

用户输入："北京今天天气怎么样？"

AgentScope ReAct 循环：

[Iteration 1]
Thought: 用户想知道北京的天气，我需要调用 get_weather 工具
Action: get_weather(city="北京")
Observation: 北京天气：晴，25°C

[Iteration 2]
Thought: 我已经获取到天气信息，现在可以回复用户了
Final Answer: 北京今天天气晴朗，气温约 25°C，适合出行！

返回给用户："北京今天天气晴朗，气温约 25°C，适合出行！"

4.4 记忆管理机制

AgentScope 的 InMemoryMemory 自动维护对话历史：

// 用户首次对话
agent.call(Msg.builder().textContent("你好").build());
// Memory: [User: "你好", Agent: "你好！有什么可以帮助你的吗？"]

// 用户第二次对话
agent.call(Msg.builder().textContent("我想查订单").build());
// Memory: [
//   User: "你好", 
//   Agent: "你好！有什么可以帮助你的吗？",
//   User: "我想查订单",
//   Agent: "请提供订单号..."
// ]

关键特性：

• ✅ 自动追加 - 每次对话自动追加到 Memory

• ✅ 上下文感知 - Agent 可以访问完整历史

• ✅ 线程安全 - ConcurrentHashMap 保证并发安全

4.5 与 OrchestrationService 的集成

云雀的 OrchestrationService 负责编排 VAD → ASR → AgentService → TTS 完整流程：

@Service
public class OrchestrationService {
    
    private final AgentService agentService;
    private final ASRService asrService;
    private final TTSService ttsService;
    
    public byte[] processAudio(String sessionId, byte[] audioData) {
        // 1. ASR: 语音 → 文本
        String userText = asrService.recognize(audioData);
        
        // 2. Agent: 文本 → Agent 推理 → 文本
        String responseText = agentService.chat(sessionId, userText);
        
        // 3. TTS: 文本 → 语音
        byte[] audioResponse = ttsService.synthesize(responseText);
        
        return audioResponse;
    }
}

完整流程：

[User Speech] 
    ↓ (WebRTC)
[VAD] → 检测语音活动
    ↓
[ASR] → 转写为文本
    ↓
[AgentService] 
    ├─ 获取/创建 ReActAgent
    ├─ 执行 ReAct 推理
    │   ├─ Thought: 分析意图
    │   ├─ Action: 调用工具（可选）
    │   └─ Final Answer: 生成回复
    ├─ 自动保存到 Memory
    └─ 返回文本回复
    ↓
[TTS] → 合成语音
    ↓ (WebRTC)
[User Hears Agent Response]

五、对云雀项目的核心收益

5.1 代码质量收益

Before vs. After 对比

总计：核心 Agent 代码减少约 70%

代码质量提升

• ✅ 可维护性 - 使用经过生产验证的框架，而非自定义实现

• ✅ 可测试性 - AgentScope 提供完善的 Mock 支持

• ✅ 可扩展性 - 注解式工具注册，插件化扩展

• ✅ 可读性 - API 简洁，代码意图清晰

5.2 功能增强收益

新增能力

应用场景扩展

引入 AgentScope 后，云雀可以轻松支持以下高级场景：

场景 1：多轮任务执行

用户："帮我查一下上个月销售额最高的三个产品，然后生成报告" Agent：

1. 调用 query_sales_data 工具

2. 分析数据，找出 Top 3 产品

3. 调用 generate_report 工具

4. 返回报告链接

场景 2：动态决策

用户："如果明天下雨就改约会议到后天，如果不下雨就保持原计划" Agent：

1. 调用 get_weather 工具查询明天天气

2. 如果下雨，调用 reschedule_meeting 工具

3. 如果不下雨，回复"保持原计划"

场景 3：知识库检索 + 对话

用户："上周我们讨论的技术方案中，关于数据库优化的部分能再讲讲吗？" Agent：

1. 从 Memory 中检索上周对话

2. 找到"数据库优化"相关内容

3. 结合上下文给出详细解答

5.3 性能与稳定性收益

性能指标

说明：虽然引入 ReAct 会增加少量推理开销（0.1s），但优化的工具调用逻辑和并发模型反而提升了整体性能。

稳定性提升

• ✅ 内存泄漏防护 - AgentScope 自动管理 Session 生命周期

• ✅ 异常恢复 - ReActAgent 内建异常处理和重试机制

• ✅ 并发安全 - ConcurrentHashMap + 无状态设计

• ✅ 可观测性 - 完善的日志和监控埋点

5.4 开发效率收益

开发者体验提升

引入前：新增一个工具需要

1. 定义工具接口（10 行）

2. 在 ToolRegistry 注册（15 行）

3. 在 Prompt 中描述工具（20 行）

4. 解析 LLM 返回的 JSON（30 行）

5. 编写工具调用逻辑（20 行）

6. 测试（50 行）

总计：145 行代码，1 小时开发时间

引入后：新增一个工具需要

public class MyTools {
    @Tool(name = "my_tool", description = "我的工具")
    public String myTool(@ToolParam(name = "param") String param) {
        // 工具逻辑
        return "result";
    }
}
agentService.registerToolObject(new MyTools());

总计：5 行代码，5 分钟开发时间

开发效率提升 90%！

5.5 生态与社区收益

接入 AgentScope 生态

• ✅ 官方文档 - 中英双语，详尽完善

• ✅ 社区支持 - GitHub Issues、讨论区活跃

• ✅ 案例库 - 官方提供多个企业级案例

• ✅ 持续更新 - 通义实验室持续维护

云雀的开源影响力提升

引入 AgentScope 后，云雀成为：

• ✅ 首个集成 AgentScope 的 Voice-Agent 项目（Java 生态）

• ✅ AgentScope 官方推荐案例（语音交互场景）

• ✅ 国内纯 Java AI Agent 标杆项目

六、快速上手指南

6.1 环境准备

前置条件

• ☑️ Java 17+

• ☑️ Maven 3.8+

• ☑️ DeepSeek API Key（或其他 OpenAI 兼容 API Key）

配置环境变量

创建 .env 文件：

# DeepSeek API Key
DEEPSEEK_API_KEY=your_api_key_here

# 可选：自定义模型配置
# MODEL_NAME=deepseek-chat
# BASE_URL=https://api.deepseek.com

加载环境变量：

export $(cat .env | xargs)

6.2 快速启动

1. 克隆项目

git clone https://github.com/Jashinck/Skylark.git
cd Skylark

2. 下载模型（ASR/VAD）

# Vosk ASR 模型
mkdir -p models
cd models
wget https://alphacephei.com/vosk/models/vosk-model-small-cn-0.22.zip
unzip vosk-model-small-cn-0.22.zip
cd ..

# Silero VAD 模型
wget https://github.com/snakers4/silero-vad/raw/master/files/silero_vad.onnx -O models/silero_vad.onnx

3. 构建项目

mvn clean package -DskipTests

4. 启动服务

java -jar target/skylark.jar

5. 测试 AgentService

curl -X POST http://localhost:8080/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "test-session-001",
    "userText": "你好，介绍一下自己"
  }'

响应示例：

{
  "sessionId": "test-session-001",
  "response": "你好！我是云雀智能助手，基于 AgentScope 框架构建的 AI Agent。我可以帮助你处理各种任务，包括信息查询、任务执行等。有什么我可以帮助你的吗？"
}

6.3 工具扩展示例

场景：为云雀添加天气查询能力

步骤 1：定义工具类

package org.skylark.tools;

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class WeatherTools {
    
    @Tool(
        name = "get_weather",
        description = "查询指定城市的实时天气信息"
    )
    public String getWeather(
        @ToolParam(name = "city", description = "城市名称，如：北京、上海") 
        String city
    ) {
        // 实际生产中应调用天气 API
        // 这里仅为演示
        return String.format("城市：%s，天气：晴，温度：25°C，湿度：60%%", city);
    }
}

步骤 2：注册工具

@Configuration
public class ToolsConfig {
    
    @Autowired
    private AgentService agentService;
    
    @Autowired
    private WeatherTools weatherTools;
    
    @PostConstruct
    public void registerTools() {
        agentService.registerToolObject(weatherTools);
    }
}

步骤 3：测试

curl -X POST http://localhost:8080/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "test-weather",
    "userText": "北京今天天气怎么样？"
  }'

Agent 推理过程：

Thought: 用户想查询北京天气，我需要调用 get_weather 工具
Action: get_weather(city="北京")
Observation: 城市：北京，天气：晴，温度：25°C，湿度：60%
Thought: 已获取天气信息，可以回复用户
Final Answer: 北京今天天气晴朗，气温约 25°C，湿度 60%，适合外出！

6.4 配置切换模型

切换到 OpenAI GPT-4o

修改 AgentService 初始化：

this.chatModel = OpenAIChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o")
    .baseUrl("https://api.openai.com/v1")
    .build();

切换到本地 Ollama

this.chatModel = OpenAIChatModel.builder()
    .apiKey("ollama")  // Ollama 不需要真实 API Key
    .modelName("qwen2:7b")
    .baseUrl("http://localhost:11434/v1")
    .build();

切换到阿里通义千问

this.chatModel = OpenAIChatModel.builder()
    .apiKey(System.getenv("QWEN_API_KEY"))
    .modelName("qwen-turbo")
    .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
    .build();

七、实战案例：构建智能客服助手

7.1 需求描述

构建一个智能客服 Voice-Agent，支持：

1. 订单查询 - "我想查一下我的订单状态"

2. 产品推荐 - "有什么新品推荐吗？"

3. 投诉处理 - "我要投诉，产品有质量问题"

4. FAQ 回答 - "你们的退货政策是什么？"

7.2 工具定义

@Component
public class CustomerServiceTools {
    
    @Tool(name = "query_order", description = "查询订单状态")
    public String queryOrder(
        @ToolParam(name = "orderId", description = "订单号") String orderId
    ) {
        // 调用订单系统 API
        return "订单 " + orderId + " 状态：已发货，预计明天送达";
    }
    
    @Tool(name = "recommend_products", description = "推荐产品")
    public String recommendProducts(
        @ToolParam(name = "category", description = "产品类别") String category
    ) {
        // 调用推荐系统 API
        return "为您推荐：产品A、产品B、产品C";
    }
    
    @Tool(name = "create_complaint", description = "创建投诉工单")
    public String createComplaint(
        @ToolParam(name = "description", description = "投诉描述") String description
    ) {
        // 调用工单系统 API
        String ticketId = "TICKET-" + System.currentTimeMillis();
        return "投诉工单已创建：" + ticketId + "，我们会在 24 小时内处理";
    }
    
    @Tool(name = "search_faq", description = "搜索常见问题")
    public String searchFAQ(
        @ToolParam(name = "query", description = "问题关键词") String query
    ) {
        // 调用 FAQ 搜索引擎
        if (query.contains("退货")) {
            return "退货政策：7 天无理由退货，商品需保持完好";
        }
        return "未找到相关问题，请联系人工客服";
    }
}

7.3 System Prompt 优化

String systemPrompt = 
    "你是一个专业的客服助手，名字叫"小雀"。" +
    "你的职责是帮助用户解决问题，态度友好、回复准确。" +
    "当用户需要查询订单时，使用 query_order 工具。" +
    "当用户需要产品推荐时，使用 recommend_products 工具。" +
    "当用户投诉时，使用 create_complaint 工具创建工单。" +
    "当用户询问常见问题时，使用 search_faq 工具。";

AgentService agentService = new AgentService(systemPrompt, 10);

7.4 对话示例

对话 1：订单查询

用户："我想查一下订单 12345 的状态" Agent：[调用 query_order(orderId="12345")] Agent："您的订单 12345 已发货，预计明天送达。请注意查收！"

对话 2：多轮对话

用户："有什么新品推荐吗？" Agent：[调用 recommend_products(category="全部")] Agent："为您推荐以下新品：产品A、产品B、产品C。您对哪款感兴趣呢？" 用户："产品A 怎么样？" Agent：[从 Memory 回忆上一轮对话，理解"产品A"指代] Agent："产品A 是我们的明星产品，具有以下特点..."

对话 3：投诉处理

用户："我要投诉，你们的产品质量太差了！" Agent：[调用 create_complaint(description="产品质量问题")] Agent："非常抱歉给您带来不便。我已为您创建投诉工单 TICKET-1234567890，我们会在 24 小时内联系您处理。"

7.5 WebRTC 语音集成

将 AgentService 集成到 WebRTC 语音通话：

@Service
public class OrchestrationService {
    
    private final AgentService agentService;
    
    public void processVoiceCall(String sessionId, byte[] audioData) {
        // 1. VAD 检测语音活动
        boolean isSpeech = vadService.detectSpeech(audioData);
        if (!isSpeech) return;
        
        // 2. ASR 转写
        String userText = asrService.recognize(audioData);
        
        // 3. Agent 推理（自动调用工具）
        String responseText = agentService.chat(sessionId, userText);
        
        // 4. TTS 合成
        byte[] audioResponse = ttsService.synthesize(responseText);
        
        // 5. 通过 WebRTC 发送语音
        webrtcService.sendAudio(sessionId, audioResponse);
    }
}

完整流程：

[User Speech: "我要查订单 12345"]
    ↓ WebRTC
[VAD] → 检测到语音活动
    ↓
[ASR] → "我要查订单 12345"
    ↓
[AgentService]
    ├─ ReActAgent 推理
    │   ├─ Thought: 用户想查询订单
    │   ├─ Action: query_order(orderId="12345")
    │   ├─ Observation: "订单 12345 已发货"
    │   └─ Final Answer: "您的订单 12345 已发货，预计明天送达"
    ├─ 保存到 Memory
    └─ 返回："您的订单 12345 已发货，预计明天送达"
    ↓
[TTS] → 合成语音
    ↓ WebRTC
[User Hears: "您的订单 12345 已发货，预计明天送达"]

八、性能优化与最佳实践

8.1 性能优化建议

1. 控制 ReAct 迭代次数

// 根据场景调整 maxIters
AgentService agentService = new AgentService(systemPrompt, 5);  // 简单场景用 5
AgentService agentService = new AgentService(systemPrompt, 10); // 复杂场景用 10

原则：

• 简单对话（FAQ、闲聊）：3-5 次迭代

• 中等复杂（单工具调用）：5-8 次迭代

• 复杂任务（多工具串联）：8-10 次迭代

2. 异步处理优化

// 使用 CompletableFuture 实现异步 Agent 调用
public CompletableFuture<String> chatAsync(String sessionId, String userText) {
    return CompletableFuture.supplyAsync(() -> {
        try {
            return chat(sessionId, userText);
        } catch (Exception e) {
            logger.error("Async chat failed", e);
            return "抱歉，服务暂时不可用";
        }
    });
}

3. Memory 清理策略

// 定期清理过期 Session
@Scheduled(fixedRate = 3600000) // 每小时清理一次
public void cleanupExpiredSessions() {
    sessionAgents.entrySet().removeIf(entry -> {
        String sessionId = entry.getKey();
        // 检查 Session 是否超过 1 小时未活动
        return isSessionExpired(sessionId);
    });
}

4. 工具调用缓存

@Component
public class CachedWeatherTools {
    
    private final Cache<String, String> weatherCache = 
        CacheBuilder.newBuilder()
            .expireAfterWrite(10, TimeUnit.MINUTES)
            .build();
    
    @Tool(name = "get_weather", description = "查询天气")
    public String getWeather(@ToolParam(name = "city") String city) {
        return weatherCache.get(city, () -> callWeatherAPI(city));
    }
}

8.2 最佳实践

1. System Prompt 设计

原则：

• ✅ 明确角色定位 - "你是一个专业的客服助手"

• ✅ 描述能力边界 - "你可以查询订单、推荐产品"

• ✅ 指定工具使用规则 - "当用户询问天气时，使用 get_weather 工具"

• ✅ 定义回复风格 - "回复简洁、友好、专业"

反例：

• ❌ "你是一个 AI" - 过于泛泛

• ❌ "你什么都能做" - 能力边界不清

• ❌ 未提及工具使用规则 - Agent 不知道何时调用工具

2. 工具命名规范

原则：

• ✅ 动词开头 - query_order, create_ticket, search_faq

• ✅ 语义清晰 - 一眼看出工具功能

• ✅ 参数描述完整 - 使用 @ToolParam 提供详细说明

反例：

• ❌ tool1, tool2 - 无语义

• ❌ order - 不知道是查询还是创建

• ❌ 缺少参数描述 - Agent 不知道如何填充参数

3. 错误处理

public String chat(String sessionId, String userText) {
    try {
        ReActAgent agent = sessionAgents.computeIfAbsent(sessionId, this::createAgent);
        Msg response = agent.call(Msg.builder().textContent(userText).build()).block();
        return response != null ? response.getTextContent() : "抱歉，我没有理解您的问题";
    } catch (Exception e) {
        logger.error("Agent chat failed for session {}", sessionId, e);
        return "抱歉，服务暂时不可用，请稍后重试";
    }
}

4. 日志与监控

logger.info("AgentScope chat - session: {}, userText: {}, responseTime: {}ms",
    sessionId, userText, responseTime);

// 工具调用监控
@Tool(name = "query_order")
public String queryOrder(@ToolParam(name = "orderId") String orderId) {
    long startTime = System.currentTimeMillis();
    try {
        String result = callOrderAPI(orderId);
        logger.info("Tool[query_order] success, orderId: {}, time: {}ms",
            orderId, System.currentTimeMillis() - startTime);
        return result;
    } catch (Exception e) {
        logger.error("Tool[query_order] failed, orderId: {}", orderId, e);
        throw e;
    }
}

九、总结

9.1 旅程的回望

这是一段关于蜕变的故事，关于云雀如何从一只懵懂的语音对话系统，蜕变为能思考、能行动的智能体。

蜕变的起因

• 曾经，自定义 Agent 代码如重负，难以维护

• 曾经，缺少 ReAct 推理之光，无法多步思考

• 曾经，工具调用需要繁琐编排，如同在黑暗中摸索

• 曾经，状态管理分散混乱，隐患重重

蜕变的契机

• ✨ AgentScope 1.0.9 — 通义实验室的匠心之作，生产级 AI Agent 框架

• 🧠 ReActAgent — 思考与行动的艺术，标准推理引擎

• 💾 InMemoryMemory — 记忆的宫殿，自动管理对话历史

• 🛠️ Toolkit + @Tool — 注解的魔法，优雅的工具注册

蜕变的收获

• ✨ 代码减少 70% — 轻装上阵，告别冗余

• 🚀 开发效率提升 90% — 新增工具从 1 小时降至 5 分钟

• 🎯 功能大幅增强 — 多步推理、工具调用、错误恢复

• 🏆 稳定性提升 — 生产级框架，久经千锤百炼

9.2 技术的诗篇

9.3 应用的舞台

云雀 × AgentScope 已在多个舞台上翩翩起舞：

• 💼 智能客服 — 倾听客户需求，查询订单、解答疑问、处理投诉

• 📅 会议助手 — 管理日历、安排会议、及时提醒

• 📚 知识问答 — 检索企业知识库、查询技术文档

• ⚙️ 任务执行 — 自动化工作流、处理数据

• 🎙️ 语音交互 — 智能音箱、车载语音、IoT 设备

9.4 远方的星辰

云雀的愿景是成为 Java 生态最好用的 Voice-Agent 开源框架。引入 AgentScope 是我们迈向这一目标的重要一步，但这只是开始。

远方的星辰还在召唤：

• 🚀 功能的延伸 — 多模态交互、流式响应、Agent 链式编排

• 🎯 性能的打磨 — 分布式部署、模型加速、智能缓存

• 🌐 生态的繁荣 — 工具市场、可视化调试器、低代码构建器

我们相信，开源的力量能让 Voice-Agent 技术如阳光般洒向每一个开发者和企业。

让我们一起，让 AI 真正听懂人类，温暖人类！ 🐦

十、后续规划与社区共建

10.1 云雀 × AgentScope 路线图

Q2 2026 - 功能增强

• 多模态支持 - 集成视觉模型（图片识别、OCR）

• 流式响应 - 支持 SSE（Server-Sent Events）流式输出

• 工具市场 - 提供官方工具库（天气、地图、翻译等）

• Agent 链式编排 - 支持多 Agent 协作（如：主 Agent + 客服 Agent + 技术 Agent）

Q3 2026 - 性能优化

• 分布式 Session 管理 - 支持 Redis 作为 Session 存储

• Agent 池化 - 预创建 Agent 实例，降低首次对话延迟

• 模型热切换 - 支持运行时动态切换 LLM 模型

• GPU 加速 - 为本地模型推理提供 GPU 加速

Q4 2026 - 生态建设

• 可视化 Agent 调试器 - 图形化展示 ReAct 推理过程

• 低代码 Agent 构建器 - 拖拽式构建 Agent 和工具

• 云雀 Agent 市场 - 分享和下载社区贡献的 Agent 模板

• 企业版功能 - 权限管理、审计日志、SLA 保障

10.2 项目信息与核心特性

📂 项目信息

• 项目名称：云雀 (Skylark)

• 标语：生于云端，鸣于指尖

• GitHub：github.com/Jashinck/Sk…

• 开源协议：Apache License 2.0

• 技术栈：Java 17 + Spring Boot 3.2.0 + AgentScope 1.0.9

🌟 核心特性

• 🎯 纯 Java 生态 - 无需 Python 依赖

• 🚀 轻量部署 - 单一 JAR 包，一键启动

• 🤖 生产级 Agent - 集成 AgentScope 框架

• 🎙️ 完整语音链路 - VAD + ASR + LLM + TTS + WebRTC

• 🔧 三种 RTC 策略 - WebSocket / Kurento / LiveKit

• 🛠️ 可插拔工具 - 注解式工具注册，插件化扩展

10.3 如何参与贡献

云雀是一个完全开源的项目（Apache License 2.0），我们欢迎任何形式的贡献！

🌟 贡献方式

1. ⭐ Star 项目

• 关注更新

• 支持开源

2. 🐛 提交 Issue

• 报告 Bug

• 提出功能建议

• 分享使用案例

3. 🔧 提交 Pull Request

• 修复 Bug

• 实现新功能

• 改进文档

4. 🛠️ 贡献工具

• 开发通用工具（如天气查询、地图导航）

• 提交到云雀工具库

5. 📝 分享使用案例

• 撰写技术博客

• 录制视频教程

• 在社区分享经验

📝 贡献指南

1. Fork 本仓库

2. 创建特性分支：git checkout -b feature/amazing-feature

3. 提交更改：git commit -m 'Add amazing feature'

4. 推送分支：git push origin feature/amazing-feature

5. 提交 Pull Request

🏆 贡献者荣誉

所有贡献者将在 README 中展示，优秀贡献者将获得：

• ✅ GitHub Contributor Badge

• ✅ 云雀社区认证

• ✅ 技术分享机会

🤝 社区与支持

• GitHub Issues：github.com/Jashinck/Sk…

• 讨论区：github.com/Jashinck/Sk…

• 邮件列表：skylark-dev@googlegroups.com

🏷️ 标签

#Skylark#AgentScope#AI-Agent#Voice-Agent#Java#Spring-Boot#WebRTC#ReAct#LLM#DeepSeek#ASR#TTS#VAD#Kurento#LiveKit#开源#纯Java#智能语音#语音交互#智能助手#客服机器人#会议助手#知识问答

🐦 云雀 (Skylark) — 生于云端，鸣于指尖

让智能语音交互触手可及

GitHub | 文档 | 贡献指南

⭐ 如果本文对你有帮助，请给云雀项目一个 Star！⭐