此集成目前处于测试阶段,因此其 API 可能会发生变化。
OpenAI Realtime 是一个语音转语音模型,它通过 WebSocket 流式传输类型化事件。无论你是使用原始连接还是 OpenAI Agents SDK 来构建它,该集成都会将每次对话捕获为一个单独的 LangSmith 追踪,并将每个有意义的事件(转录、模型响应和工具调用)按轮次分组为跨度。 将你的 OpenAI Realtime API 语音智能体追踪到 LangSmith。有关高级约定,请参阅语音追踪基础。

选择一种方式

有两种方式可以使用 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 会将它们的事件关联起来。

录制对话音频

将你的麦克风和播放音频输入给代理:
你应该从扬声器录制智能体的音频,这样录音只反映实际播放的内容。在打断期间,生成的音频在播放前被丢弃,因此不应被录制。这样做可以确保追踪与用户实际听到的内容保持一致。

后续步骤

语音基础

追踪语音智能体的核心约定。

随追踪上传文件

将对话录音附加到你的追踪中。