运行时配置¶

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

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

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

管理会话和上下文¶

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

• get_session_config：限制加载会话时获取哪些事件。 使用 num_recent_events 或 after_timestamp 以避免每次调用时加载完整的事件历史记录。
• context_window_compression：为 LLM 输入启用上下文窗口压缩， 当会话接近模型上下文限制时非常有用。

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 和实时聊天显示。
• StreamingMode.BIDI：保留用于双向流式传输，但在标准 run_async() 路径中 未使用。对于双向流式传输，请改用 runner.run_live()。

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

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,
    supportCfc: true,
    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();

val streamingConfig =
    RunConfig(
        streamingMode = StreamingMode.SSE,
    )

配置音频和语音¶

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

• speech_config：设置语音输出的声音和语言（例如，使用 en-US 的 "Kore" 声音）。
• response_modalities：控制输出格式。设置为 ["AUDIO", "TEXT"] 以使 智能体既能说话又能返回文本。
• output_audio_transcription / input_audio_transcription：启用 模型音频输出和用户音频输入的转录。在 Python 中两者默认为 AudioTranscriptionConfig()。

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", "TEXT"],
    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, Modality.TEXT],
    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), new Modality(Modality.Known.TEXT)))
        .speechConfig(
            SpeechConfig.builder()
                .voiceConfig(
                    VoiceConfig.builder()
                        .prebuiltVoiceConfig(
                            PrebuiltVoiceConfig.builder().voiceName("Kore").build())
                        .build())
                .languageCode("en-US")
                .build())
        .build();

配置 Live 智能体¶

当使用 runner.run_live() 时，使用以下附加参数配置实时行为：

• realtime_input_config：配置如何从用户接收音频输入。
• proactivity：允许模型主动响应并忽略不相关的输入。
• enable_affective_dialog：设置为 True 时，模型检测用户情绪并相应调整其语气。
• avatar_config：为实时智能体配置头像。
• session_resumption：启用断开连接后的透明会话恢复。
• save_live_blob：设置为 True 时，将实时音频和视频数据保存到会话和工件服务。
• tool_thread_pool_config：在后台线程池中运行工具执行，以保持事件循环对用户中断的响应性。

并非所有参数在每种语言中都可用。请参阅 API 参考 以获取特定语言的详细信息。

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

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

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

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

配置运行时限制和调试¶

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

• max_llm_calls：限制每次运行的 LLM 调用总次数（默认：500）。 设置为 0 或负数表示无限制调用，但这不建议用于生产环境。 等于或高于 sys.maxsize 的值会引发错误。
• save_input_blobs_as_artifacts：设置为 True 时，将输入 blob（例如， 上传的文件）保存为运行工件，用于调试和审计。
• custom_metadata：附加到调用的任意元数据 dict[str, Any]， 用于跟踪或日志记录。

API 参考¶

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

• Python API reference
• TypeScript API reference
• Go API reference
• Java API reference
• Kotlin API reference