使用 Realtime API 构建语音到语音智能体。模型直接处理音频、维护对话状态，并且可以调用工具。本指南从使用 Agents SDK 构建浏览器应用入手；如果您需要直接控制底层连接，请参阅相应的连接指南。
如需将任务委派给独立后端的全双工对话，请参阅 GPT-Live。如需比较语音架构和链式流水线，请参阅语音智能体。
构建语音到语音智能体
如果您希望交互像自然对话一样流畅、即时，请使用 Realtime API。对于需要支持插话打断、低首段音频延迟、自然轮流发言以及实时工具调用的语音智能体，这是最佳起点。
浏览器中的典型流程如下：
- 您的应用服务器为实时会话创建临时客户端密钥。
- 您的前端创建一个
RealtimeSession。 - 会话在浏览器中通过 WebRTC 连接，在服务器上通过 WebSocket 连接。
- 智能体在该会话中处理音频轮次、工具、中断和任务移交。
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.1",
});
await session.connect({
apiKey: "ek_...(ephemeral key from your server)",
});接下来，您可以像为文本智能体添加工具、任务移交和护栏一样，将它们添加到 RealtimeAgent。在会话层处理音频传输，在智能体定义中保留业务逻辑。
如果您需要更底层的控制，请先参阅传输文档：
安全标识符
如果您的应用能够识别各个最终用户，请在 Realtime API 请求中包含安全标识符。OpenAI 建议使用安全标识符，但不作强制要求。它们有助于 OpenAI 检测有害行为，并针对单个用户而非您的整个组织采取处置措施。请使用稳定且能保护隐私的值，例如经过哈希处理的内部用户 ID。
对于 Realtime API 请求，请在 OpenAI-Safety-Identifier 请求头中发送该标识符。使用临时 Token 时，请在创建客户端密钥的服务端请求中设置该请求头，以将标识符与会话关联。从受信任的服务器通过 WebSocket 或统一 WebRTC 接口连接时，请在连接请求中设置该请求头。
安全标识符不会从 Responses API 请求或其他会话中自动沿用。如果您在应用的其他位置使用了 Responses API 的 safety_identifier 参数，请在创建或连接每个实时会话时传入同一个稳定值。
从 Beta 迁移到正式版（GA）
如果您仍在使用 Realtime 测试版集成，请先将其迁移到正式版（GA）接口，再开展新的开发工作。最重要的变化如下：
- 调用 GA 接口时，请移除
OpenAI-Beta: realtime=v1请求头。 - 使用
POST /v1/realtime/client_secrets为浏览器或移动客户端创建临时凭据。 - 建立 WebRTC 会话时，请使用
/v1/realtime/calls。 - 更新会话和事件的数据结构，以适配 GA 接口。具体而言，请设置
session.type，将输出音频配置移至session.audio.output下，并使用较新的响应事件名称，例如response.output_text.delta、response.output_audio.delta和response.output_audio_transcript.delta。 - 如果您正在升级语音到语音应用，请从浏览器示例入手。如果您正在升级转录工作流，请参阅实时转录。
有关当前 GA 版本的流程，请参阅实时客户端事件参考资料、实时会话参考资料和浏览器示例。
后续步骤
- 管理对话：配置会话并处理音频、文本和事件。
- 语音活动检测：配置自动轮次检测。
- 工具和 MCP：添加函数、MCP 服务器和连接器。
- 语音模型提示词：参阅适用于您的 Realtime 模型的指南。
- 成本优化：了解 Realtime 的用量核算和缓存机制。
- 服务端控制：在您的服务器上执行工具并控制会话。
其他音频工作流
工作流选择工具和通用音频术语现已移至音频与语音。如需持续翻译，请使用实时翻译。如需实时字幕，请使用实时转录；对于录制的音频，请使用文件转录。