使用智能体配置构建智能体¶

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

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

PythonTypeScriptGoJava

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

管理会话和上下文¶

Supported in ADKPython

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

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

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

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

实验性

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

PythonTypeScriptGoJava

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

配置音频和语音¶

Supported in ADKPythonTypeScriptJava

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

speech_config：设置语音输出的语音和语言（例如使用 en-US 的 "Kore" 语音）。
response_modalities：控制输出格式。对于既说话又返回文本的智能体，设置为 ["AUDIO", "TEXT"]。
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", "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();

配置实时智能体¶

Supported in ADKPythonTypeScript

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

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

并非所有参数在每个语言中都可用。请参阅 API 参考了解语言特定详情。

PythonTypeScript

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,
    },
};

配置运行时限制和调试¶

使用这些参数控制运行时护栏和调试：

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

API 参考¶

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