此集成处于 Beta 阶段,其 API 可能会发生变化。
LiveKit 集成需要
langsmith[livekit]>=0.9.7。安装
安装此集成以及您的代理所使用的 LiveKit 插件:设置环境变量
该集成从环境变量中读取您的 LangSmith 凭证,并通过 OpenTelemetry 为您导出到 LangSmith:.env
设置追踪
在创建AgentServer 之前,导入 configure_livekit 并调用一次。它会构建追踪器提供者,注册 LangSmith 跨度处理器,并将其接入 LiveKit:
lk_openai.realtime.RealtimeModel(...))需要额外调用以捕获用户的转录文本。请参阅当 LiveKit 与实时模型一起使用时。
使用您自己的追踪器提供者
configure_livekit() 会构建一个 TracerProvider,注册 LangSmith 跨度处理器,并将其接入 LiveKit。如果您想使用自己管理的 TracerProvider,请自行构建处理器,将其添加到您的提供者中,并通过 LiveKit 的追踪器钩子注册该提供者。LiveKit 仅通过其追踪器绑定的提供者发出跨度:
将对话分组到一个线程中
要将对话的运行分组到一个 LangSmith 线程中,以便进行线程级视图以及令牌和成本聚合,请在@server.rtc_session() 处理程序内、在发出跨度之前,对每次对话调用一次 set_thread_id:
当 LiveKit 与实时模型一起使用时
对于语音到语音(实时)模型,没有单独的语音转文本步骤,因此 LiveKit 会异步转录用户的音频,并通过会话的user_input_transcribed 事件传递转录文本,而不是通过其发出的 OTel 追踪。
instrument_session 需要 langsmith[livekit]>=0.10.4。AgentSession 后立即调用 instrument_session 一次,这样 SDK 就会为您订阅该事件,并将每次转录与其对应的轮次配对。它通过线程 ID 进行关联,因此请先使用 set_thread_id 设置它,并传递相同的 ID:
instrument_session。在 STT/LLM/TTS 级联中,转录文本已经(从语音转文本步骤中)被捕获,因此在那里调用它会将用户轮次记录两次。
记录音频
该集成将通话录音附加到对话的根跨度上。您如何捕获录音在本地开发和生产环境之间有所不同。开发:嵌入本地文件
在控制台和本地开发环境中,启用 LiveKit 的会话录制,并将audio_path_provider 指向 LiveKit 在 ctx.session_directory 下写入的 audio.ogg。该集成读取该文件并将字节嵌入到追踪中。
--record。录音反映的是播放给客户端的内容,因此抢占式输入会被截断。
生产环境:使用 Egress 录制并附加文件
在生产环境中,使用 LiveKit Egress 将房间录制到您自己的对象存储中,然后将完成的录音作为真正的音频附件附加到追踪上。Egress 在通话结束后才完成上传,因此集成会保持对话的根跨度处于打开状态,直到您提供字节:- 当您启动 Egress 时调用
processor.expect_recording(thread_id)。 - 通话结束后,等待 Egress 完成,从您的存储下载文件,然后调用
processor.complete_recording(thread_id, audio_bytes)。集成将嵌入字节并导出追踪。
thread_id,以便录音匹配到正确的对话。
wait_for_egress 会轮询 list_egress 直到状态为 EGRESS_COMPLETE(或订阅 egress_ended webhook),而 download_from_storage 会使用您的云提供商客户端读取对象。LiveKit Egress 也可以写入 Google Cloud Storage 和 Azure:将 s3= 替换为 gcp=api.GCPUpload(...) 或 azure=api.AzureBlobUpload(...)。
始终要调用
complete_recording,因为追踪的根跨度会保持打开状态直到它运行,包括在失败时使用 data=None。如果 worker 先停止,集成将在没有音频的情况下刷新追踪。后续步骤
语音基础
追踪语音代理的核心约定。
随追踪上传文件
将对话音频录音附加到您的追踪。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

