English
主导航

旧版 API

语音智能体

使用语音到语音会话或链式语音管道构建语音智能体。

语音智能体将相同的智能体概念转化为口语化、低延迟的交互。关键的设计选择在于决定模型是直接处理实时音频,还是由你的应用程序显式地将语音转文本、文本推理和文本转语音串联起来。

选择合适的架构

架构适用场景原因
具有实时音频会话的语音到语音自然、低延迟的对话模型直接处理实时音频输入和输出
链式语音管道可预测的工作流或扩展现有的文本智能体你的应用对转录、文本推理和语音输出保持明确的控制

智能体构建器 目前不支持语音工作流,因此语音仍然是一个优先使用 SDK 构建的平台。

以下示例刻意采用了不同的架构,并非为了匹配不同语言的标签页。TypeScript 和 Python 库目前提供了不同的语音辅助工具:

  • 在 TypeScript 中,构建基于浏览器的语音助手的最快途径是 RealtimeAgent and RealtimeSession.
  • 在 Python 中,将现有文本智能体扩展为语音的最简单途径是链式的 VoicePipeline.

构建语音到语音的语音智能体

当交互需要具有对话感和即时性时,请使用实时音频 API 路径。对于需要打断、低首音频延迟、自然轮换以及实时工具使用的语音智能体,这是最佳的起点。

常见的浏览器流程是:

  1. 你的应用服务器为实时音频会话创建一个临时客户端密钥。
  2. 你的前端创建一个 RealtimeSession.
  3. 该会话在浏览器中通过 WebRTC 连接,或在服务器上通过 WebSocket 连接。
  4. 智能体在该会话内处理音频轮次、工具、中断和交接。
启动实时语音会话
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 与将它们附加到文本智能体的方式相同。将音频传输问题保留在会话层,将业务逻辑保留在智能体定义中。

当你需要更低级别的控制时,请从传输文档开始:

构建链式语音工作流

当你希望对中间文本有更强的控制、希望复用现有文本智能体,或希望从非语音工作流进行更简单的扩展时,请使用链式路径。在这种设计中,你的应用程序需显式管理:

  1. 语音转文本
  2. the agent workflow itself
  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
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 连接

将浏览器和移动音频直接连接到实时会话。

实时提示指南

调整推理、前言、工具、实体捕获和语音行为。