使用 Realtime API 构建支持语音到语音交互的智能体。模型直接处理音频,维护对话状态,还可以调用工具。本指南首先介绍如何使用 Agents SDK 构建浏览器应用。如果您需要直接控制底层连接,请参阅相应的连接指南。
如果您需要将后端处理委托给独立服务来实现全双工对话,请参阅 GPT-Live。如需比较不同的语音架构和链式处理流程,请参阅语音智能体。
构建支持语音到语音交互的智能体
如果您希望交互像日常对话一样自然、即时,可以使用 Realtime API。如果您的语音智能体需要支持用户随时打断、以低延迟开始播放回复、自然地轮流发言以及实时调用工具,Realtime API 是最佳起点。
浏览器应用通常按以下步骤建立并使用会话:
- 应用服务器为 Realtime 会话创建临时客户端密钥。
- 前端创建一个
RealtimeSession。 - 会话在浏览器中通过 WebRTC 建立连接,在服务器上则通过 WebSocket 建立连接。
- 智能体在会话中处理各轮语音交互、工具调用、打断和智能体之间的任务交接。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: ephemeralKey,
});接下来,您可以像配置文本智能体一样,为 RealtimeAgent 添加工具、任务交接和防护机制。请在会话层处理音频传输,并在智能体定义中编写业务逻辑。
如果您需要控制底层传输,请先参阅以下文档:
安全标识符
如果您的应用能识别每位最终用户,请在 Realtime API 请求中附上安全标识符。OpenAI 建议使用安全标识符,但不作强制要求。安全标识符有助于 OpenAI 检测有害行为,并将处置措施限定于相关用户,避免影响整个组织。请选择一个稳定且能保护隐私的值,例如内部用户 ID 的哈希值。
对于 Realtime API 请求,请通过 OpenAI-Safety-Identifier 请求头发送标识符。如果使用临时 Token,请在服务器端创建客户端密钥的请求中设置此请求头,将标识符与会话关联。如果从受信任的服务器通过 WebSocket 或统一的 WebRTC 接口建立连接,请在连接请求中设置此请求头。
Realtime 会话不会自动沿用 Responses API 请求或其他会话中的安全标识符。如果您在应用的其他位置使用了 Responses API 的 safety_identifier 参数,请在创建或连接每个 Realtime 会话时传入同一个稳定值。
从测试版迁移到正式版(GA)
如果您的应用仍在使用测试版 Realtime 接口,请先将其迁移到正式版接口,再开展新的开发工作。主要变更如下:
- 调用正式版接口时,移除
OpenAI-Beta: realtime=v1请求头。 - 使用
POST /v1/realtime/client_secrets为浏览器或移动客户端创建临时凭据。 - 建立 WebRTC 会话时,使用
/v1/realtime/calls。 - 按正式版接口的要求更新会话和事件的数据结构。具体来说,请设置
session.type,将音频输出配置移至session.audio.output下,并使用新版响应事件名称,例如response.output_text.delta、response.output_audio.delta和response.output_audio_transcript.delta。 - 如果您要迁移语音到语音应用,请从浏览器示例入手。如果您要迁移转写工作流,请参阅实时转写。
有关当前正式版的使用流程,请参阅 Realtime 客户端事件参考、Realtime 会话参考和浏览器示例。
后续步骤
- 管理对话:配置会话并处理音频、文本和事件。
- 语音活动检测:配置对话轮次的自动检测。
- 工具与 MCP:添加函数、MCP 服务器和连接器。
- 为语音模型编写提示词:参阅适用于您所用 Realtime 模型的指南。
- 成本优化:了解 Realtime 的用量计算方式和缓存机制。
- 服务器端控制:在您的服务器上执行工具并控制会话。
其他音频工作流
现在,您可以在音频与语音中选择合适的工作流并查阅通用音频术语。如需连续翻译,请参阅实时翻译。如需生成实时字幕,请参阅实时转写。如需转写已录制的音频,请参阅文件转写。