运行时配置¶

Supported in ADKPython v0.1.0Go v0.1.0Java v0.1.0

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

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

类定义¶

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

Python ADK uses Pydantic for this validation.
Go ADK has mutable structs by default.
Java ADK typically uses immutable data classes.

PythonGoJava

class RunConfig(BaseModel):
    """Configs for runtime behavior of agents."""

    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

type StreamingMode string

const (
    StreamingModeNone StreamingMode = "none"
    StreamingModeSSE  StreamingMode = "sse"
)

// RunConfig controls runtime behavior.
type RunConfig struct {
    // Streaming mode, None or StreamingMode.SSE.
    StreamingMode StreamingMode
    // Whether or not to save the input blobs as artifacts
    SaveInputBlobsAsArtifacts bool
}

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();

  // ...
}

Runtime Parameters¶

Parameter	Python Type	Go Type	Java Type	Default (Py / Go / Java )	Description
`speech_config`	`Optional[types.SpeechConfig]`	N/A	`SpeechConfig` (nullable via `@Nullable`)	`None` / N/A / `null`	Configures speech synthesis (voice, language) using the `SpeechConfig` type.
`response_modalities`	`Optional[list[str]]`	N/A	`ImmutableList<Modality>`	`None` / N/A / Empty `ImmutableList`	List of desired output modalities (e.g., Python: `["TEXT", "AUDIO"]`; Java: uses structured `Modality` objects).
`save_input_blobs_as_artifacts`	`bool`	`bool`	`boolean`	`False` / `false` / `false`	If `true`, saves input blobs (e.g., uploaded files) as run artifacts for debugging/auditing.
`streaming_mode`	`StreamingMode`	`StreamingMode`	`StreamingMode`	`StreamingMode.NONE` / `agent.StreamingModeNone` / `StreamingMode.NONE`	Sets the streaming behavior: `NONE` (default), `SSE` (server-sent events), or `BIDI` (bidirectional) (Python/Java).
`output_audio_transcription`	`Optional[types.AudioTranscriptionConfig]`	N/A	`AudioTranscriptionConfig` (nullable via `@Nullable`)	`None` / N/A / `null`	Configures transcription of generated audio output using the `AudioTranscriptionConfig` type.
`max_llm_calls`	`int`	N/A	`int`	`500` / N/A / `500`	Limits total LLM calls per run. `0` or negative means unlimited (warned); `sys.maxsize` raises `ValueError`.
`support_cfc`	`bool`	N/A	`bool`	`False` / N/A / `false`	Python: Enables Compositional Function Calling. Requires `streaming_mode=SSE` and uses the LIVE API. Experimental.

`speech_config`¶

Supported in ADKPython v0.1.0Java v0.1.0

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`¶

Supported in ADKPython v0.1.0Java v0.1.0

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

`save_input_blobs_as_artifacts`¶

Supported in ADKPython v0.1.0Go v0.1.0Java v0.1.0

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

`support_cfc`¶

Supported in ADKPython v0.1.0Experimental

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

Experimental release

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

`streaming_mode`¶

Supported in ADKPython v0.1.0Go v0.1.0

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

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

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

`output_audio_transcription`¶

Supported in ADKPython v0.1.0Java v0.1.0

配置具有音频响应能力的实时智能体的音频输出转录。这为可访问性、记录和多模态应用程序启用了音频响应的自动转录。

`max_llm_calls`¶

Supported in ADKPython v0.1.0Java v0.1.0

设置给定智能体运行的总 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 交互的警告。

示例¶

基本运行时配置¶

PythonGoJava

from google.genai.adk import RunConfig, StreamingMode

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

import "google.golang.org/adk/agent"

config := agent.RunConfig{
    StreamingMode: agent.StreamingModeNone,
}

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

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

This configuration creates a non-streaming agent with a limit of 100 LLM calls, suitable for simple task-oriented agents where complete responses are preferable.

启用流式处理¶

PythonGoJava

from google.genai.adk import RunConfig, StreamingMode

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

import "google.golang.org/adk/agent"

config := agent.RunConfig{
    StreamingMode: agent.StreamingModeSSE,
}

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

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

Using SSE streaming allows users to see responses as they're generated, providing a more responsive feel for chatbots and assistants.

启用语音支持¶

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();

This comprehensive example configures an agent with:

使用 "Kore" 语音（美式英语）的语音能力
音频和文本输出模态
输入 blob 的制品保存（用于调试）
用于响应式交互的 SSE 流式处理
1000 次 LLM 调用限制

启用实验性 CFC 支持¶

Supported in ADKPython v0.1.0Experimental

```python
    from google.genai.adk import RunConfig, StreamingMode

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

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

运行时配置¶

类定义¶

Runtime Parameters¶

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`¶