静态语音代理

文档摘要

️ 静态语音代理使用 OpenAI Agents SDK 和预录音频输入的完整语音交互示例。此示例展示了基本的语音处理流程，包括语音转文本、代理处理和文本转语音功能。本演示所展示的内容静态音频处理：录制一次，完整处理语音处理管道：完整的语音转文本 → 代理处理 → 文本转语音工作流多代理系统：根据语言检测进行代理交接工具集成：支持语音激活的天气、时间和计算工具音频管理：录音、播放及音频实用功能核心概念：静态语音处理管道静态语音处理管道在一个工作流中处理完整的音频录制内容。

️ 静态语音代理

使用 OpenAI Agents SDK 和预录音频输入的完整语音交互示例。此示例展示了基本的语音处理流程，包括语音转文本、代理处理和文本转语音功能。

本演示所展示的内容

静态音频处理：录制一次，完整处理
语音处理管道：完整的语音转文本 → 代理处理 → 文本转语音工作流
多代理系统：根据语言检测进行代理交接
工具集成：支持语音激活的天气、时间和计算工具
音频管理：录音、播放及音频实用功能

核心概念：静态语音处理管道

静态语音处理管道在一个工作流中处理完整的音频录制内容。可以将其视为一个回合制语音助手，它：

先录制你的完整消息
将整个音频转写为文本
使用 AI 代理和工具进行处理
将完整响应转换回语音
播放完整的音频响应


┌─────────────────────────────────────────────────────────────┐
│                    STATIC VOICE WORKFLOW                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   RECORD AUDIO                                            |
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    1. COMPLETE RECORDING                   │
│  │   AUDIO     │    ◦ Record for fixed duration             │
│  │  CAPTURE    │    ◦ Full audio buffer                     │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    2. SPEECH-TO-TEXT                       │
│  │ TRANSCRIBE  │    ◦ Convert full audio to text            │
│  │   AUDIO     │    ◦ Complete transcription                │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    3. AGENT PROCESSING                     │
│  │   AGENT     │    ◦ Multi-agent workflow                  │
│  │ WORKFLOW    │    ◦ Tool calls & handoffs                 │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    4. TEXT-TO-SPEECH                       │
│  │  GENERATE   │    ◦ Convert response to audio             │
│  │   SPEECH    │    ◦ Stream audio output                   │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│   PLAY RESPONSE                                           │
└─────────────────────────────────────────────────────────────┘

快速入门

安装语音依赖项：


pip install 'openai-agents[voice]'
pip install sounddevice numpy soundfile librosa

设置环境：


cp env.example .env
# Edit .env and add your OpenAI API key

运行静态语音代理：
```
python agent.py
```

本示例包含的内容

多语言支持

英语代理：主要助手，配备所有工具
西班牙语代理：专门的西班牙语助手
法语代理：专门的法语助手
自动语言检测：根据检测到的语言进行代理交接

语音激活工具

get_weather(city): Get weather information for any city
get_time(): Get current time
calculate_tip(bill, percentage): Calculate tips for bills

Audio Utilities

AudioPlayer: Real-time audio playback with sounddevice
record_audio(): Microphone recording with duration control
create_silence(): Generate silence buffers
save_audio() / load_audio(): Audio file operations

Workflow Callbacks

WorkflowCallbacks：监控转写、工具调用和代理交接
管道监控的调试输出
性能跟踪与统计信息

示例交互

英语示例

“给我讲个笑话” → 代理以幽默方式回应
“东京的天气怎么样？” → 调用天气工具
“现在几点了？” → 调用时间工具
“计算 50 美元账单的 20% 折扣” → 执行计算

语言交接

“Hola, ¿cómo estás？” → 交接给西班牙语代理
“Bonjour, comment allez-vous？” → 交接给法语代理
代理以检测到的语言回应

工具集成

天气查询支持任何语言
时间和计算工具对所有代理可用
工具根据用户请求自动调用

关键实现模式

1. 语音处理管道设置


pipeline = VoicePipeline(
    workflow=SingleAgentVoiceWorkflow(agent, callbacks=WorkflowCallbacks())
)

2. 音频输入处理


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

3. 音频输出流式传输


with AudioPlayer() as player:
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            player.add_audio(event.data)

4. 多代理配置


agent = Agent(
    name="Assistant",
    handoffs=[spanish_agent, french_agent],
    tools=[get_weather, get_time, calculate_tip]
)

语音代理最佳实践

清晰的音频录制：确保麦克风质量良好，背景噪音尽量低
简洁的指令：语音交互最适合简短、清晰的代理指令
错误处理：针对音频录制失败实施健壮的错误处理
语言检测：通过提示工程实现自动语言切换
工具设计：设计适合语音交互的工具，提供对话式回复

性能特征

静态管道优势

可预测的处理：固定录制时长
完整上下文：完整语句可用于处理
更简单的实现：无需实时复杂性
更适合复杂查询：可处理更长、更详细的请求

应用场景

语音助手：传统的回合制交互
语音命令：特定任务自动化
语言学习：与多语言代理练习
无障碍访问：面向应用的语音界面

要求与依赖项

核心依赖项

openai-agents[voice]: OpenAI Agents SDK with voice support
sounddevice: Audio recording and playback
numpy: Audio data processing
soundfile: Audio file operations (optional)
librosa：音频重采样（可选）

系统要求

麦克风：用于音频输入
扬声器/耳机：用于音频输出
Python 3.8+：需支持异步操作

️ 自定义选项

扩展音频实用工具

添加音频效果和滤波
实现自定义音频格式
添加音频可视化

增强代理能力

添加更多专业语言代理
实现领域专用工具
添加会话记忆

提升语音体验

添加语音活动检测
实现自定义唤醒词
添加语音情感检测

专业提示

测试音频设置：运行前验证麦克风和扬声器
试验录制时长：根据使用场景调整录制时长
监控调试输出：使用回调了解管道行为
处理中断：实现对 Ctrl+C 的优雅处理
优化语音表现：保持代理回复简明且具有对话感

下一步

掌握静态语音代理后：

流式语音：实现实时语音交互
高级语音管道：自定义管道配置
生产级语音应用：将语音代理部署到实际应用中

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