Runtime Configuration

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

RunConfig controls how agents behave at runtime, including streaming mode, speech settings, LLM call limits, and live agent options. Pass a RunConfig to runner.run_async() or runner.run_live() to override default behavior.

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

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

Manage sessions and context

Supported in ADKPython

For long-running sessions, you can control how much history is loaded and whether the context window is compressed:

• get_session_config: Limits which events are fetched when loading a session. Use num_recent_events or after_timestamp to avoid loading the full event history on every invocation.
• context_window_compression: Enables context window compression for LLM input, useful when sessions approach model context limits.
• include_thoughts_from_other_agents: Controls whether thought parts from other agents are included in the LLM context. Disabled by default.
• model_input_context: A list of types.Content added to the LLM request for this invocation only. The runner does not persist it to the session, so you can supply per-turn context without changing the conversation history.

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

Enable streaming

To control how the agent delivers responses, set the streaming_mode parameter:

• StreamingMode.NONE (default): The runner returns one complete response per turn. Suitable for CLI tools, batch processing, and synchronous workflows.
• StreamingMode.SSE: Server-Sent Events streaming. The runner yields partial events as the LLM generates, enabling typewriter-style UIs and real-time chat displays.
• StreamingMode.BIDI: Reserved for bidirectional streaming, but not used in the standard run_async() path. For bidirectional streaming, use runner.run_live() instead.

Set support_cfc=True alongside StreamingMode.SSE to enable Compositional Function Calling (CFC), which allows the model to dynamically compose and execute function calls. CFC uses the Live API under the hood.

Experimental

CFC support is experimental and its API or behavior may change in future releases.

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

Configure audio and speech

Supported in ADKPythonTypeScriptJava

For voice-enabled agents, configure speech synthesis, audio transcription, and response modalities.

Live agents

This section covers the audio fields shared across languages. For the full live (run_live()) configuration reference — transcription streaming, voice selection, voice activity detection, and proactive/affective dialog — see Live agent configuration.

• speech_config: Sets the voice and language for speech output (e.g., the "Kore" voice with en-US).
• response_modalities: Controls the output format. A session accepts exactly one modality — use ["AUDIO"] for voice agents and ["TEXT"] for text-only ones. To get both speech and text, set ["AUDIO"] and read the text from the output audio transcription.
• output_audio_transcription / input_audio_transcription: Enable transcription of audio output from the model and audio input from the user. Both default to AudioTranscriptionConfig() in Python.

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

Configure live agents

Live (run_live()) sessions add a set of real-time parameters — realtime_input_config, session_resumption, save_live_blob, tool_thread_pool_config, proactivity, enable_affective_dialog, and more. These are documented in one place, with per-model support and examples, in the live docs:

• Live agent configuration — the full RunConfig reference for live agents.
• Sessions — session resumption and reconnection.
• Configuration: proactivity and affective dialog — native-audio conversational features and the models that support them.

tool_thread_pool_config is the exception: it is a runtime concern rather than a Live API one, so it stays here. It runs tool executions in a background thread pool so the event loop keeps responding to user interruptions.

Not all parameters are available in every language. See the API reference for language-specific details.

PythonTypeScript

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 pools help with blocking I/O and C extensions that release the GIL (e.g. time.sleep(), network calls, numpy). They do not help with pure Python CPU-bound code since the GIL prevents true parallel execution of Python bytecode.

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

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

Configure runtime limits and debugging

Use these parameters to control runtime guardrails and debugging:

• max_llm_calls: Caps the total number of LLM calls per run (default: 500). Set to 0 or negative for unlimited calls, though this is not recommended for production. Values at or above sys.maxsize raises an error.
• save_input_blobs_as_artifacts: When True, saves input blobs (e.g., uploaded files) as run artifacts for debugging and auditing. Deprecated in Python in favor of SaveFilesAsArtifactsPlugin.
• custom_metadata: A dict[str, Any] of arbitrary metadata attached to the invocation, useful for tracing or logging.

API reference

For the complete list of fields, types, and defaults, see the API reference for your language:

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