指南
本指南深入介绍如何使用 OpenAI Agents SDK 的实时能力来构建语音功能的 AI 智能体。
测试版功能
Realtime 智能体处于测试阶段。随着实现的改进，可能会出现不兼容的变更。
概览
Realtime 智能体支持对话式流程，实时处理音频与文本输入，并以实时音频作出回应。它们与 OpenAI 的 Realtime API 保持持久连接，从而实现低时延的自然语音对话，并能优雅地处理打断。
架构
核心组件
实时系统由以下关键组件构成：
- RealtimeAgent: 一个智能体，配置有 instructions、tools 和 handoffs。
- RealtimeRunner: 管理配置。可调用
runner.run()获取一个会话。 - RealtimeSession: 单次交互会话。通常在每次用户开始对话时创建一个，并保持到对话结束。
- RealtimeModel: 底层模型接口（通常是 OpenAI 的 WebSocket 实现）
会话流程
典型的实时会话遵循以下流程：
- 创建 RealtimeAgent，配置 instructions、tools 和 handoffs。
- 设置 RealtimeRunner，传入智能体和相关配置选项
- 启动会话，使用
await runner.run()返回一个 RealtimeSession。 - 发送音频或文本消息，通过
send_audio()或send_message() - 监听事件，通过迭代会话对象获取事件——事件包括音频输出、转写结果、工具调用、任务转移和错误
- 处理打断，当用户打断发言时，当前音频生成会自动停止
会话会维护对话历史，并管理与实时模型的持久连接。
智能体配置
RealtimeAgent 的工作方式与常规 Agent 类相似，但有一些关键差异。完整 API 详情参见RealtimeAgent API 参考。
相较于常规智能体的主要差异：
- 模型选择在会话级别配置，而非智能体级别。
- 不支持 structured output（不支持
outputType）。 - 可为每个智能体配置语音，但在首个智能体开始说话后不能再更改。
- 其他功能如 tools、handoffs 和 instructions 的工作方式相同。
会话配置
模型设置
会话配置允许你控制底层实时模型行为。你可以配置模型名称（例如gpt-realtime）、语音选择（alloy、echo、fable、onyx、nova、shimmer），以及支持的模态（文本和/或音频）。音频格式可为输入和输出分别设置，默认是 PCM16。
音频配置
音频设置控制会话如何处理语音输入与输出。你可以配置使用 Whisper 等模型进行输入音频转写，设置语言偏好，并提供转写提示以提升领域术语的准确性。轮次检测设置控制智能体何时开始和停止响应，可选项包括语音活动检测阈值、静音时长和检测语音的前后填充。
工具与函数
添加工具
与常规智能体一样，实时智能体支持在对话中执行的工具调用（function tools）：
fromagentsimportfunction_tool@function_tooldefget_weather(city:str)->str:"""Get current weather for a city."""# Your weather API logic herereturnf"The weather in{city} is sunny, 72°F"@function_tooldefbook_appointment(date:str,time:str,service:str)->str:"""Book an appointment."""# Your booking logic herereturnf"Appointment booked for{service} on{date} at{time}"agent=RealtimeAgent(name="Assistant",instructions="You can help with weather and appointments.",tools=[get_weather,book_appointment],)任务转移
创建任务转移
任务转移允许在不同的专业化智能体之间转交对话。
fromagents.realtimeimportrealtime_handoff# Specialized agentsbilling_agent=RealtimeAgent(name="Billing Support",instructions="You specialize in billing and payment issues.",)technical_agent=RealtimeAgent(name="Technical Support",instructions="You handle technical troubleshooting.",)# Main agent with handoffsmain_agent=RealtimeAgent(name="Customer Service",instructions="You are the main customer service agent. Hand off to specialists when needed.",handoffs=[realtime_handoff(billing_agent,tool_description="Transfer to billing support"),realtime_handoff(technical_agent,tool_description="Transfer to technical support"),])事件处理
会话会以流式传输的方式发送事件，你可以通过迭代会话对象来监听。事件包括音频输出分片、转写结果、工具执行开始与结束、智能体任务转移和错误。需要重点处理的事件包括：
- audio: 来自智能体响应的原始音频数据
- audio_end: 智能体结束发言
- audio_interrupted: 用户打断了智能体
- tool_start/tool_end: 工具执行的生命周期
- handoff: 发生了智能体任务转移
- error: 处理过程中发生错误
完整事件详情参见RealtimeSessionEvent。
安全防护措施
Realtime 智能体仅支持输出安全防护措施。这些防护经过去抖处理并周期性运行（不会对每个词触发），以避免实时生成过程中的性能问题。默认去抖长度为 100 个字符，但可配置。
安全防护措施可以直接附加到RealtimeAgent 上，或通过会话的run_config 提供。来自这两处的防护会一同运行。
fromagents.guardrailimportGuardrailFunctionOutput,OutputGuardraildefsensitive_data_check(context,agent,output):returnGuardrailFunctionOutput(tripwire_triggered="password"inoutput,output_info=None,)agent=RealtimeAgent(name="Assistant",instructions="...",output_guardrails=[OutputGuardrail(guardrail_function=sensitive_data_check)],)当某项安全防护被触发时，会生成guardrail_tripped 事件，并可中断智能体当前的响应。去抖行为有助于在安全性与实时性能要求之间取得平衡。与文本智能体不同，Realtime 智能体在触发安全防护时并不会抛出 Exception。
音频处理
使用session.send_audio(audio_bytes) 发送音频到会话，或使用session.send_message() 发送文本。
对于音频输出，监听audio 事件，并通过你偏好的音频库播放音频数据。务必监听audio_interrupted 事件，以便在用户打断智能体时立即停止播放并清空任何已排队的音频。
SIP 集成
你可以将实时智能体附加到通过Realtime Calls API 到达的电话。SDK 提供了OpenAIRealtimeSIPModel，在通过 SIP 协商媒体的同时复用相同的智能体流程。
要使用它，将该模型实例传递给 runner，并在启动会话时提供 SIP 的call_id。呼叫 ID 会由指示来电的 webhook 传递。
fromagents.realtimeimportRealtimeAgent,RealtimeRunnerfromagents.realtime.openai_realtimeimportOpenAIRealtimeSIPModelrunner=RealtimeRunner(starting_agent=agent,model=OpenAIRealtimeSIPModel(),)asyncwithawaitrunner.run(model_config={"call_id":call_id_from_webhook,"initial_model_settings":{"turn_detection":{"type":"semantic_vad","interrupt_response":True},},},)assession:asyncforeventinsession:...当来电者挂断时，SIP 会话结束，实时连接会自动关闭。完整电话示例参见examples/realtime/twilio_sip。
直接访问模型
你可以访问底层模型以添加自定义监听器或执行高级操作：
这将为你提供对RealtimeModel 接口的直接访问，适用于需要对连接进行更底层控制的高级用例。
示例
要查看完整可运行的示例，请访问examples/realtime 目录，其中包含带有和不带 UI 组件的演示。