教程11：语音智能体

文档摘要

️ 教程 11：语音智能体借助 OpenAI 智能体 SDK，掌握支持语音的 AI 智能体！本教程将演示如何利用语音转文本、文本转语音以及智能代理工作流，构建自然语音交互的对话式语音智能体。您将学到的内容语音管道架构：完整的语音 ↔ 文本 ↔ 语音工作流静态语音处理：基于录制音频的回合制语音交互流式语音处理：实时语音对话与直播音频多语言支持：自动检测语言并实现智能体交接语音优化工具：专为语音交互设计的工具音频管理：录音、播放和流媒体音频实用工具核心概念：语音智能体语音智能体结合了 AI 语言模型与语音处理技术，打造自然的对话式界面。

️ 教程 11：语音智能体

借助 OpenAI 智能体 SDK，掌握支持语音的 AI 智能体！本教程将演示如何利用语音转文本、文本转语音以及智能代理工作流，构建自然语音交互的对话式语音智能体。

您将学到的内容

语音管道架构：完整的语音 ↔ 文本 ↔ 语音工作流
静态语音处理：基于录制音频的回合制语音交互
流式语音处理：实时语音对话与直播音频
多语言支持：自动检测语言并实现智能体交接
语音优化工具：专为语音交互设计的工具
音频管理：录音、播放和流媒体音频实用工具

核心概念：语音智能体

语音智能体结合了 AI 语言模型与语音处理技术，打造自然的对话式界面。不妨把语音智能体想象成一种你可以自然交谈的 AI 助手，它们具备以下功能：

听取你的语音并将其转换为文本
利用智能 AI 智能体处理你的请求
像文本智能体一样使用工具并做出决策
将回复转换回自然语音
无缝处理多轮对话


┌─────────────────────────────────────────────────────────────┐
│                     VOICE AGENT SYSTEM                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   USER SPEECH                                             │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    1. SPEECH-TO-TEXT                       │
│  │   AUDIO     │    ◦ Convert speech to text                │
│  │  PIPELINE   │    ◦ Handle multiple languages             │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    2. AGENT PROCESSING                     │
│  │    AGENT    │    ◦ Multi-agent workflows                 │
│  │ ECOSYSTEM   │    ◦ Tool calling & handoffs               │
│  └─────────────┘    ◦ Context management                    │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    3. TEXT-TO-SPEECH                       │
│  │   SPEECH    │    ◦ Convert response to speech            │
│  │ SYNTHESIS   │    ◦ Natural voice output                  │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│   AI RESPONSE                                             │
└─────────────────────────────────────────────────────────────┘

教程概览

本教程将演示三种核心语音交互模式：

1. 静态语音处理 (`static/`)

Turn-based interaction: Record → Process → Respond
Complete audio processing: Full utterance before processing
Simpler implementation: Easier to understand and debug
Best for: Voice commands, structured interactions

2. Streaming Voice Processing (`streamed/`)

Real-time interaction: Continuous listening and responding
Live audio streaming: Process audio as it arrives
Activity detection: Automatic speech start/stop detection
Best for: Natural conversations, voice assistants

3. Realtime Voice Processing (`realtime/`)

超低延迟：基于 WebSocket 的持久连接
打断处理：自然对话中的打断处理
实时 API：OpenAI 最新语音技术
适用场景：实时对话，对延迟要求极低

项目结构


11_voice/
├── README.md                          # This file - voice agents overview
├── static/                            # Static voice processing example
│   ├── agent.py                      # Complete static voice agent
│   ├── util.py                       # Audio recording and playback utilities
│   ├── requirements.txt              # Dependencies for static example
│   ├── env.example                   # Environment variables
│   └── README.md                     # Static voice documentation
├── streamed/                         # Streaming voice processing example
│   ├── agent.py                      # Real-time streaming voice agent
│   ├── util.py                       # Streaming audio utilities
│   ├── requirements.txt              # Dependencies for streaming example
│   ├── env.example                   # Environment variables
│   └── README.md                     # Streaming voice documentation
├── realtime/                         # Realtime voice processing example
│   ├── agent.py                      # Basic realtime voice agent
│   ├── requirements.txt              # Dependencies for realtime example
│   ├── env.example                   # Environment variables
│   └── README.md                     # Realtime voice documentation
└── __init__.py                       # Module initialization

学习目标

完成本教程后，您将理解：

✅ 如何构建完整的语音交互管道
✅ 静态与流式语音处理的区别
✅ 如何实现多语言语音智能体并进行交接
✅ 语音优化智能体设计的最佳实践
✅ 实时音频处理与流媒体技术

开始使用

前提条件

安装支持语音的 OpenAI 智能体 SDK：
```
pip install 'openai-agents[voice]'
```

安装音频依赖库：


pip install sounddevice numpy soundfile librosa

设置环境变量：


cp static/env.example static/.env
cp streamed/env.example streamed/.env
# Edit .env files and add your OpenAI API key

快速入门选项

选项 1：静态语音（推荐给初学者）


cd static/
python agent.py

选项 2：流式语音（进阶版）


cd streamed/
python agent.py

选项 3：实时语音（超低延迟）


cd realtime/
python agent.py

语音智能体能力

多语言支持

两个示例均包含：

英语智能体：主助手，拥有完整工具访问权限
西班牙语智能体：专门的西班牙语助手
法语智能体：专门的法语助手
自动语言检测：根据识别的语言无缝交接

语音优化工具

get_weather(city): Weather information with voice-friendly responses
get_time(): Current time with natural speech output
calculate_tip(bill, percentage): Tip calculations for voice queries
set_reminder(message, minutes): Voice-activated reminders (streaming only)
get_news_summary()：适合语音的新闻更新（仅限流式）

音频处理功能

高质量录音：24kHz 音频采集
实时播放：低延迟音频输出
活动检测：自动检测语音边界（流式）
错误恢复：强大的音频管道错误处理机制

语音智能体关键模式

1. 基础语音管道


from agents.voice import VoicePipeline, SingleAgentVoiceWorkflow

pipeline = VoicePipeline(
    workflow=SingleAgentVoiceWorkflow(agent)
)

2. 静态音频处理


from agents.voice import AudioInput

audio_buffer = record_audio(duration=5.0)
audio_input = AudioInput(buffer=audio_buffer)
result = await pipeline.run(audio_input)

3. 流式音频处理


from agents.voice import StreamedAudioInput

streamed_input = StreamedAudioInput()
result = await pipeline.run(streamed_input)

# Push audio chunks in real-time
streamed_input.push_audio(audio_chunk)

4. 多语言智能体设置


spanish_agent = Agent(
    name="Spanish",
    handoff_description="A spanish speaking agent.",
    instructions="Speak in Spanish only..."
)

main_agent = Agent(
    name="Assistant", 
    handoffs=[spanish_agent, french_agent],
    instructions="If user speaks Spanish, handoff to Spanish agent..."
)

语音智能体最佳实践

智能体语音设计

简洁指令：语音交互最适合简短指令
对话式回复：针对自然语音模式设计
清晰工具描述：语音友好的工具命名与描述
语言处理：实现清晰的语言检测逻辑

音频质量

优质硬件：使用高质量麦克风与扬声器
降噪处理：录制时尽量减少背景噪音
音频电平：确保合适的输入/输出音量
延迟优化：配置音频缓冲区以最小化延迟

错误处理

优雅失败：妥善处理音频设备故障
网络问题：实现 API 调用的重试逻辑
用户打断：允许语音会话干净退出
资源清理：正确关闭音频流与资源

示例语音交互

英语对话

“给我讲个笑话” → 幽默回复
“伦敦的天气怎么样？” → 调用天气工具
“现在几点了？” → 当前时间
“计算 75 美元账单的 18% 折扣” → 计算折扣

语言切换

“Hola, ¿qué tiempo hace en Madrid？” → 西班牙语智能体回复
“Bonjour, quelle heure est-il？” → 法语智能体回复
语言自动检测与智能体交接顺畅

多轮对话（流式）

自然的来回对话
跨轮次保持上下文
对话中使用工具

静态 vs 流式对比

特性	静态语音	流式语音
处理方式	回合制	实时
复杂度	更简单	更复杂
延迟	更高	更低
适用场景	命令、查询	对话
活动检测	手动	自动
资源占用	更低	更高
用户体验	结构化	自然

要求与依赖项

核心依赖

openai-agents[voice]: Voice-enabled Agents SDK
sounddevice: Real-time audio I/O
numpy: Audio data processing
soundfile: Audio file operations (optional)
librosa：音频重采样（可选）

系统要求

Python 3.8+：需支持异步
音频硬件：麦克风与扬声器/耳机
处理能力：足够 CPU 进行实时音频处理
网络：稳定的互联网用于 OpenAI API 调用

故障排除

音频问题

无麦克风输入：检查音频设备权限与设置
音频质量差：验证麦克风电平与背景噪音
播放问题：测试扬声器/耳机配置
延迟问题：优化音频缓冲区大小

语音管道问题

转录错误：确保语音清晰且音频质量良好
智能体回复：验证 API 密钥与网络连接
语言检测：用清晰的语言示例测试
交接失败：检查智能体指令与交接逻辑

性能问题

CPU 使用率高：监控实时处理负载
内存泄漏：确保正确清理音频流
网络超时：实现 API 调用的重试逻辑
资源冲突：检查音频设备冲突

专业提示

从静态开始：先掌握静态语音处理，再尝试流式
测试音频设置：开发前验证硬件配置
监控调试输出：使用回调了解管道行为
优化语音交互：专门针对对话式交互设计智能体
应对边缘情况：规划网络问题、音频故障与用户打断

下一步

掌握语音智能体后：

生产部署：将语音智能体扩展到实际应用
自定义语音模型：集成专用语音识别/合成技术
多模态智能体：结合语音、视觉与文本能力
企业语音解决方案：构建面向商业用途的稳健语音应用

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文（母语）文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。