运行时配置¶

RunConfig 定义了 ADK 中智能体的运行时行为和选项。它控制语音和流式设置、函数调用、制品保存，以及对 LLM 调用的限制。

在构建智能体运行时，你可以传递 RunConfig 来自定义智能体如何与模型交互、处理音频和流式响应。默认情况下，不启用流式处理，输入也不会作为制品保留。使用 RunConfig 可以覆盖这些默认设置。

类定义¶

RunConfig 类是一个 Pydantic 模型，强制对配置参数进行严格验证。

class RunConfig(BaseModel):
    """智能体运行时行为的配置。"""

    model_config = ConfigDict(
        extra='forbid',
    )

    speech_config: Optional[types.SpeechConfig] = None
    response_modalities: Optional[list[str]] = None
    save_input_blobs_as_artifacts: bool = False
    support_cfc: bool = False
    streaming_mode: StreamingMode = StreamingMode.NONE
    output_audio_transcription: Optional[types.AudioTranscriptionConfig] = None
    max_llm_calls: int = 500

运行时参数¶

参数	类型	默认值	描述
`speech_config`	`Optional[types.SpeechConfig]`	`None`	通过嵌套的 `types.SpeechConfig` 配置语音合成（声音、语言）。
`response_modalities`	`Optional[list[str]]`	`None`	期望的输出模态列表（例如，`["TEXT", "AUDIO"]`）。默认为 `None`。
`save_input_blobs_as_artifacts`	`bool`	`False`	如果为 `True`，则将输入二进制大对象（例如，上传的文件）保存为运行制品，用于调试/审计。
`support_cfc`	`bool`	`False`	启用组合函数调用。需要 `streaming_mode=SSE` 并使用 LIVE API。实验性功能。
`streaming_mode`	`StreamingMode`	`StreamingMode.NONE`	设置流式行为：`NONE`（默认），`SSE`（服务器发送事件）或 `BIDI`（双向）。
`output_audio_transcription`	`Optional[types.AudioTranscriptionConfig]`	`None`	通过 `types.AudioTranscriptionConfig` 配置生成的音频输出转录。
`max_llm_calls`	`int`	`500`	限制每次运行的 LLM 调用总数。`0` 或负数表示无限制（会发出警告）；`sys.maxsize` 引发 `ValueError`。

`speech_config`¶

具有音频功能的实时智能体的语音配置设置。SpeechConfig 类具有以下结构：

class SpeechConfig(_common.BaseModel):
    """语音生成配置。"""

    voice_config: Optional[VoiceConfig] = Field(
        default=None,
        description="""要使用的说话者配置。""",
    )
    language_code: Optional[str] = Field(
        default=None,
        description="""用于语音合成的语言代码（ISO 639，例如 en-US）。
        仅适用于 Live API。""",
    )

voice_config 参数使用 VoiceConfig 类：

class VoiceConfig(_common.BaseModel):
    """要使用的声音配置。"""

    prebuilt_voice_config: Optional[PrebuiltVoiceConfig] = Field(
        default=None,
        description="""要使用的说话者配置。""",
    )

而 PrebuiltVoiceConfig 有以下结构：

class PrebuiltVoiceConfig(_common.BaseModel):
    """要使用的预构建说话者的配置。"""

    voice_name: Optional[str] = Field(
        default=None,
        description="""要使用的预构建声音的名称。""",
    )

这些嵌套的配置类允许你指定：

voice_config：要使用的预构建声音的名称（在 PrebuiltVoiceConfig 中）
language_code：用于语音合成的 ISO 639 语言代码（例如，"en-US"）

在实现支持语音的智能体时，配置这些参数来控制你的智能体在说话时的声音。

`response_modalities`¶

定义智能体的输出模态。如果未设置，默认为 AUDIO。响应模态决定了智能体如何通过各种渠道（例如，文本、音频）与用户交流。

`save_input_blobs_as_artifacts`¶

启用后，输入二进制大对象将在智能体执行期间被保存为制品。这对于调试和审计目的很有用，允许开发者查看智能体接收到的确切数据。

`support_cfc`¶

启用组合函数调用（CFC）支持。仅适用于使用 StreamingMode.SSE 时。启用后，将调用 LIVE API，因为只有它支持 CFC 功能。

Warning

support_cfc 功能是实验性的，其 API 或行为可能在未来版本中发生变化。

`streaming_mode`¶

配置智能体的流式行为。可能的值：

StreamingMode.NONE：无流式处理；响应作为完整单元交付
StreamingMode.SSE：服务器发送事件流式处理；从服务器到客户端的单向流式处理
StreamingMode.BIDI：双向流式处理；两个方向的同时通信

流式模式影响性能和用户体验。SSE 流式处理让用户可以在生成响应时就看到部分响应，而 BIDI 流式处理则能实现实时交互体验。

`output_audio_transcription`¶

配置具有音频响应能力的实时智能体的音频输出转录。这使得音频响应能够自动转录，用于无障碍访问、记录保存和多模态应用。

`max_llm_calls`¶

设置给定智能体运行的 LLM 调用总数限制。

大于 0 且小于 sys.maxsize 的值：对 LLM 调用实施限制
小于或等于 0 的值：允许无限制的 LLM 调用（不推荐用于生产环境）

此参数防止过度 API 使用和潜在的失控进程。由于 LLM 调用通常会产生成本并消耗资源，设置适当的限制至关重要。

验证规则¶

作为 Pydantic 模型，RunConfig 自动验证参数类型。此外，它还包含针对 max_llm_calls 参数的特定验证逻辑：

如果设置为 sys.maxsize，将引发 ValueError 以防止整数溢出问题
如果小于或等于 0，将记录关于潜在无限 LLM 调用的警告

示例¶

基本运行时配置¶

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.NONE,
    max_llm_calls=100
)

此配置创建了一个非流式智能体，LLM 调用限制为 100 次，适用于偏好完整响应的简单任务导向智能体。

启用流式处理¶

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.SSE,
    max_llm_calls=200
)

使用 SSE 流式处理允许用户在生成响应时即可看到，为聊天机器人和助手提供更具响应性的感觉。

启用语音支持¶

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

config = RunConfig(
    speech_config=types.SpeechConfig(
        language_code="en-US",
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(
                voice_name="Kore"
            )
        ),
    ),
    response_modalities=["AUDIO", "TEXT"],
    save_input_blobs_as_artifacts=True,
    support_cfc=True,
    streaming_mode=StreamingMode.SSE,
    max_llm_calls=1000,
)

这个综合示例配置了一个智能体，具有：

使用"Kore"声音（美式英语）的语音能力
音频和文本两种输出模态
为输入二进制大对象保存制品（对调试有用）
启用实验性 CFC 支持
SSE 流式处理以实现响应式交互
1000 次 LLM 调用的限制

启用实验性 CFC 支持¶

from google.genai.adk import RunConfig, StreamingMode

config = RunConfig(
    streaming_mode=StreamingMode.SSE,
    support_cfc=True,
    max_llm_calls=150
)

启用组合函数调用创建了一个可以基于模型输出动态执行函数的智能体，这对需要复杂工作流的应用非常强大。

运行时配置¶

类定义¶

运行时参数¶

speech_config¶

response_modalities¶

save_input_blobs_as_artifacts¶

support_cfc¶

streaming_mode¶

output_audio_transcription¶

max_llm_calls¶