此集成目前处于测试阶段,因此其 API 可能会发生变化。
选择一种方式
有两种方式可以使用 OpenAI Realtime API 进行构建,LangSmith 为每种方式都提供了追踪集成:- 如果你直接连接实时客户端,请使用
wrap_realtime。 - 如果你正在使用 OpenAI Agents SDK 构建,请改用
wrap_realtime_session。
安装
langsmith[openai-realtime]>=0.9.7 扩展包提供了这两个包装器:
设置环境变量
.env
使用 Realtime 客户端
当你使用client.realtime.connect() 自行打开 WebSocket 并驱动事件循环时,请使用此方式。
设置追踪
wrap_realtime 返回你的连接的一个透明代理。你现有的 async for event in connection 循环、session.update 和工具处理保持不变:
每次对话都被捕获为独立的追踪。要将其与 LangSmith 线程中的相关交互分组(例如继续之前的会话或从文本聊天中接续),请传递一个
thread_id。在不同追踪中重用相同的 ID 会将它们的事件关联起来。@traceable 工具都会自动嵌套在该事件下。
在你的
session.update 中启用 input_audio_transcription 和智能体转录,以便将转录作为追踪的一部分进行查看。录制对话音频
当你将麦克风和播放音频输入给代理时,它会将单个立体声录音(用户左声道,智能体右声道)附加到追踪中。要标记打断(barge-ins),请使用is_agent_speaking:
你应该从扬声器录制智能体的音频,这样录音只反映实际播放的内容。在打断期间,生成的音频在播放前被丢弃,因此不应被录制。这样做可以确保追踪与用户实际听到的内容保持一致。
使用 OpenAI Agents SDK
当你使用 OpenAI Agents SDK (RealtimeAgent / RealtimeRunner) 构建智能体(它负责管理轮次和工具调用循环)时,请使用此方式。
Agents SDK 的内置实时追踪会上传到 OpenAI 自己的仪表板。调用
agents.set_tracing_disabled(True) 以避免额外的、独立的上传路径。设置追踪
wrap_realtime_session 包裹 RealtimeSession 并为你进入其中。像处理原始对象一样迭代它;SDK 会运行工具并管理轮次:
history 快照重建的,因此即使 SDK 将它们作为部分内容流式传输,消息也会出现。
每次对话都被捕获为独立的追踪。要将其与 LangSmith 线程中的相关交互分组(例如继续之前的会话或从文本聊天中接续),请传递一个
thread_id。在不同追踪中重用相同的 ID 会将它们的事件关联起来。录制对话音频
将你的麦克风和播放音频输入给代理:你应该从扬声器录制智能体的音频,这样录音只反映实际播放的内容。在打断期间,生成的音频在播放前被丢弃,因此不应被录制。这样做可以确保追踪与用户实际听到的内容保持一致。
后续步骤
语音基础
追踪语音智能体的核心约定。
随追踪上传文件
将对话录音附加到你的追踪中。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

