追踪 Gemini Live 应用

此集成目前处于测试阶段，其 API 可能会发生变化。

Gemini Live 是一种语音到语音的模型，它通过 WebSocket 流式传输类型化事件。无论您是使用原始的 google-genai 连接还是 Google 智能体开发工具包 (ADK) 进行构建，此集成都会将每次对话捕获为一个单一的 LangSmith 追踪，其中包含用于转录文本、模型响应、工具调用、对话轮次边界和中断的跨度。将您的 Gemini Live 语音智能体追踪到 LangSmith。有关高级约定，请参阅语音追踪基础。要追踪使用 ADK 构建的非实时文本智能体、工具和多智能体工作流，请参阅追踪 Google ADK 应用。

选择一种方法

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

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

安装

使用 Gemini Live 客户端

为原始的 google-genai 连接安装 gemini-live 附加组件：

pip install "langsmith[gemini-live]"

uv add "langsmith[gemini-live]"

使用 Google ADK

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

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

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

ADK Live 集成要求 langsmith[google-adk-live]>=0.9.7。此附加组件与用于批量处理的 langsmith[google-adk] 集成是分开的。

设置环境变量

.env

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():
        ...  # 播放音频、运行工具、处理用户打断，并更新 UI

转录是可选启用的。要在追踪中显示转录文本，请在 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 会话创建一个包装器。每个包装器拥有独立的追踪和转录状态，因此并发对话保持独立。

录制对话音频

将麦克风和回放音频输入到包装后的会话中，以附加单个立体声录音，用户在左声道，智能体在右声道：

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,
):
    # 在播放后录音，这样因用户打断而丢弃的音频会被省略。
    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 格式录制两个声道。从扬声器录制智能体的音频，这样附件仅反映用户听到的内容。有关底层附件 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,
):
    ...  # 播放音频、处理用户打断，并更新 UI

转录是可选启用的。要显示转录文本，请在 RunConfig 上设置 input_audio_transcription 和 output_audio_transcription。

在正常结束时（当实时请求队列关闭），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。

录制对话音频

将麦克风和回放音频输入到插件中，以附加单个立体声录音，用户在左声道，智能体在右声道：

plugin.record_user_audio(mic_chunk)      # 用户麦克风 PCM16 数据
plugin.record_agent_audio(played_chunk)  # 智能体实际播放的 PCM16 数据

在将用户麦克风捕获的数据重采样供 ADK 使用之前进行录制，并从扬声器录制智能体的音频。以相同的采样率输入两个声道。插件的 sample_rate 默认为 24 kHz。有关底层附件 API，请参阅随追踪上传文件。

后续步骤

语音基础

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

随追踪上传文件

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

选择一种方法

安装

使用 Gemini Live 客户端

使用 Google ADK

设置环境变量

使用 Gemini Live 客户端

设置追踪

将对话分组到一个线程中

录制对话音频

使用 Google ADK

设置追踪

将对话分组到一个线程中

录制对话音频

后续步骤

语音基础

随追踪上传文件

​选择一种方法

​安装

​使用 Gemini Live 客户端

​使用 Google ADK

​设置环境变量

​使用 Gemini Live 客户端

​设置追踪

​将对话分组到一个线程中

​录制对话音频

​使用 Google ADK

​设置追踪

​将对话分组到一个线程中

​录制对话音频

​后续步骤

语音基础

随追踪上传文件

选择一种方法

安装

使用 Gemini Live 客户端

使用 Google ADK

设置环境变量

使用 Gemini Live 客户端

设置追踪

将对话分组到一个线程中

录制对话音频

使用 Google ADK

设置追踪

将对话分组到一个线程中

录制对话音频

后续步骤