追踪 Gemini Live 应用

使用 LangSmith SDK 在 LangSmith 中追踪 Gemini Live 语音 agent。

NOTE

此集成处于 beta 阶段，因此其 API 可能会发生变化。

Gemini Live 是一种通过 WebSocket 流式传输类型化事件的语音到语音模型。无论你是使用原始 google-genai 连接还是 Google Agent Development Kit (ADK) 构建，该集成都会将每个对话捕获为单条 LangSmith 追踪，并为转录、模型响应、工具调用、轮次边界和中断提供 span。

将你的 Gemini Live 语音 agent 追踪到 LangSmith。有关高层约定，请参阅语音追踪基础。

要追踪使用 ADK 构建的非实时文本 agent、工具和多 agent 工作流，请参阅追踪 Google ADK 应用。

选择一种方法

LangSmith 为每种连接 Gemini Live 的方式提供追踪集成：

• 如果你使用 client.aio.live.connect(...) 直接连接，请使用 wrap_gemini_live。
• 如果你使用 Google ADK 构建，请使用 LangSmithGoogleADKLivePlugin。

安装

使用 Gemini Live 客户端

为原始 google-genai 连接安装 gemini-live 附加项：

pip

pip install "langsmith[gemini-live]"

uv

uv add "langsmith[gemini-live]"

使用 Google ADK

为 ADK 应用安装 google-adk-live 附加项：

pip

pip install "langsmith[google-adk-live]"

uv

uv add "langsmith[google-adk-live]"

NOTE

ADK Live 集成需要 langsmith[google-adk-live]>=0.9.7。此附加项与 langsmith[google-adk] 批处理集成分开。

设置环境变量

LANGSMITH_API_KEY=<your-langsmith-api-key>
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=<your-desired-langsmith-project>
GOOGLE_API_KEY=<your-google-api-key>
GEMINI_LIVE_MODEL=<your-gemini-live-model>

使用 Gemini Live 客户端

当你的应用使用 client.aio.live.connect(...) 打开 WebSocket 并拥有音频和工具循环时，请使用此方法。

设置追踪

在实时配置中启用输入和输出转录。wrap_gemini_live 返回连接会话的透明代理，因此你现有的接收循环、音频处理和工具分发保持不变：

import os

from google import genai
from google.genai import types
from langsmith.integrations.gemini_live import wrap_gemini_live

model = os.environ["GEMINI_LIVE_MODEL"]
client = genai.Client()
config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
)

async with (
    client.aio.live.connect(model=model, config=config) as raw,
    wrap_gemini_live(
        raw,
        model=model,
        project_name="gemini-live-voice",
    ) as session,
):
    async for message in session.receive():
        ...  # play audio, run tools, handle barge-ins, and update the UI

NOTE

转录需要选择启用。要在追踪中显示转录，请在 LiveConnectConfig 上同时设置 input_audio_transcription 和 output_audio_transcription。

将对话分组到线程

每个被包装的会话都会捕获为单独的追踪，并具有自己的线程 ID。要提供 ID（例如将对话与 LangSmith 线程中的相关交互分组），请传递 thread_id：

wrap_gemini_live(
    raw,
    model=model,
    thread_id=thread_id,
    project_name="gemini-live-voice",
)

为每个连接的 Gemini Live 会话创建一个包装器。每个包装器拥有独立的追踪和转录状态，因此并发对话保持分离。

录制对话音频

将麦克风和播放音频提供给被包装的会话，以附加单个立体声录音，用户在左声道，agent 在右声道：

RECORDING_SAMPLE_RATE = 24_000

async with (
    client.aio.live.connect(model=model, config=config) as raw,
    wrap_gemini_live(
        raw,
        model=model,
        sample_rate=RECORDING_SAMPLE_RATE,
        is_agent_speaking=lambda: speaker.buffered_bytes() > 0,
    ) as session,
):
    # Record audio after playback so discarded audio from a barge-in is omitted.
    speaker.set_played_callback(session.record_agent_audio)

    async def send_mic(mic_chunk):
        await session.send_realtime_input(
            audio=types.Blob(
                data=mic_chunk,
                mime_type=f"audio/pcm;rate={microphone.sample_rate}",
            )
        )
        session.record_user_audio(
            resample_pcm16(
                mic_chunk,
                microphone.sample_rate,
                RECORDING_SAMPLE_RATE,
            )
        )

以包装器的 sample_rate 将两个声道录制为 PCM16。从扬声器录制 agent 的音频，以便附件仅反映用户听到的内容。有关底层附件 API，请参阅使用追踪上传文件。

使用 Google ADK

当 ADK 拥有 Gemini Live 会话和工具循环时，请使用此方法。

设置追踪

导入 LangSmithGoogleADKLivePlugin 并将其注册到 Runner 上。它与你的 run_live 循环一起运行，因此你的循环只需处理音频播放、打断和 UI 更新：

from google.adk.agents.run_config import RunConfig, StreamingMode
from google.adk.runners import Runner
from google.genai import types as genai_types
from langsmith.integrations.google_adk_live import LangSmithGoogleADKLivePlugin

plugin = LangSmithGoogleADKLivePlugin(project_name="gemini-live-voice")

runner = Runner(
    app_name="voice-app",
    agent=root_agent,
    session_service=session_service,
    plugins=[plugin],
)

run_config = RunConfig(
    response_modalities=["AUDIO"],
    streaming_mode=StreamingMode.BIDI,
    input_audio_transcription=genai_types.AudioTranscriptionConfig(),
    output_audio_transcription=genai_types.AudioTranscriptionConfig(),
)

async for event in runner.run_live(
    user_id=user_id,
    session_id=adk_session.id,
    live_request_queue=queue,
    run_config=run_config,
):
    ...  # play audio, handle barge-ins, and update the UI

NOTE

转录需要选择启用。要显示转录，请在 RunConfig 上同时设置 input_audio_transcription 和 output_audio_transcription。

NOTE

在正常结束时，当实时请求队列关闭时，ADK 会发送其 after_run 回调，插件会完成追踪。

在取消运行时（例如控制台应用在 Ctrl-C 时停止 run_live），ADK 可能不会发送该回调。请在清理期间调用 plugin.finalize(session_id=adk_session.id)，以完成追踪和音频附件。该调用是幂等的，因此如果 ADK 的回调已经运行，它不会执行任何操作。

将对话分组到线程

每个对话都会捕获为单独的追踪，并具有自己的线程 ID。要提供 ID（例如将对话与 LangSmith 线程中的相关交互分组），请向插件传递 thread_id_provider：

plugin = LangSmithGoogleADKLivePlugin(
    project_name="gemini-live-voice",
    thread_id_provider=lambda: thread_id,
)

单个插件实例在每次 run_live 调用之间共享，并在每个对话开始时解析一次线程 ID。默认值使并发对话保持分离。如果你在处理并发对话的服务器上传递 thread_id_provider，请返回当前对话的 ID，例如读取每次运行开始时设置的 ContextVar。

录制对话音频

将麦克风和播放音频提供给插件，以附加单个立体声录音，用户在左声道，agent 在右声道：

plugin.record_user_audio(mic_chunk)      # user mic PCM16
plugin.record_agent_audio(played_chunk)  # agent PCM16 as played

在为用户麦克风捕获重新采样供 ADK 使用之前录制它，并从扬声器录制 agent 的音频。以相同采样率提供两个声道。插件的 sample_rate 默认为 24 kHz。有关底层附件 API，请参阅使用追踪上传文件。

后续步骤

•Voice fundamentals

追踪语音 agent 的核心约定。

•Upload files with traces

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

---