语音智能体让用户可以通过与您的应用对话来提问和完成任务。设计时,首先要决定如何将语音交互与推理和工具调用结合起来。您可以让对话持续进行,把任务交给独立后端处理;也可以让一个语音模型负责整个过程,或采用由您逐阶段控制的流水线。
选择合适的架构
| 架构 | 适用场景 | 选择理由 |
|---|---|---|
| GPT-Live | 使用独立后端的全双工对话 | 可以保留现有的文本工作流,自主选择后端,并在后端处理任务时继续对话。 |
| Realtime API | 在同一会话中处理语音、推理和工具调用 | 由同一个模型理解音频、决定下一步操作并用语音回答。 |
| 链式语音流水线 | 需要控制语音和文本处理的各个阶段 | 可以检查或转换中间阶段的文本,也可以单独替换各个组件。 |
构建全双工语音智能体
GPT-Live 可以同时听和说,这种能力称为全双工。实时模型负责语音交互,并将推理和工具调用委派给独立后端。后端处理任务时,用户可以继续说话。
您可以保留现有的文本工作流,包括其中的业务逻辑和工具,并接入 GPT-Live 作为语音接口。您选择的委派模式决定了由谁执行后端任务,以及由谁为这些任务提供对话上下文:
- 客户端委派: 接入您自己的智能体或工作流,自行选择后端模型和提供商。您的应用负责执行任务,并将结果返回给 GPT-Live。
- Responses 委派: 选择由 OpenAI 托管的 Responses 模型来执行后端推理和工具调用。GPT-Live 提供对话上下文并管理对该模型的调用,自定义函数仍由您的应用执行。
在这两种模式下,权限和业务记录都由您的应用管理。请在实时模型的提示词中指定说话方式,在后端提示词中定义业务规则。
请先阅读 GPT-Live 入门指南。有关后端配置,请参阅委派与工具;要调整模型的说话方式,请参阅为语音模型编写提示词。
构建语音到语音智能体
使用 Realtime API 时,您可以从 RealtimeAgent 和 RealtimeSession 入手,优先面向浏览器构建应用。会话负责处理各轮语音交互、工具调用、打断和智能体交接。完整的入门示例现已收录在 Realtime API 入门指南中。
构建链式语音工作流
如果您需要在语音识别、智能体处理和语音生成之间检查或转换文本,可以采用链式工作流。您的应用负责管理三个阶段:
- 语音转文本
- 执行智能体工作流
- 文本转语音
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-6.2-astra",
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", event.data.nbytes)
if __name__ == "__main__":
asyncio.run(main())如果您需要观察每个阶段的处理过程,或需要单独替换其中任一阶段,可以采用这种架构。例如,您可以保存转写文本,在文本智能体回答之前执行策略检查,调用内部系统,等工作流得出经过审批的答案后再生成语音。
评估语音智能体
请同时测试对话表现和任务完成情况。例如,测试预约助手时,既要听它如何确认预约,也要检查系统保存的预约信息是否正确。
- 选择有代表性的场景,明确每个场景的预期结果、应调用的工具和所需权限。
- 保存验证各项结果所需的音频、事件、工具结果和应用状态。请区分两种情况:评估本身未能正常运行,或者评估正常运行但智能体未能完成任务。
- 重复测试相同场景,比较任务完成情况、用户听到回复前的延迟、打断情况和不必要的沉默。比较改动前后的表现时,请使用相同的呼叫方、模型配置、工具和传输方式。
对于 GPT-Live,请分别评估以下方面:
- 任务和工具执行结果: 检查智能体是否保留了用户的原意,并核查委派任务的执行情况、工具参数、权限和应用的最终状态。确认语音回复中声称已完成的操作与实际执行结果一致。
- 对话时序: 测量用户多久能听到回复,记录不必要的沉默和双方同时说话的情况。评估智能体在被打断时能否停下来听用户说话,包括用户在后端处理任务期间纠正智能体的情况。
- 语音和语言: 测试不同口音、背景噪声和语言切换对输入识别的影响,并检查姓名和数字能否正确识别。对于输出,请单独评估语音是否清晰易懂,以及语言选择是否恰当。
- 会话可靠性: 跟踪连接失败、音频丢失、超时和会话未完成的情况,与任务评分分开记录。
按基础测试、录音回放和模拟通话三个阶段逐步增加测试复杂度:
- 基础测试: 使用合成语音,在受控条件下测试单轮请求。保持生成的音频、应用上下文和预期结果一致,以便重复测试并比较结果。
- 录音回放: 回放有代表性的真人单轮请求录音,测试不同人声、麦克风、停顿和声学环境如何影响智能体的表现。
- 模拟通话: 使用独立的模拟呼叫方进行连续的多轮对话。在对话和后端任务同时进行时,测试智能体如何澄清问题、应对需求变化和打断,以及如何恢复对话。
除自动评分外,还请安排人工试听,评估发音是否准确、表达是否自然,以及对话节奏是否合适。
有关 GPT-Live 的评估执行框架,请参阅 OpenAI Cookbook 中的语音智能体评估示例。
有关 Realtime 的评估执行框架和完整示例,请参阅 OpenAI Cookbook 中的 Realtime 评估指南。
测量延迟
测量呼叫方需要等待多久才能听到有用的回答。单独记录后端耗时,以便定位延迟,并比较同类通话的延迟中位数和第 95 百分位数。
比较不同前端模型时,请保持呼叫方、录音、后端模型、提示词、传输方式、音频发送节奏和评分器一致。
对于 GPT-Live,请记录您的应用能够观察到的各个时间点:收到委派任务、发起后端请求、获得首个有用结果、工具开始执行和执行结束、提交结果、收到音频,以及客户端播放音频。在客户端委派模式下,您的应用可以直接观察自己发出的后端请求。在 Responses 委派模式下,您的应用可以观察嵌套的响应事件和自身执行的自定义工具调用。
根据这些时间点判断延迟发生在建立连接、模型处理、工具执行、缓冲还是播放环节。对于“我正在查询”之类的回应,请将呼叫方听到这类回应前的等待时间与听到所需答案前的等待时间分开测量。
每次只改变一个因素,并重复测试相同场景。检查响应速度提高后,任务成功率、工具调用的正确性或打断情况是否也发生了变化。请参阅降低后端延迟。
语音智能体沿用相同的核心组件
语音接口改变了传输方式和音频收发流程,但设计核心工作流时仍需考虑相同的问题:
- 语音智能体需要外部能力时,请参阅使用工具。
- 语音工作流需要流式处理、接续运行或持久化状态时,请参阅运行智能体。
- 语音工作流需要将不同分支的任务交给相应的专业智能体时,请参阅编排与交接。
- 语音工作流需要安全检查或审批时,请参阅防护措施与人工审核。
- 如果您需要通过 MCP 提供的能力,或想检查语音工作流的实际运行情况,请参阅集成与可观测性。
实际设计时,请先选定音频架构,再按照设计文本智能体工作流的方法设计其余部分。
后续步骤
根据您的使用场景选择合适的实时交互或音频指南。
管理 Realtime 会话的生命周期,并使用其事件模型。
将浏览器和移动设备的音频直接接入 Realtime 会话。
调整推理方式、操作前的说明、工具使用、实体信息提取和语音表现。