运行时配置¶

Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0

RunConfig 控制智能体在运行时的行为，包括流式模式、语音设置、 LLM 调用限制和实时智能体选项。将 RunConfig 传递给 runner.run_async() 或 runner.run_live() 以覆盖默认行为。

PythonTypeScriptGoJavaKotlin

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

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

async for event in runner.run_async(
    ...,
    run_config=config,
):
    ...

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

const config: RunConfig = {
  streamingMode: StreamingMode.SSE,
  maxLlmCalls: 200,
};

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

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

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

RunConfig config = RunConfig.builder()
    .streamingMode(StreamingMode.SSE)
    .maxLlmCalls(200)
    .build();

val config =
    RunConfig(
        streamingMode = StreamingMode.SSE,
        // Cap the LLM calls a single run may make. Defaults to 500.
        maxLlmCalls = 200,
    )

// Pass it to runner.runAsync
// runner.runAsync(..., runConfig = config)

管理会话和上下文¶

Supported in ADKPython

对于长时间运行的会话，你可以控制加载多少历史记录以及是否压缩上下文窗口：

get_session_config：限制加载会话时获取的事件。使用 num_recent_events 或 after_timestamp 避免在每次调用时加载完整的事件历史记录。
context_window_compression：为 LLM 输入启用上下文窗口压缩，当会话接近模型上下文限制时很有用。
include_thoughts_from_other_agents：控制是否将其他智能体的思考部分包含在 LLM 上下文中。默认禁用。
model_input_context：仅在本次调用中添加到 LLM 请求的 types.Content 列表。Runner 不会将其持久化到会话中，因此你可以在不更改对话历史的情况下提供每轮上下文。

Python

from google.adk.agents.run_config import RunConfig
from google.adk.sessions.base_session_service import GetSessionConfig

config = RunConfig(
    get_session_config=GetSessionConfig(num_recent_events=50),
)

文本响应选项¶

你可以控制智能体在文本模式下的响应方式——逐字生成还是作为完整响应返回，通过 流式模式 (Streaming Mode) 参数实现，具体说明如下：

StreamingMode.NONE（默认）：运行器每个轮次返回一个完整响应。适用于 CLI 工具、批处理和同步工作流。
StreamingMode.SSE：服务器推送事件（Server-Sent Events）流式传输。运行器在 LLM 生成过程中产出部分事件，支持打字机样式的 UI 和实时聊天展示。

还有另一个 流式模式 (Streaming Mode) 参数设置，支持双向数据流，包括语音输入和输出。此功能需要在简单智能体之外进行额外配置。有关此功能的更多信息，请参阅实时和语音智能体。

在 StreamingMode.SSE 旁边设置 support_cfc=True 以启用组合函数调用（CFC），这允许模型动态组合和执行函数调用。CFC 在底层使用 Live API。

实验性功能

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

PythonTypeScriptGoJavaKotlin

from google.adk.agents.run_config 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,
    maxLlmCalls: 150,
};

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

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

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

RunConfig config = RunConfig.builder()
    .streamingMode(StreamingMode.SSE)
    .maxLlmCalls(150)
    .build();

// Note: Kotlin currently has no supportCfc equivalent
val streamingConfig =
    RunConfig(
        streamingMode = StreamingMode.SSE,
        maxLlmCalls = 150,
    )

配置音频和语音¶

Supported in ADKPythonTypeScriptJava

对于支持语音的智能体，配置语音合成、音频转录和响应模态。

Live 智能体

本节涵盖跨语言共享的音频字段。有关完整的 Live（run_live()）配置参考——转录流式传输、语音选择、语音活动检测和主动/情感对话——请参阅 Live 智能体配置。

speech_config：设置语音输出的声音和语言（例如，使用 en-US 的 "Kore" 声音）。
response_modalities：控制输出格式。一个会话只接受一种模态——语音智能体使用 ["AUDIO"]，纯文本智能体使用 ["TEXT"]。要同时获取语音和文本，设置 ["AUDIO"] 并从输出音频转录中读取文本。
output_audio_transcription / input_audio_transcription：启用模型音频输出和用户音频输入的转录。两者在 Python 中默认为 AudioTranscriptionConfig()。

PythonTypeScriptJava

from google.adk.agents.run_config 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"],
    streaming_mode=StreamingMode.SSE,
    max_llm_calls=1000,
)

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

const config: RunConfig = {
    speechConfig: {
        languageCode: "en-US",
        voiceConfig: {
            prebuiltVoiceConfig: {
                voiceName: "Kore"
            }
        },
    },
    responseModalities: [Modality.AUDIO],
    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.Modality;
import com.google.genai.types.PrebuiltVoiceConfig;
import com.google.genai.types.SpeechConfig;
import com.google.genai.types.VoiceConfig;

RunConfig runConfig =
    RunConfig.builder()
        .streamingMode(StreamingMode.SSE)
        .maxLlmCalls(1000)
        .responseModalities(ImmutableList.of(new Modality(Modality.Known.AUDIO)))
        .speechConfig(
            SpeechConfig.builder()
                .voiceConfig(
                    VoiceConfig.builder()
                        .prebuiltVoiceConfig(
                            PrebuiltVoiceConfig.builder().voiceName("Kore").build())
                        .build())
                .languageCode("en-US")
                .build())
        .build();

配置 Live 智能体¶

Supported in ADKPythonTypeScriptJava

ADK 智能体支持实时和语音智能体，以创建交互式智能体体验。你可以使用 runner.run_live() 方法来配置支持此功能的智能体。实时智能体（run_live()）会话添加了一组实时参数，包括 realtime_input_config、session_resumption、save_live_blob、 tool_thread_pool_config、proactivity、enable_affective_dialog 等。更多信息请参阅实时智能体文档：

实时智能体配置：实时智能体的 RunConfig 参考。
会话：恢复和重连会话。
配置：主动性和情感对话：原生音频对话功能及支持它们的模型。

tool_thread_pool_config 设置是一个例外：它是运行时层面的配置而非 Live API 的功能，因此保留在本节。它在后台线程池中运行工具执行，以便事件循环能够持续响应用户中断。并非所有参数在每种语言中都可用。有关特定语言的详细信息，请参阅 API 参考。

PythonTypeScriptJava

from google.adk.agents.run_config import RunConfig, ToolThreadPoolConfig

config = RunConfig(
    save_live_blob=True,
    tool_thread_pool_config=ToolThreadPoolConfig(max_workers=8),
)

线程池和 GIL

线程池有助于处理阻塞 I/O 和释放 GIL 的 C 扩展（例如 time.sleep()、网络调用、numpy）。它们对纯 Python 的 CPU 密集型代码没有帮助，因为 GIL 阻止了 Python 字节码的真正并行执行。

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

const config: RunConfig = {
    enableAffectiveDialog: true,
    proactivity: {
        proactiveAudio: true,
    },
};

import com.google.adk.agents.RunConfig;
import com.google.genai.types.AvatarConfig;

RunConfig config = RunConfig.builder()
    .avatarConfig(
        AvatarConfig.builder()
            .avatarName("PREBUILT_AVATAR_ID")
            .build())
    .build();

配置运行时限制和调试¶

使用以下参数来控制运行时防护措施和调试：

max_llm_calls：限制每次运行的 LLM 调用总数（默认：500）。设置为 0 或负数表示不限制调用次数，但不建议在生产环境中使用。传入你所用语言的最大整数会引发错误：Python 中为 sys.maxsize，Kotlin 中为 Int.MAX_VALUE。
save_input_blobs_as_artifacts：当为 True 时，将输入 blob（例如上传的文件）保存为运行产物，用于调试和审计。在 Python 中已弃用，推荐使用 SaveFilesAsArtifactsPlugin。
custom_metadata：附加到调用的任意元数据 dict[str, Any]，用于跟踪或日志记录。

API 参考¶

有关完整的字段、类型和默认值列表，请参阅您所用语言的 API 参考：