运行时配置¶

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

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

类定义¶

RunConfig 类保存了智能体运行时行为的配置参数。

Python ADK 使用 Pydantic 进行类型校验。
Java ADK 通常使用不可变数据类。

PythonJava

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

public abstract class RunConfig {

  public enum StreamingMode {
    NONE,
    SSE,
    BIDI
  }

  public abstract @Nullable SpeechConfig speechConfig();

  public abstract ImmutableList<Modality> responseModalities();

  public abstract boolean saveInputBlobsAsArtifacts();

  public abstract @Nullable AudioTranscriptionConfig outputAudioTranscription();

  public abstract int maxLlmCalls();

  // ...
}

运行时参数¶

参数	Python 类型	Java 类型	默认值（Py / Java）	说明
`speech_config`	`Optional[types.SpeechConfig]`	`SpeechConfig` (nullable via `@Nullable`)	`None` / `null`	使用 `SpeechConfig` 类型配置语音合成（语音、语言）。
`response_modalities`	`Optional[list[str]]`	`ImmutableList<Modality>`	`None` / 空 `ImmutableList`	所需输出模态的列表（如 Python: `["TEXT", "AUDIO"]`；Java: 使用结构化 `Modality` 对象）。
`save_input_blobs_as_artifacts`	`bool`	`boolean`	`False` / `false`	若为 `true`，则将输入二进制大对象（如上传文件）保存为运行制品，便于调试/审计。
`streaming_mode`	`StreamingMode`	当前不支持	`StreamingMode.NONE` / N/A	设置流式行为：`NONE`（默认）、`SSE`（服务器发送事件）、`BIDI`（双向流式）。
`output_audio_transcription`	`Optional[types.AudioTranscriptionConfig]`	`AudioTranscriptionConfig` (nullable via `@Nullable`)	`None` / `null`	使用 `AudioTranscriptionConfig` 类型配置生成音频输出的转录。
`max_llm_calls`	`int`	`int`	`500` / `500`	限制每次运行的 LLM 调用总数。`0` 或负数表示无限制（有警告）；`sys.maxsize` 会抛出 `ValueError`。
`support_cfc`	`bool`	当前不支持	`False` / N/A	Python：启用组合函数调用。需 `streaming_mode=SSE` 且使用 LIVE API。实验性功能。

`speech_config`¶

Note

SpeechConfig 的接口或定义在不同语言中是相同的。

用于具有音频能力的实时智能体的语音配置。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 调用通常会产生成本并消耗资源，设置适当的限制至关重要。

验证规则¶

RunConfig 类会校验其参数以确保智能体正常运行。Python ADK 使用 Pydantic 自动类型校验，Java ADK 依赖静态类型并可能在 RunConfig 构造中包含显式检查。对于 max_llm_calls 参数：

极大值（如 Python 的 sys.maxsize 或 Java 的 Integer.MAX_VALUE）通常会被禁止以避免问题。
零或负值通常会触发关于无限 LLM 交互的警告。

示例¶

基本运行时配置¶

PythonJava

from google.genai.adk import RunConfig, StreamingMode

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

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;

RunConfig config = RunConfig.builder()
        .setStreamingMode(StreamingMode.NONE)
        .setMaxLlmCalls(100)
        .build();

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

启用流式处理¶

PythonJava

from google.genai.adk import RunConfig, StreamingMode

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

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;

RunConfig config = RunConfig.builder()
    .setStreamingMode(StreamingMode.SSE)
    .setMaxLlmCalls(200)
    .build();

使用 SSE 流式处理允许用户在生成响应时实时看到结果，为聊天机器人和助手带来更流畅的体验。

启用语音支持¶

PythonJava

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,
)

import com.google.adk.agents.RunConfig;
import com.google.adk.agents.RunConfig.StreamingMode;
import com.google.common.collect.ImmutableList;
import com.google.genai.types.Content;
import com.google.genai.types.Modality;
import com.google.genai.types.Part;
import com.google.genai.types.PrebuiltVoiceConfig;
import com.google.genai.types.SpeechConfig;
import com.google.genai.types.VoiceConfig;

RunConfig runConfig =
    RunConfig.builder()
        .setStreamingMode(StreamingMode.SSE)
        .setMaxLlmCalls(1000)
        .setSaveInputBlobsAsArtifacts(true)
        .setResponseModalities(ImmutableList.of(new Modality("AUDIO"), new Modality("TEXT")))
        .setSpeechConfig(
            SpeechConfig.builder()
                .voiceConfig(
                    VoiceConfig.builder()
                        .prebuiltVoiceConfig(
                            PrebuiltVoiceConfig.builder().voiceName("Kore").build())
                        .build())
                .languageCode("en-US")
                .build())
        .build();

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

使用 "Kore" 语音（美式英语）的语音能力
同时支持音频和文本输出模态
输入大对象制品保存（便于调试）
启用实验性 CFC 支持（仅限 Python）
SSE 流式处理，交互更流畅
LLM 调用上限为 1000 次

启用实验性 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¶

验证规则¶

示例¶

基本运行时配置¶

启用流式处理¶

启用语音支持¶

启用实验性 CFC 支持¶

`speech_config`¶

`response_modalities`¶

`save_input_blobs_as_artifacts`¶

`support_cfc`¶

`streaming_mode`¶

`output_audio_transcription`¶

`max_llm_calls`¶