ランタイム設定 (Runtime Configuration)¶

ADKでサポートPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0

RunConfig は、streaming mode、speech setting、LLM call limit、live agent option など、エージェントのランタイム動作を制御します。デフォルト動作を上書きするには、 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)

セッションとコンテキストの管理¶

ADKでサポートPython

Long-running session では、どれだけの history を load するか、context window を圧縮するかを制御できます。

get_session_config: session を load するときに取得する event を制限します。 invocation ごとに event history 全体を load しないよう、num_recent_events または after_timestamp を使います。これらのフィルターは保存されたイベントを削除することなく、読み込まれるビューのみを制限します。新しいイベントは保存された履歴に追加され、読み込まれたビューから除外された過去のイベントもそのまま保持されます。
context_window_compression: LLM input の context window compression を有効にします。 session が model context limit に近づく場合に便利です。
model_input_context: 今回の呼び出しにのみ LLM リクエストに追加される types.Content のリスト。ランナーはこれをセッションに永続化しないため、会話履歴を変更せずにターンごとのコンテキストを提供できます。
include_thoughts_from_other_agents: 他のエージェントの思考（thought）パートを 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),
)

テキスト応答オプション¶

エージェントがテキストモードで応答する方法を、生成されるにつれて単語ごとに配信するか、または 1 つの完全な応答として配信するかを、以下で説明する Streaming Mode パラメータで制御できます:

StreamingMode.NONE (デフォルト): runner は turn ごとに 1 つの完全なレスポンスを返します。CLI tool、batch processing、synchronous workflow に適しています。
StreamingMode.SSE: Server-Sent Events streaming です。LLM が生成している間、runner が partial event を yield し、typewriter-style UI や real-time chat display を実現できます。

音声の入力と出力を含むデータの双方向ストリーミングを可能にする Streaming Mode パラメータのもう 1 つの設定があります。この機能には、シンプルなエージェントを超える追加の設定が必要です。詳細については、ライブおよび音声エージェントを参照してください。

StreamingMode.SSE とともに support_cfc=True を設定すると、Compositional Function Calling(CFC) を有効にできます。CFC により、model は function call を動的に構成して実行でき、内部では Live API を使用します。

Experimental

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

音声と発話の設定¶

ADKでサポートPythonTypeScriptJava

Voice-enabled agent では、speech synthesis、audio transcription、response modality を設定します。

ライブエージェント

このセクションでは、言語共通のオーディオフィールドを扱います。文字起こしストリーミング、音声選択、音声活動検出（VAD）、プロアクティブ/感情的対話など、完全なライブ（run_live()）構成リファレンスについては、ライブエージェントの設定を参照してください。

speech_config: 音声出力の音声と言語を設定します（例: en-US と "Kore" 音声）。
response_modalities: 出力形式を制御します。セッションは厳密に1つのモダリティのみを受け入れるため、音声エージェントには ["AUDIO"] を、テキストのみのエージェントには ["TEXT"] を使用します。音声とテキストの両方を取得するには、["AUDIO"] に設定し、出力音声の文字起こし（transcription）からテキストを読み取ります。
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();

ライブエージェントの設定¶

ADK でサポートPythonTypeScriptJava

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 reference を参照してください。

PythonTypeScriptJava

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

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

Thread pool and the GIL

Thread pool は blocking I/O と、GIL を release する C extension(例: time.sleep()、network call、numpy)に役立ちます。純粋な Python CPU-bound code には役立ちません。GIL が Python bytecode の真の並列実行を妨げるためです。

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

ランタイム制限とデバッグの設定¶

次のパラメータで runtime guardrail と debugging を制御します。

max_llm_calls: run ごとの LLM call 合計数を制限します(デフォルト: 500)。0 または負の値は無制限の呼び出しを意味しますが、本番環境では推奨されません。使用する言語の最大整数(Python では sys.maxsize、Kotlin では Int.MAX_VALUE)を渡すとエラーになります。
save_input_blobs_as_artifacts: True の場合、input blob(例: uploaded file)を debugging と auditing 用の run artifact として保存します。
custom_metadata: invocation に添付される任意 metadata の dict[str, Any] です。tracing や logging に便利です。

API reference¶

field、type、default の完全な一覧は、各言語の API reference を参照してください。