语音智能体

语音智能体让用户能够通过与您的应用交谈来提问和完成任务。关键的设计选择在于如何将语音与推理和工具连接起来：采用配备独立后端的持续对话模式、使用单个语音模型，或构建由您逐阶段控制的流水线。

选择合适的架构

构建全双工语音智能体

GPT-Live 可以同时听和说，这种能力称为 全双工。实时模型负责语音交互，并将推理和工具使用委派给独立的后端。后端执行任务时，用户可以继续交谈。

您可以保留现有的文本工作流，包括其中的业务逻辑和工具，并添加 GPT-Live 作为语音交互界面。您选择的 委派模式 决定由谁执行后端任务并提供任务所需的对话上下文：

• 客户端委派： 接入您自己的智能体或工作流，使用您选择的后端模型和提供商。您的应用执行任务，并将结果返回给 GPT-Live。
• Responses 委派： 选择由 OpenAI 托管的 Responses 模型来处理后端推理和工具使用。GPT-Live 提供对话上下文并管理对该模型的调用；自定义函数仍由您的应用执行。

在这两种模式下，权限和业务记录都由您的应用控制。请在实时模型的提示中定义说话行为，在后端提示中定义业务规则。

请先阅读 GPT-Live 入门。有关后端设置，请参阅委派与工具；有关说话行为，请参阅语音模型提示词。

构建语音到语音智能体

对于 Realtime API，RealtimeAgent 和 RealtimeSession 提供了以浏览器为主要使用环境的入门方案。会话负责处理音频轮次、工具、中断和移交。完整的入门示例现已移至 Realtime API 入门。

构建链式语音工作流

如果您希望在语音识别、智能体和语音生成这些环节之间检查或转换文本，请使用链式方案。您的应用负责管理三个阶段：

1. 语音转文本
2. 智能体工作流本身
3. 文本转语音

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
32import 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-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", len(event.data))


if __name__ == "__main__":
    asyncio.run(main())

如果您需要查看或替换每个阶段，请使用此方案。例如，您可以保存转录文本，在文本智能体回复前执行策略检查，调用内部系统，然后仅在工作流得出已获批准的答案后生成语音。

评估您的语音智能体

请分别测试对话质量和任务结果。回复听起来自然，并不能证明工具已执行或应用状态已改变。

1. 选择有代表性的场景，并明确预期结果、工具调用和权限。
2. 保存验证每项结果所需的音频、事件、工具结果和应用状态。请区分评估运行本身失败的情况，以及评估有效运行但智能体未能完成任务的情况。
3. 重复测试各个场景，比较任务完成情况、可听见的语音回复延迟、中断和不必要的静默。在比较变更效果时，请保持对话发起方、模型配置、工具和传输方式一致。

对于 GPT-Live，请分别衡量以下维度：

• 任务和工具结果： 检查用户意图是否得到保留、委派任务的执行情况、工具参数、权限以及最终应用状态。验证语音确认是否与已完成的操作一致。
• 对话时序： 衡量可听见的语音回复时序、不必要的静默、双方同时说话的情况，以及被打断时是否让出话轮，包括后端执行任务期间用户提出更正的情况。
• 语音和语言： 测试在不同口音、背景噪声、语言切换以及包含姓名和数字的情况下，输入识别的表现。将输出是否清晰易懂、语言选择是否合适与识别能力分开评估。
• 会话可靠性： 单独跟踪连接失败、音频丢失、超时和会话未完成的情况，不要将这些指标混入任务得分。

按 基础、进阶和综合 三个阶段逐步增加复杂度：

1. 基础： 使用合成语音测试受控的单轮请求。保持生成的音频、应用上下文和预期结果不变，以便重复比较。
2. 进阶： 重放有代表性的真人单轮请求录音，测试声音、麦克风、停顿和声学条件如何影响智能体的行为。
3. 综合： 使用独立的模拟对话发起方进行持续的多轮对话。在对话与后端任务同时进行时，测试澄清、需求变化、中断和恢复等情况。

在自动评分之外，辅以人工听评，评估发音、自然度以及对话节奏是否合适。

有关 GPT-Live 的评估执行框架，请参阅语音智能体评估 Cookbook。

有关 Realtime 的评估执行框架和完整示例，请参阅 OpenAI Cookbook 中的 Realtime 评估指南。可运行的评估示例由 Cookbook 维护；本页提供通用的测试清单。

测量延迟

为每项延迟指标定义可观测的起始和结束事件。首次可听见的语音回复耗时、 发起委派耗时、被打断后让出话轮的耗时、后端完成耗时， 以及经验证的任务完成耗时，各自衡量的起止边界不同。请使用统一的单调时间轴， 并报告符合统计条件的样本总体、中位数和尾部延迟。不要 用仅衡量后端的计时结果代替端到端响应时间。

比较前端模型时，请保持对话发起方、录音、后端模型、提示、传输方式、音频发送节奏和 评分器不变。

对于 GPT-Live，请记录您的应用能够观测到的各个阶段：收到委派、 后端请求开始、获得首个有用结果、工具开始和结束、提交结果、 音频到达以及客户端播放。客户端委派让您的应用 能够直接观测其后端请求；Responses 委派则提供嵌套响应事件， 以及您的应用所运行的自定义工具的可观测信息。

利用各阶段之间的时间间隔，定位连接建立、模型处理、工具执行、 应用缓冲和播放中的延迟。请将首个有用的语音回答 与“我正在查询”这样的回应分开测量。更早给出这类回应， 并不代表用户请求的结果更早到达。

每次只改变一个因素，并重复测试相同的场景。比较获得有用语音回复的耗时中位数和 尾部延迟，同时比较任务成功情况、工具使用的正确性 和中断情况。有关实现指导，请参阅降低后端延迟 。

语音智能体仍使用相同的核心智能体构建模块

语音交互改变了传输方式和音频处理循环，但工作流的核心设计决策仍然相同：

• 当语音智能体需要外部能力时，请参阅使用工具。
• 当语音工作流需要流式传输、继续执行或持久状态时，请参阅运行智能体。
• 当语音工作流需要分支到不同的专长智能体时，请参阅编排与移交。
• 当语音工作流需要安全检查或审批时，请参阅护栏与人工审查。
• 当您需要由 MCP 提供的能力，或想检查语音工作流的运行表现时，请参阅集成与可观测性。

实用原则是：先选择音频架构，再按照设计文本智能体的方式，设计智能体工作流的其余部分。

后续步骤