OpenAI Agents SDK #17：两套语音子系统，你选对了吗？GPT-Realtime-2 今日上线

先说今天的大新闻

你以为是一个系统，其实是两套

• realtime/：RealtimeAgent、RealtimeRunner、RealtimeSession
• voice/：VoicePipeline、SingleAgentVoiceWorkflow、StreamedAudioResult

第一套：Voice Pipeline —— 三段流水线

# pip install 'openai-agents[voice]'
from agents.voice import VoicePipeline, SingleAgentVoiceWorkflow
from agents import Agent

agent = Agent(name="助手", model="gpt-5.5", instructions="你是一个语音助手")
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))

# 静态模式：一次录音 → 一次回复
result = await pipeline.run(audio_input)
async for event in result.stream():
    if event.type == "audio":
        player.play(event.data)  # 流式播放 TTS 音频

• AudioInput：静态缓冲输入（默认 24000Hz/16bit/单声道）
• StreamedAudioInput：流式输入，通过 add_audio() 持续推送
• StreamedAudioResult.stream()：返回 VoiceStreamEvent 异步迭代器，事件类型有 audio/lifecycle/error

• 需要用 gpt-5.5 等成熟模型处理复杂逻辑
• 对端到端延迟不是极度敏感（可以接受 600ms+）
• 已有 Agent 逻辑想快速接入语音能力

第二套：Realtime Agents —— 直通音频流

from agents.realtime import RealtimeAgent, RealtimeRunner, RealtimeRunConfig
from agents.realtime import RealtimeModelConfig, RealtimeSessionConfig

agent = RealtimeAgent(
    name="语音助手",
    instructions="你是一个简洁的语音助手，回答要短。",
    voice="alloy",               # 首次发言后不能更改
    handoffs=[support_agent],    # 支持 handoff
    tools=[lookup_order],        # 支持工具调用
)

runner = RealtimeRunner(
    agent,
    run_config=RealtimeRunConfig(async_tool_calls=True),  # 默认开启异步工具
    model_config=RealtimeModelConfig(api_key=os.environ["OPENAI_API_KEY"]),
)

async with runner.run() as session:
    # session 是 RealtimeSession，掌管一切
    await session.send_audio(audio_chunk)
    async for event in session:
        if event.type == "audio":
            player.play(event.data)
        elif event.type == "tool_approval_required":
            await session.approve_tool_call(event.approval_request)

⚠️「这个比喻在付费方面不成立」：直通隧道听起来便宜，实际上 Realtime API 的定价远比三段式方案贵，$32/MTok 的音频输入成本需要仔细核算。

RealtimeSession 才是真正的控制中枢

VAD + 打断：两个坑，几乎每个人都踩过

# 推荐配置示例（来自官方 server.py）
model_settings = {
    "audio": {
        "input": {
            "turn_detection": {
                "type": "server_vad",          # 或 "semantic_vad"
                "interrupt_response": True,    # 允许用户打断
                "prefix_padding_ms": 300,      # 防止截断开头
                "silence_duration_ms": 500,    # 500ms 静音才确认结束
            },
            "transcription": {
                "model": "gpt-4o-transcribe"   # 转录模型（可选）
            }
        },
        "output": {
            "voice": "alloy"
        }
    }
}

1. VAD 阈值太低 → 用户停顿 100ms 就被误判为说完 → 打断用户的话
2. 打断处理只停前端播放 → 服务端 LLM/TTS 流没取消，下次回复带上残留历史 → 上下文错乱
3. WebRTC 回声消除在 Safari/移动端效果差 → 必须多设备测试
4. 级联延迟失控 → 每层 P99 延迟叠加后，端到端 P99 会超出用户心理预期

传输层：WebSocket 还是 SIP 还是 WebRTC？

• OpenAIRealtimeWebSocketModel（默认）：服务器端 WebSocket，适合绝大多数后端服务
• OpenAIRealtimeSIPModel：SIP 电话集成，需要传 call_id 参数，适合 Twilio 等电话平台

RealtimeAgent 有什么不支持的，要提前知道

• ❌ 不支持 model 参数：模型由 Session 级统一管理，无法 per-agent 指定
• ❌ 不支持 structured outputs：Realtime API 不走结构化输出流程
• ❌ 不支持 toolUseBehavior：工具调用由 Runner 的 async_tool_calls 统一控制
• ⚠️ voice 首轮发言后不能更改：要换声线只能重开 session
• ✅ 支持 handoffs：用 realtime_handoff(agent) 或直接传 RealtimeAgent 列表
• ✅ 支持 output guardrails：基于去抖文本累积运行，debounce_text_length 默认 100 字符
• ❌ 不支持 input guardrails

四大厂商横评：OpenAI 体验最好，但不是唯一选择

延伸阅读：OpenAI 开源的 React 语音控制组件

SDK 版本快查

• v0.16.0：realtime guardrail fallback 文档补充
• v0.15.3：修复音频 delta 格式协商前抵达的问题（audio deltas before format negotiation）
• v0.15.2：补充 realtime 工具超时/边界 case 测试

实践建议

• 端到端 < 800ms 且音频质量优先 → RealtimeAgent（WebSocket 模式）
• 逻辑复杂或已有 Agent 代码 → VoicePipeline + SingleAgentVoiceWorkflow