实时智能体的配置

Supported in ADKPython v0.1.0Java v0.2.0

RunConfig 是你配置实时会话的地方：智能体的声音、语音转录方式、轮次结束的判断、保留多少历史记录，以及运行时的限制条件。你将它传给 Runner.run_live()，它仅对该会话生效。同一智能体的两个用户可以使用完全不同的配置。

RunConfig 并非实时专用；运行时配置 记录了完整的类以及适用于 run_async() 的字段。以下是与 run_live() 相关的子集，以及仅存在于实时会话中的语音相关设置。

RunConfig 参数速查表

此表提供了对实时智能体最重要的 RunConfig 参数的速查参考：

Parameter	Type	Purpose	Reference
response_modalities	list[str]	Output format. Live agents must use AUDIO — Live models do not accept TEXT	Details
streaming_mode	StreamingMode	Chunked or single-shot delivery on the run_async() path; not read by run_live()	Details
session_resumption	SessionResumptionConfig	Enable automatic reconnection	Details
context_window_compression	ContextWindowCompressionConfig	Unlimited session duration	Details
history_config	HistoryConfig	Control how prior conversation history is replayed to the Live server	Details
max_llm_calls	int	Limit total LLM calls per session	Details
save_live_blob	bool	Persist audio/video streams	Details
custom_metadata	dict[str, Any]	Attach metadata to invocation events	Details
speech_config	SpeechConfig	Voice and language configuration	Voice and language
input_audio_transcription	AudioTranscriptionConfig	Transcribe user speech	Audio transcription
output_audio_transcription	AudioTranscriptionConfig	Transcribe model speech	Audio transcription
realtime_input_config	RealtimeInputConfig	VAD configuration	Voice activity detection
explicit_vad_signal	bool	Emit voice activity events from the model	Details
proactivity	ProactivityConfig	Enable proactive audio (model-specific)	Proactivity and affective dialog
enable_affective_dialog	bool	Emotional adaptation (model-specific)	Proactivity and affective dialog
translation_config	TranslationConfig	Real-time speech-to-speech translation (translation models only)	Details
avatar_config	AvatarConfig	Render the agent as an animated avatar	Details

有关配置选项的更多详情，请参阅 Python API 参考中的 RunConfig。

导入路径：

上表中引用的所有配置类型类均从 google.genai.types 导入：

from google.genai import types
from google.adk.agents.run_config import RunConfig, StreamingMode

# 配置类型通过 types 模块访问
run_config = RunConfig(
    session_resumption=types.SessionResumptionConfig(),
    context_window_compression=types.ContextWindowCompressionConfig(...),
    speech_config=types.SpeechConfig(...),
    # etc.
)

RunConfig 类本身和 StreamingMode 枚举从 google.adk.agents.run_config 导入。

响应模式

response_modalities 设置控制输出格式，每个会话只能指定一种。对于实时智能体，值始终为 ["AUDIO"]，因为 ADK 支持的每个实时模型都不接受其他模态。 当你未设置时，ADK 会自动填充此值，因此大多数实时应用程序无需关心此字段。

从 response_modalities=["TEXT"] 迁移

旧版 ADK 示例和半级联模型曾允许纯文本实时会话。这已不再有效：使用 ["TEXT"] 的 run_live() 在当前实时模型上会失败，因为它们只产生音频。

要从实时智能体获取文本，请读取 event.output_transcription：转录在 ADK 中默认启用，因此删除 response_modalities 一行通常就足够了。

["TEXT"] 在 run_async() 路径上仍然正确，该路径运行在标准 Gemini 模型上。参见 双向流或 SSE。

响应模态只影响模型输出 — 你始终可以发送文本、语音或视频输入（如果模型支持该输入模态），不受此设置限制。

双向流或 SSE

ADK 可以通过两种不同的端点连接 Gemini，你调用的 Runner 方法决定了使用哪一种：

• runner.run_live()：ADK 通过 WebSocket 连接到实时 API（通过 live.connect() 的双向流端点）。本指南其余部分介绍的就是这种方式，实时音频和视频必须使用它
• runner.run_async()：ADK 通过 HTTP 连接到标准 Gemini API（通过 generate_content_async() 的一元/流端点）。设置 RunConfig.streaming_mode = StreamingMode.SSE 以逐块流式返回响应

两组模型几乎没有重叠。标准 Gemini 模型如 gemini-flash-latest 不支持双向连接，而支持的模型中的模型设计为通过 run_live() 驱动，因此选择模型就是选择 Runner 方法的一部分。

Python：StreamingMode.BIDI 不会将 ADK 切换到实时 API

在 Python 中，RunConfig.streaming_mode 仅在 run_async() 代码路径上被读取，用于在单次完整响应（StreamingMode.NONE，默认值）和分块响应（StreamingMode.SSE）之间选择。run_live() 路径从不读取此字段，因此设置 streaming_mode=StreamingMode.BIDI 不会生效且会静默失败。调用 run_live() 才是获得双向流的方式。 ADK 自身的 Python StreamingMode 文档字符串也有说明：BIDI "不在标准执行路径中使用"，真正的双向行为 "使用完全不同的代码路径，不依赖 streaming_mode"。

Java 不同。 ADK Java 的流程会读取 StreamingMode.BIDI，Java 快速入门在传给 runLive() 的 RunConfig 上明确设置了它。请遵循各语言的快速入门指南，而不是跨语言移植设置。

# 实时 API：无需 streaming_mode，调用 run_live() 才是选择它的方式
run_config = RunConfig(response_modalities=["AUDIO"])
async for event in runner.run_live(..., run_config=run_config):
    ...

这个选择只影响 ADK 与 Gemini 的通信方式。你的客户端架构是独立的：你可以在任一路径上构建 WebSocket 服务器、REST API 或 SSE 端点。

运行时配置 涵盖了 run_async() 和 SSE 路径：streaming_mode 的值、渐进式 SSE 流以及特定语言的配置。

杂项控制

ADK 提供了额外的 RunConfig 选项，用于控制会话行为、管理成本，以及持久化音频数据以供调试和合规目的。

run_config = RunConfig(
    # 限制每次调用的 LLM 调用总次数
    max_llm_calls=500,  # 默认值：500（防止无限循环）
                        # 0 或负数 = 无限制（谨慎使用）

    # 保存音视频制品以供调试/合规
    save_live_blob=True,  # 默认值：False

    # 为事件附加自定义元数据
    custom_metadata={"user_tier": "premium", "session_type": "support"},  # 默认值：None
)

max_llm_calls

max_llm_calls 限制每次调用上下文中的 LLM 调用次数，运行时配置 中有完整文档。

它不适用于 run_live()。 该参数仅保护 run_async() 路径，因此实时会话不会从中获得自动成本上限。你需要自行控制预算：限制会话时长、统计轮次、关注模型事件上的 usage_metadata（元数据），并在循环前设置熔断器。

save_live_blob

save_live_blob=True 将会话的音频持久化到会话服务（作为引用）和制品服务（作为文件）。尽管名称如此，目前只有音频会被持久化，不包括视频。

在调试语音行为或监管环境中的审计跟踪时启用它。否则请关闭：16 kHz PCM 输入约每分钟每会话 1.92 MB，写入两个服务，在语音工作负载下会快速累积。如果需要在生产中使用，请对部分会话采样而非全部，并在制品服务上设置保留策略 — ADK 不会自动过期。

save_live_audio 已弃用

ADK 会自动将 save_live_audio=True 迁移到 save_live_blob=True 并发出警告，但此兼容层将在未来版本中移除。请更新为 save_live_blob。

history_config

当 ADK 为已有对话历史的会话打开新的实时 API 连接时，它会将该历史回放给服务器。该历史包含模型自身的过往轮次，因此需要告知服务器不要再次回答。ADK 会自动处理：在连接前，只要有历史需要发送且没有会话恢复句柄在使用中，就会设置 live_connect_config.history_config.initial_history_in_client_content = True。

from google.genai import types

# ADK 会自动设置此项；仅在需要相反行为时才覆盖。
run_config = RunConfig(
    history_config=types.HistoryConfig(
        initial_history_in_client_content=True,
    ),
)

实际含义：

• 通常你不需要做任何事。 ADK 只在你未设置时才填充该值，因此在 RunConfig 上显式设置 history_config 始终优先。
• 重连时完全跳过历史。 当 ADK 使用会话恢复句柄重连时，服务器已持有该会话的状态，因此 ADK 不发送历史，也不会触碰 history_config。
• 出错时的症状：在播种历史时设置 initial_history_in_client_content=False 会使模型对回放的轮次做出响应，导致连接开始时出现大量重复回答。

custom_metadata

custom_metadata 为调用中的每个 Event 附加一个任意的可 JSON 序列化的字典，它在实时会话中的行为与其他场景相同 — 参见运行时配置。

run_config = RunConfig(
    response_modalities=["AUDIO"],
    custom_metadata={"user_tier": "premium", "session_type": "support"},
)

实时特定的影响在于作用域：一次 run_live() 调用就是一次调用，因此元数据会标记在整个流会话的每个事件上，而不是单个轮次。通过 event.custom_metadata 读取它。

不要在 custom_metadata 中放置敏感数据

携带此元数据的每个事件都会被持久化到会话服务。不要将 PII、凭据和其他敏感值放入其中，如果没有替代方案则应加密。

其他实时相关字段

RunConfig 还有一些仅在 run_live() 路径上生效的字段。ADK 将它们直接传递给实时连接，因此其确切行为由实时 API 而非 ADK 定义：

Field	Type	What it does
explicit_vad_signal	bool	请求模型发出显式语音活动信号。ADK 将其暴露在 event.voice_activity 上，而非从内容推断轮次边界
translation_config	types.TranslationConfig	启用实时语音到语音翻译。接受 target_language_code（BCP-47）和 echo_target_language。仅受翻译模型支持，如 gemini-3.5-live-translate-preview — 不受支持的模型中的模型支持
avatar_config	types.AvatarConfig	将智能体渲染为动画头像。接受 avatar_name（预构建头像）或 customized_avatar，以及 audio_bitrate_bps / video_bitrate_bps

from google.genai import types

run_config = RunConfig(
    response_modalities=["AUDIO"],
    explicit_vad_signal=True,
)

还有一个字段不是实时专用的，但在实时会话中经常有用：

• model_input_context（list[types.Content]）：为当前调用注入 LLM 请求的临时上下文。Runner 不会将其持久化到会话中，这使其成为提供每轮基础信息（用户刚打开的文档、正在查看的页面）的简洁方式，而不会污染对话历史。

组合函数调用 (support_cfc)

组合函数调用 (CFC) 是 run_async() / SSE 功能，不是实时功能：它理论上适用于当前实时模型，但没有任何模型满足其要求。将 support_cfc 留给 SSE 路径，在实时会话中使用标准函数调用（参见工具）。关于参数本身，请参见运行时配置。

音频转录

实时 API 会为你转录对话双方的内容，因此你可以显示字幕、记录对话和支持无障碍功能，而无需单独的语音转文本服务。转录在 ADK 中默认对输入（用户语音）和输出（模型语音）均启用。 将字段设置为 None 可关闭该方向的转录。

from google.genai import types
from google.adk.agents.run_config import RunConfig

# 默认开启。这等同于将两者都设置为 AudioTranscriptionConfig()。
run_config = RunConfig(response_modalities=["AUDIO"])

# 关闭用户输入转录，保留模型输出转录。
run_config = RunConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=None,
)

转录以 types.Transcription 对象的形式出现在 event.input_transcription 和 event.output_transcription 上，与 event.content 分开。它们以片段形式流式传入：.text 包含最新片段，.finished 标记该轮的最后一个片段。连接片段以构建完整的转录文本。

async for event in runner.run_live(...):
    if event.input_transcription and event.input_transcription.text:
        update_caption(
            event.input_transcription.text,
            is_user=True,
            is_final=event.input_transcription.finished,
        )
    if event.output_transcription and event.output_transcription.text:
        update_caption(
            event.output_transcription.text,
            is_user=False,
            is_final=event.output_transcription.finished,
        )

关于事件结构，请参见转录事件。

多智能体总会话始终转录

当根智能体有 sub_agents 时，run_live() 会启用输入和输出转录，即使你将它们设置为 None。智能体转移需要文本转录来将对话上下文传递给下一个智能体，因此无法禁用（runners.py）。

语音与语言

设置 speech_config 来选择模型的语音和语言。你可以在两个地方设置它：

• 在智能体上，通过传递带有 speech_config 的 Gemini 实例。用于为多智能体工作流中的每个智能体分配各自的语音。
• 在会话上，通过设置 RunConfig.speech_config。用于整个会话使用同一语音。

当两者都设置时，智能体级别的语音优先。两者都未设置时，实时 API 会选择默认语音。

from google.genai import types
from google.adk.agents import Agent
from google.adk.models.google_llm import Gemini
from google.adk.agents.run_config import RunConfig

# 智能体级别的语音（优先于 RunConfig）。
agent = Agent(
    model=Gemini(
        model="gemini-live-2.5-flash-native-audio",
        speech_config=types.SpeechConfig(
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Puck")
            ),
            language_code="en-US",
        ),
    ),
    instruction="You are a helpful assistant.",
)

# 会话级别的默认语音，供没有自定义语音的智能体使用。
run_config = RunConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        ),
    ),
)

voice_name 选择预构建语音。实时模型支持八种（Puck、Charon、Kore、Fenrir、Aoede、Leda、Orus、Zephyr），以及扩展的文本转语音语音列表。关于当前列表和各后端可用性，请参见 Gemini 实时 API 语音文档。不支持的语音会在连接时返回错误。

language_code（例如 en-US、ja-JP）设置语言和口音。实时模型通常会从对话中推断语言，可能会忽略此设置。

语音活动检测 (VAD)

VAD 检测用户何时开始和停止说话，使模型可以自然地轮换发言，包括处理中断。在所有实时模型上默认开启，大多数应用无需配置。

当你的应用自行决定轮次边界时，禁用自动 VAD：按住说话、客户端 VAD 或任何用户信号表示说完的 UX。禁用时，你必须通过 send_activity_start() / send_activity_end() 发送手动的 ActivityStart / ActivityEnd 信号，你的客户端必须将其自身的轮次信号转换为服务器上的这些调用。

from google.genai import types
from google.adk.agents.run_config import RunConfig

run_config = RunConfig(
    response_modalities=["AUDIO"],
    realtime_input_config=types.RealtimeInputConfig(
        automatic_activity_detection=types.AutomaticActivityDetection(disabled=True)
    ),
)

运行自身 VAD 的客户端将这些信号发送到你的服务器，服务器再通过 send_activity_start() / send_activity_end() 转发。参见连接客户端。

主动性和情感对话

部分实时模型提供两种对话功能，默认均关闭：

• 主动音频（proactivity）让模型自行决定何时响应、主动提供建议或忽略无关输入。
• 情感对话（enable_affective_dialog）让模型检测用户语气中的情感并调整响应。

from google.genai import types
from google.adk.agents.run_config import RunConfig

run_config = RunConfig(
    response_modalities=["AUDIO"],
    proactivity=types.ProactivityConfig(proactive_audio=True),
    enable_affective_dialog=True,
)

这两种行为都是概率性的，会使响应更不可预测，因此在正式或高精度场景以及调试时请保持关闭。

这两种设置取决于模型：Gemini 2.5 Flash Live 支持它们，Gemini 3.1 Flash Live 不支持，在迁移到 3.1 时保留这些设置是最常见的失败原因。参见 各模型功能支持。