语音智能体将相同的智能体概念转化为口语化、低延迟的交互。关键的设计选择在于决定模型是直接处理实时音频,还是由你的应用程序显式地将语音转文本、文本推理和文本转语音串联起来。
选择合适的架构
| 架构 | 适用场景 | 原因 |
|---|---|---|
| 具有实时音频会话的语音到语音 | 自然、低延迟的对话 | 模型直接处理实时音频输入和输出 |
| 链式语音管道 | 可预测的工作流或扩展现有的文本智能体 | 你的应用对转录、文本推理和语音输出保持明确的控制 |
智能体构建器 目前不支持语音工作流,因此语音仍然是一个优先使用 SDK 构建的平台。
推荐的起点
以下示例刻意采用了不同的架构,并非为了匹配不同语言的标签页。TypeScript 和 Python 库目前提供了不同的语音辅助工具:
- 在 TypeScript 中,构建基于浏览器的语音助手的最快途径是
RealtimeAgentandRealtimeSession. - 在 Python 中,将现有文本智能体扩展为语音的最简单途径是链式的
VoicePipeline.
构建语音到语音的语音智能体
当交互需要具有对话感和即时性时,请使用实时音频 API 路径。对于需要打断、低首音频延迟、自然轮换以及实时工具使用的语音智能体,这是最佳的起点。
常见的浏览器流程是:
- 你的应用服务器为实时音频会话创建一个临时客户端密钥。
- 你的前端创建一个
RealtimeSession. - 该会话在浏览器中通过 WebRTC 连接,或在服务器上通过 WebSocket 连接。
- 智能体在该会话内处理音频轮次、工具、中断和交接。
启动实时语音会话
typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2",
});
await session.connect({
apiKey: "ek_...(ephemeral key from your server)",
});然后,将工具、交接和防护措施附加到 RealtimeAgent 与将它们附加到文本智能体的方式相同。将音频传输问题保留在会话层,将业务逻辑保留在智能体定义中。
当你需要更低级别的控制时,请从传输文档开始:
构建链式语音工作流
当你希望对中间文本有更强的控制、希望复用现有文本智能体,或希望从非语音工作流进行更简单的扩展时,请使用链式路径。在这种设计中,你的应用程序需显式管理:
- 语音转文本
- the agent workflow itself
- 文本转语音
这通常更适合支持流程、重审批流程,或者你希望在每个阶段之间拥有持久化转录和确定性逻辑的场景。
运行链式语音管道
python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import asyncio
import numpy as np
from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline
@function_tool
def get_weather(city: str) -> str:
"""Get the weather for a given city."""
return f"The weather in {city} is sunny."
agent = Agent(
name="Assistant",
instructions="You are a helpful voice assistant.",
model="gpt-5.5",
tools=[get_weather],
)
async def main() -> None:
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
result = await pipeline.run(audio_input)
async for event in result.stream():
if event.type == "voice_stream_event_audio":
print("Received audio bytes", len(event.data))
if __name__ == "__main__":
asyncio.run(main())当每个阶段都需要可见或可替换时,请使用此路径。例如,你可能会存储转录,在文本智能体响应之前运行策略检查,调用内部系统,然后仅在工作流得出已批准的答案后才生成语音。
语音智能体仍然使用相同的核心智能体构建块
语音平台改变了传输和音频循环,但核心工作流的决策是相同的:
- 使用 使用工具 当语音智能体需要外部能力时。
- 使用 运行智能体 当语音工作流需要流式传输、延续或持久化状态时。
- 使用 编排与交接 当语音工作流在不同专家之间分支时。
- 使用 护栏与人工审查 当语音工作流需要安全检查或审批时。
- 使用 集成与可观测性 当你需要 MCP 支持的能力,或想要检查语音工作流的行为时。
实用规则是:首先选择音频架构,然后以与处理文本相同的方式设计智能体工作流的其余部分。
后续步骤
实时与音频概述
根据你的用例选择合适的实时或音频指南。
管理对话
使用实时会话生命周期和事件模型。
WebRTC 连接
将浏览器和移动音频直接连接到实时会话。
实时提示指南
调整推理、前言、工具、实体捕获和语音行为。