OpenAI Agents Python Realtime Transport 选型指南：WebSocket 与 SIP 接入路径全解析-北京尧图网络

OpenAI Agents Python Realtime Transport 选型指南WebSocket 与 SIP 接入路径全解析【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python在基于 openai-agents-python 构建实时语音应用时首先要回答的问题通常是我的 Python 服务应该用哪种 transport 把 Realtime Agent 接到 Realtime API 上本文以官方文档 Realtime transport 为核心系统梳理本 SDK 支持的两种服务端 transportserver-side WebSocket 与 SIP attach、transport_config低层调优参数、RealtimeModelConfig自定义端点能力并结合仓库源码src/agents/realtime/openai_realtime.py、src/agents/realtime/model.py、src/agents/realtime/runner.py与真实示例examples/realtime深入讲解底层实现。读完本文你将能够根据自己的部署形态自建服务、电话/ SIP 呼叫、浏览器 WebRTC 客户端正确选择 transport并完成 WebSocket 参数调优与自定义端点接入。先做决定三种 transport 路径的适用场景Python SDK 的实时语音能力建立在 OpenAI Realtime API 之上但不包含浏览器端的 WebRTC transport那是独立的平台主题。因此本文只讨论 Python SDK 相关的两类服务端接入方式服务端 WebSocket 会话与 SIP attach 流程。官方文档给出的决策表如下目标起点原因构建服务端托管的实时应用Realtime quickstartPython 默认路径是由RealtimeRunner管理的服务端 WebSocket 会话决定选用哪种 transport 与部署形态本文在承诺采用某一种 transport 或部署形态之前先阅读本文将 Agent 接入电话或 SIP 呼叫Realtime agents guide 与 examples/realtime/twilio_sip仓库自带基于call_id的 SIP attach 流程一句话总结决策逻辑默认走服务端 WebSocket接电话走 SIP attach浏览器客户端请直接参考官方 Realtime API 的 WebRTC 文档本仓库不会提供浏览器侧RTCPeerConnection抽象或现成的 WebRTC 示例。服务端 WebSocketPython 默认路径RealtimeRunner在未传入自定义RealtimeModel时默认使用OpenAIRealtimeWebSocketModel见 runner.py 中self._model model if model is not None else OpenAIRealtimeWebSocketModel()。这意味着标准 Python 拓扑是Python 服务创建RealtimeRunnerawait runner.run()返回一个RealtimeSession以异步上下文管理器方式进入RealtimeSession然后发送文本、结构化消息或音频消费RealtimeSessionEvent事件流把音频或转写文本转发给你的应用。这条路径适合服务端持有音频管线、工具执行、审批流程和历史记录的场景也是仓库内核心 demo 应用、CLI 示例和 Twilio Media Streams 示例共同使用的拓扑examples/realtime/appFastAPI WebSocket 的浏览器语音 Demo服务端转发input_image等结构化消息见 server.pyexamples/realtime/cli终端 CLI 语音 Demodemo.py 使用sounddevice采集/播放音频并携带RealtimePlaybackTrackerexamples/realtime/twilioTwilio Media Streams 电话接入示例server.py 通过 TwiML 把呼叫桥接到/media-streamWebSocket。低层 WebSocket 调优transport_config当你需要调整底层服务端 WebSocket 连接时把transport_config传给OpenAIRealtimeWebSocketModelfrom agents.realtime import ( OpenAIRealtimeWebSocketModel, RealtimeAgent, RealtimeRunner, ) agent RealtimeAgent(nameAssistant) model OpenAIRealtimeWebSocketModel( transport_config{ ping_interval: 20.0, ping_timeout: 60.0, handshake_timeout: 30.0, max_size: 8 * 1024 * 1024, } ) runner RealtimeRunner(starting_agentagent, modelmodel)transport_config支持的全部选项如下参数含义默认行为ping_interval客户端保活 ping 的间隔秒数通常为20.0设为None可禁用 pingping_timeout等待 pong 后判定断开的秒数设为None可容忍延迟 pong不因心跳超时断开handshake_timeout等待初始连接握手的秒数对应 websockets 库的open_timeoutmax_size单个入站 WebSocket 消息的最大字节数SDK 默认为None不限大小需要约束单条消息内存占用时显式设置这些设置配置的是客户端连接本身而非 Realtime API 会话。端点、认证、呼叫 attach 与播放跟踪等会话级配置仍然通过RealtimeModelConfig完成。从源码看TransportConfig定义在 openai_realtime.py其 docstring 明确说明ping_interval默认通常为 20.0、max_size默认None不限制并指出限制消息大小适用于位于代理之后或内存受限容器中的长连接。真正的连接建立发生在_create_websocket_connectionopenai_realtime.pySDK 把ping_interval、ping_timeout、max_size原样透传给websockets.connect并把handshake_timeout映射为open_timeout未传入transport_config时默认仍携带user_agent_header和max_sizeNone。仓库测试 tests/realtime/test_openai_realtime.py 验证了handshake_timeout会作为open_timeout透传、空transport_config不会注入多余参数、ping_interval: None可禁用 ping 等行为可作为你调优时的回归依据。连接建立背后的实现细节OpenAIRealtimeWebSocketModel.connect()openai_realtime.py展示了 WebSocket 路径的完整建立流程理解它有助于排查连接问题端点 URL 构造未显式传入url时非 attach 场景使用wss://api.openai.com/v1/realtime?model{model}传入call_id时则改为wss://api.openai.com/v1/realtime?call_id{call_id}。注意call_id与model_name不能同时指定否则抛出UserErrorCannot specify bothcall_idandmodel_name。认证头未传headers时SDK 使用Authorization: Bearer {api_key}api_key来自model_config[api_key]支持字符串或可调用对象缺省则回退到OPENAI_API_KEY环境变量见get_api_keyopenai_realtime.py一旦你显式传入headersSDK 不再自动注入Authorization。建连后创建监听任务_listen_for_messages并通过session.update事件下发会话配置。服务端正常关闭连接时transport 依次发出RealtimeModelConnectionStatusEvent(statusdisconnected)与RealtimeModelEndOfStreamEvent见_emit_normal_disconnectopenai_realtime.pyRealtimeSession会在raw_model_event中转发它们、排空已排队事件后正常结束迭代而不抛异常。SIP attach电话路径仓库文档化的电话流程中Python SDK 通过call_id挂接到一个已存在的实时通话。拓扑如下OpenAI 向你的服务发送realtime.call.incoming之类的 webhook你的服务通过 Realtime Calls API 接受该呼叫Python 服务启动RealtimeRunner(..., modelOpenAIRealtimeSIPModel())会话以model_config{call_id: ...}连接之后像普通实时会话一样处理事件。这一拓扑的完整落地见 examples/realtime/twilio_sip 中的 server.pyFastAPI 在/openai/webhook校验签名OPENAI_WEBHOOK_SECRET后对realtime.call.incoming事件先调用accept_call(call_id)通过client.post(f/realtime/calls/{call_id}/accept, ...)调用 Realtime Calls API再以OpenAIRealtimeSIPModel()创建 runner用model_config{call_id: call_id, initial_model_settings: {...}}进入会话attach 成功后立即通过session.model.send_event(RealtimeModelSendRawMessage(...))发送一条原始response.create强制说出开场白随后在async for event in session中记录对话转写。OpenAIRealtimeSIPModel继承自OpenAIRealtimeWebSocketModelopenai_realtime.py其connect()强制要求model_config中必须提供call_id否则抛出UserError。此外它还提供静态方法build_initial_session_payload(...)当需要先接受呼叫、并希望 accept 载荷与 Agent 派生的会话配置一致时用它构造OpenAISessionCreateRequest转发给 Realtime Calls API从而避免重复实现会话设置逻辑。更广泛的 Realtime API 也在部分服务端控制模式中使用call_id但本仓库随附的 attach 示例是 SIP。Browser WebRTC不在 SDK 范围内如果应用的主要客户端是使用 Realtime WebRTC 的浏览器将其视为本仓库 Python SDK 文档范围之外的主题浏览器侧流程与事件模型请参考官方 Realtime API 的 WebRTC 与 conversations 文档如果除浏览器 WebRTC 客户端外还需要一条旁路sideband服务端连接参考官方 Realtime server-side controls 指南不要期望本仓库提供浏览器侧RTCPeerConnection抽象或现成的浏览器 WebRTC 示例。当前仓库同样没有随附浏览器 WebRTC Python sideband组合示例。RealtimeRunner的 docstring 也印证了这一边界Since this code runs on your server, it uses WebSockets by default.见 runner.py。自定义端点与 attach 点RealtimeModelConfig[RealtimeModelConfig][agents.realtime.model.RealtimeModelConfig]定义于 src/agents/realtime/model.py是 transport 的配置面让你定制默认传输行为字段作用url覆盖 WebSocket 端点headers显式提供请求头例如 Azure 的认证头传入后 SDK 不再注入Authorizationapi_key直接传入 API key或传回调函数支持同步/异步返回 key缺省回退OPENAI_API_KEY环境变量call_idattach 到已存在的实时通话本仓库文档化的示例是 SIPplayback_tracker上报真实播放进度用于打断interruption处理initial_model_settings建连时使用的初始模型设置即RealtimeSessionModelSettingsplayback_tracker值得单独说明模型生成音频的速度远快于实时播放。低延迟本地播放场景下默认跟踪器假设音频立即以实时速度播放通常够用但在远程或延迟播放场景尤其是电话应传入RealtimePlaybackTrackermodel.py由你在真实播放字节时调用on_play_bytes(item_id, content_index, bytes)或on_play_ms(...)上报进度。这样发生打断时被中断的响应会在实际播放位置截断发送conversation.item.truncate见convert_interruptopenai_realtime.py而不是假设全部已生成音频都已被听到。Twilio 示例 examples/realtime/twilio/twilio_handler.py 就是通过model_config[playback_tracker]传入跟踪器的。实战接入 Azure OpenAI Realtime 端点连接 Azure OpenAI 时传入 GA Realtime 端点 URL 与显式请求头session await runner.run( model_config{ url: wss://your-resource.openai.azure.com/openai/v1/realtime?modeldeployment-name, headers: {api-key: your-azure-api-key}, } )若使用令牌认证则在headers中传 bearer tokensession await runner.run( model_config{ url: wss://your-resource.openai.azure.com/openai/v1/realtime?modeldeployment-name, headers: {authorization: fBearer {token}}, } )两个要点传入headers后 SDK 不会自动添加Authorization同时应避免使用旧的 beta 路径/openai/realtime?api-version...接入 realtime Agent。低层访问session.modelRealtimeSession暴露底层 transport 对象session.model在以下场景直接使用通过session.model.add_listener(...)注册自定义监听器RealtimeModelListener需实现on_event见 model.py发送原始客户端事件如response.create、session.update通过model_config自定义url、headers、api_key处理通过call_idattach 到已存在的实时通话。from agents.realtime.model_inputs import RealtimeModelSendRawMessage await session.model.send_event( RealtimeModelSendRawMessage( message{ type: response.create, } ) )send_event会根据事件类型分发到_send_user_input、_send_audio、_send_tool_output、_send_interrupt、_send_session_update或原始消息发送openai_realtime.py原始消息会经_ConversionHelper.try_convert_raw_message校验后发送。若实现自定义RealtimeModel还需关注send_event_if()条件发送须在真实提交边界重新检查条件默认实现安全地返回False与_retire_response_audio()释放响应音频索引这两个约定它们是 guardrail 恢复消息与打断行为正确工作的前提详见 Realtime agents guide 的 Guardrails 一节。选型后的下一步选定拓扑后建议继续阅读Realtime agents guide完整的会话生命周期、结构化输入、审批、handoff、guardrail 与低层控制Realtime quickstart五分钟跑通服务端 WebSocket 会话examples/realtime/app、examples/realtime/cli、examples/realtime/twilio、examples/realtime/twilio_sip四种真实部署形态的完整代码。关键结论服务端 WebSocket 是 Python 默认路径RealtimeRunner默认使用OpenAIRealtimeWebSocketModel适合服务端持有音频管线、工具、审批与历史的场景SIP attach 是电话路径通过OpenAIRealtimeSIPModelmodel_config{call_id: ...}挂接 Realtime Calls API 的入站呼叫仓库示例见 examples/realtime/twilio_sipWebRTC 属于浏览器侧平台话题Python SDK 不提供RTCPeerConnection抽象也不随附浏览器 WebRTC 示例transport_config管连接、RealtimeModelConfig管会话前者只调底层 WebSocketping、握手、消息大小后者负责端点、认证、attach 与播放跟踪显式传headers即放弃自动Authorization接入 Azure 等自定义端点时必须自行处理认证头。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenAI Agents Python Realtime Transport 选型指南：WebSocket 与 SIP 接入路径全解析

相关推荐

基于 context-retrieval-evals 的 Deep Agents 多文件上下文检索评测任务解析——以 cb-cloud-9 否定推理任务为例

OmX autoresearch 候选交接（candidate.json）契约：thin-supervisor 决策边界与 Parity 测试实战

嵌入式FFT谐波分析实战：从采样率到THD计算的完整实现

更多资讯

JAX 的 SciPy 兼容模块 jax.scipy 完全指南：从特殊函数到稀疏线性代数

GE图引擎AutoFuse融合策略

Spring Boot网上商城系统毕设全流程：从数据库设计到部署答辩

AI Agent记忆系统实战：从机制拆解到工程实现

SRS 视角下 WebRTC 直播的适用边界：何时该用、何时该放弃

2025年CSP-J初赛真题全解析：考点、避坑与备考策略

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？