运行时配置¶

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

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

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

类定义¶

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

Python ADK 使用 Pydantic 进行此验证。
Go ADK 默认具有可变结构。
Java ADK 通常使用不可变数据类。
TypeScript ADK 使用标准接口，类型安全由 TypeScript 编译器提供。

PythonTypeScriptGoJava

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

export interface RunConfig {
  speechConfig?: SpeechConfig;
  responseModalities?: Modality[];
  saveInputBlobsAsArtifacts: boolean;
  supportCfc: boolean;
  streamingMode: StreamingMode;
  outputAudioTranscription?: AudioTranscriptionConfig;
  maxLlmCalls: number;
  // ... and other properties
}

export enum StreamingMode {
  NONE = 'none',
  SSE = 'sse',
  BIDI = 'bidi',
}

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

  // ...
}

运行时参数¶

参数	Python 类型	TypeScript 类型	Go 类型	Java 类型	默认值 (Py / TS / Go / Java)	描述
`speech_config`	`Optional[types.SpeechConfig]`	`SpeechConfig` (可选)	N/A	`SpeechConfig` (通过 `@Nullable` 可空)	`None` / `undefined`/ N/A / `null`	使用 `SpeechConfig` 类型配置语音合成（语音、语言）。
`response_modalities`	`Optional[list[str]]`	`Modality[]` (可选)	N/A	`ImmutableList<Modality>`	`None` / `undefined` / N/A / Empty `ImmutableList`	所需输出模态列表（例如，Python: `["TEXT", "AUDIO"]`; Java/TS: 使用结构化 `Modality` 对象）。
`save_input_blobs_as_artifacts`	`bool`	`boolean`	`bool`	`boolean`	`False` / `false` / `false` / `false`	如果为 `true`，将输入 blob（例如，上传的文件）保存为运行制品以供调试/审计。
`streaming_mode`	`StreamingMode`	`StreamingMode`	`StreamingMode`	`StreamingMode`	`StreamingMode.NONE` / `StreamingMode.NONE` / `agent.StreamingModeNone` / `StreamingMode.NONE`	设置流式行为：`NONE`（默认），`SSE`（服务器发送事件），或 `BIDI`（双向）。
`output_audio_transcription`	`Optional[types.AudioTranscriptionConfig]`	`AudioTranscriptionConfig` (可选)	N/A	`AudioTranscriptionConfig` (通过 `@Nullable` 可空)	`None` / `undefined` / N/A / `null`	使用 `AudioTranscriptionConfig` 类型配置生成的音频输出的转录。
`max_llm_calls`	`int`	`number`	N/A	`int`	`500` / `500` / N/A / `500`	限制每次运行的总 LLM 调用次数。`0` 或负数表示无限制。超出语言限制（例如 `sys.maxsize`、`Number.MAX_SAFE_INTEGER`）会引发错误。
`support_cfc`	`bool`	`boolean`	N/A	`bool`	`False` / `false` / N/A / `false`	Python/TypeScript：启用组合函数调用。需要 `streaming_mode=SSE` 并使用 LIVE API。实验性。

`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 调用通常会产生成本并消耗资源，设置适当的限制至关重要。

验证规则¶

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

RunConfig 类验证其参数以确保智能体操作正确。虽然 Python ADK 使用 Pydantic 进行自动类型验证，Java 和 TypeScript ADK 依赖其静态类型系统，并可能在 RunConfig 的构造函数中包含显式检查。对于 max_llm_calls 参数：

通常不允许极大的值（如 Python 中的 sys.maxsize、Java 中的 Integer.MAX_VALUE 或 TypeScript 中的 Number.MAX_SAFE_INTEGER），以防止出现问题。

示例¶

基本运行时配置¶

PythonTypeScriptGoJava

from google.genai.adk import RunConfig, StreamingMode

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

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
  streamingMode: StreamingMode.NONE,
  maxLlmCalls: 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();

此配置创建一个非流式智能体，限制为 100 次 LLM 调用，适用于简单的面向任务的智能体，在这种情况下完整的响应是首选。

启用流式处理¶

PythonTypeScriptGoJava

from google.genai.adk import RunConfig, StreamingMode

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

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
  streamingMode: StreamingMode.SSE,
  maxLlmCalls: 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();

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

启用语音支持¶

PythonTypeScriptJava

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 { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
    speechConfig: {
        languageCode: "en-US",
        voiceConfig: {
            prebuiltVoiceConfig: {
                voiceName: "Kore"
            }
        },
    },
    responseModalities: [
      { modality: "AUDIO" },
      { modality: "TEXT" }
    ],
    saveInputBlobsAsArtifacts: true,
    supportCfc: true,
    streamingMode: StreamingMode.SSE,
    maxLlmCalls: 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" 语音的语音功能（美式英语）
音频和文本输出模态
输入 blob 的制品保存（用于调试）
实验性 CFC 支持已启用 (Python 和 TypeScript)
用于响应式交互的 SSE 流式处理
1000 次 LLM 调用限制

启用 CFC 支持¶

Supported in ADKPython v0.1.0Typescript v0.2.0Experimental

PythonTypeScript

from google.genai.adk import RunConfig, StreamingMode

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

import { RunConfig, StreamingMode } from '@google/adk';

const config: RunConfig = {
    streamingMode: StreamingMode.SSE,
    supportCfc: true,
    maxLlmCalls: 150,
};

启用组合函数调用 (CFC) 会创建一个能够根据模型输出动态执行函数的智能体，对于需要复杂工作流的应用程序非常强大。

实验性发布

组合函数调用 (CFC) 流式功能是实验性发布。

运行时配置¶

类定义¶

运行时参数¶

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