Struct SessionConfig 

pub struct SessionConfig {

    pub endpoint: ApiEndpoint,
    pub model: Option<ModelId>,
    pub generation_config: GenerationConfig,
    pub system_instruction: Option<Content>,
    pub tools: Vec<Tool>,
    pub tool_config: Option<ToolConfig>,
    pub input_audio_transcription: Option<InputAudioTranscription>,
    pub output_audio_transcription: Option<OutputAudioTranscription>,
    pub realtime_input_config: Option<RealtimeInputConfig>,
    pub session_resumption: Option<SessionResumptionConfig>,
    pub context_window_compression: Option<ContextWindowCompressionConfig>,
    pub proactivity: Option<ProactivityConfig>,
    pub avatar_config: Option<AvatarConfig>,
    pub history_config: Option<HistoryConfig>,
    pub explicit_vad_signal: Option<bool>,
    pub input_audio_format: AudioFormat,
    pub audio_pacing: Option<BackpressureConfig>,
    pub wire_recorder: Option<WireRecorderHandle>,
}

Complete session configuration — the builder entrypoint.

Fields

endpoint: ApiEndpoint

API endpoint and credentials (Google AI key or Vertex AI project/token).

model: Option<ModelId>

Which Gemini model to use. The Live model. None means “the platform’s current default”, resolved at connect time by SessionConfig::resolved_model; set it only when a specific model is required.

generation_config: GenerationConfig

Generation parameters (modalities, temperature, etc.).

system_instruction: Option<Content>

System instruction content.

tools: Vec<Tool>

Tool declarations for function calling, search, etc.

tool_config: Option<ToolConfig>

Tool usage configuration.

input_audio_transcription: Option<InputAudioTranscription>

Input audio transcription configuration.

output_audio_transcription: Option<OutputAudioTranscription>

Output audio transcription configuration.

realtime_input_config: Option<RealtimeInputConfig>

Realtime input configuration (VAD, activity handling).

session_resumption: Option<SessionResumptionConfig>

Session resumption configuration.

context_window_compression: Option<ContextWindowCompressionConfig>

Context window compression configuration.

proactivity: Option<ProactivityConfig>

Proactivity configuration.

avatar_config: Option<AvatarConfig>

Live Avatar video output (Gemini 3.8 Live).

history_config: Option<HistoryConfig>

How clientContent history is treated (Gemini 3.8 Live).

explicit_vad_signal: Option<bool>

Ask the server to send voiceActivity events at speech boundaries (Vertex AI; stripped on Google AI, which does not accept it).

input_audio_format: AudioFormat

Encoding of the audio sent with send_audio (default: PCM16 at LIVE_INPUT_SAMPLE_RATE). The output format is not configurable: the API returns 24 kHz PCM16.

audio_pacing: Option<BackpressureConfig>

Optional send pacing for outbound audio (token-bucket backpressure).

None (default) sends audio as fast as the command queue accepts it. When set, SessionHandle::send_audio paces the producer: a caller pushing audio faster than refill_rate_bps waits, instead of overflowing the send queue.

wire_recorder: Option<WireRecorderHandle>

Optional wire recorder. When set, connect and ConnectBuilder wrap the codec in a RecordingCodec so every wire byte (both directions) is delivered to the recorder. See SessionConfig::record_wire.

Implementations

impl SessionConfig

pub fn to_setup_message(&self) -> SetupMessage

Build the setup message from this configuration.

Settings the target does not accept are left off the wire rather than failing the handshake; SessionConfig::ignored_settings lists exactly what this drops:

• behavior on function declarations, on Vertex AI models without async tool calling;
• thinkingConfig on Vertex AI and on models without thinking;
• enableAffectiveDialog and proactivity on models where both are always on (Gemini 3.8 Live);
• on Google AI, which has no such fields: proactivity, explicitVadSignal, sessionResumption.transparent, and avatarConfig.avatarName / customizedAvatar.

pub fn to_setup_json(&self) -> String

Pre-serialize the setup message to JSON. Called once at connection time.

impl SessionConfig

pub fn new(api_key: impl Into<String>) -> Self

Create a new session configuration with a Google AI API key.

This is the simplest way to get started. For Vertex AI, use SessionConfig::from_vertex or SessionConfig::from_endpoint.

pub fn from_access_token(access_token: impl Into<AccessToken>) -> Self

Create a session configuration with an OAuth2 access token.

Uses the Google AI endpoint (generativelanguage.googleapis.com) with an access token instead of an API key. This is the recommended approach when using gcloud auth print-access-token credentials.

let config = SessionConfig::from_access_token("ya29.ACCESS_TOKEN");

pub fn from_vertex( project: impl Into<String>, location: impl Into<String>, access_token: impl Into<AccessToken>, ) -> Self

Create a session configuration for Vertex AI.

Uses the regional Vertex AI endpoint ({location}-aiplatform.googleapis.com). For the global endpoint, consider using SessionConfig::from_access_token instead.

let config = SessionConfig::from_vertex(
    "my-project-123",
    "us-central1",
    "ya29.ACCESS_TOKEN",
);

pub fn from_endpoint(endpoint: ApiEndpoint) -> Self

Create a session configuration from an explicit ApiEndpoint.

pub fn model(self, model: impl Into<ModelId>) -> Self

Set the Gemini model.

pub fn resolved_model(&self) -> ModelId

The model this session will ask for: the configured one, else the platform default (see ModelId::live_default).

pub fn record_wire(self, recorder: Arc<dyn WireRecorder>) -> Self

Record every wire byte (both directions) to the given recorder.

Both connect paths (connect and ConnectBuilder) honor this by wrapping the codec in a RecordingCodec. Use FileWireRecorder for a durable JSONL log that can be replayed offline with ReplayTransport.

pub fn voice(self, voice: Voice) -> Self

Set the output voice.

pub fn replicated_voice(self, voice: ReplicatedVoiceConfig) -> Self

Speak in a voice replicated from a recorded sample instead of a prebuilt one (Gemini 3.8 Live on Vertex AI; allow-listed customers).

pub fn avatar(self, avatar: AvatarConfig) -> Self

Answer with Live Avatar video (Gemini 3.8 Live on Vertex AI).

Also sets responseModalities to ["VIDEO"], which the API requires for avatar output; the synchronized speech rides in the same stream. Chunks arrive as SessionEvent::Media.

Vertex AI only. Google AI’s avatar config has no avatarName or customizedAvatar (those are left off the wire there), and its gemini-3.8-live refuses the VIDEO modality.

pub fn initial_history_in_client_content(self, enabled: bool) -> Self

Accept conversation history sent with clientContent before the first turn (required by Gemini 3.8 Live to seed history). Send the turns after setupComplete, with turnComplete: true on the last.

pub fn explicit_vad_signal(self, enabled: bool) -> Self

Ask the server for explicit voiceActivity events at the start and end of user speech (Vertex AI only; stripped on Google AI).

pub fn system_instruction(self, instruction: impl Into<String>) -> Self

Set the system instruction.

pub fn response_modalities(self, modalities: Vec<Modality>) -> Self

Set response modalities.

pub fn text_only(self) -> Self

Configure for text-only mode (no audio output).

pub fn add_tool(self, tool: Tool) -> Self

Add a tool declaration.

pub fn with_url_context(self) -> Self

Enable URL context tool.

pub fn with_google_search(self) -> Self

Enable Google Search grounding.

pub fn with_code_execution(self) -> Self

Enable code execution.

pub fn tool_config(self, config: ToolConfig) -> Self

Set tool configuration.

pub fn input_transcription(self, enabled: bool) -> Self

Whether the server transcribes the user’s audio (SessionEvent::InputTranscription).

Enabling keeps settings already given through input_transcription_config.

pub fn output_transcription(self, enabled: bool) -> Self

Whether the server transcribes the model’s audio (SessionEvent::OutputTranscription).

Enabling keeps settings already given through output_transcription_config.

pub fn input_transcription_config( self, config: AudioTranscriptionConfig, ) -> Self

Transcribe the user’s audio with these settings — language hints, custom vocabulary.

pub fn output_transcription_config( self, config: AudioTranscriptionConfig, ) -> Self

Transcribe the model’s audio with these settings.

pub fn custom_vocabulary<S: Into<String>>( self, terms: impl IntoIterator<Item = S>, ) -> Self

Bias transcription of the user’s audio toward these terms — product names, SKUs, proper nouns (Gemini 3.8 Live). Enables input transcription, keeping any language hints already set.

pub fn temperature(self, temp: f32) -> Self

Set the temperature for generation.

pub fn automatic_activity_detection_enabled(&self) -> bool

Whether the server is detecting speech boundaries.

True unless the caller explicitly disabled automatic detection, because that is the API’s own default: omitting realtimeInputConfig entirely leaves server VAD on.

This gates explicit activityStart / activityEnd signalling. The two are mutually exclusive on the wire — sending an activity signal while automatic detection is on draws a close frame, code 1007, “Explicit activity control is not supported when automatic activity detection is enabled”, and the session dies mid-utterance.

pub fn server_vad(self, detection: AutomaticActivityDetection) -> Self

Configure server-side VAD.

pub fn activity_handling(self, handling: ActivityHandling) -> Self

Set how incoming audio interacts with model output (barge-in behavior).

pub fn turn_coverage(self, coverage: TurnCoverage) -> Self

Set which input counts toward a user’s conversation turn.

pub fn audio_pacing(self, config: BackpressureConfig) -> Self

Pace outbound audio with a token bucket (producer-side backpressure).

See SessionConfig::audio_pacing. Use BackpressureConfig::default for 16 kHz PCM16 rates with a ~250 ms burst allowance.

pub fn voice_realtime_defaults(self) -> Self

Apply recommended realtime input defaults for voice conversations.

This preserves any values the caller already set. In particular, it sets TURN_INCLUDES_ONLY_ACTIVITY so long pauses/silence in a continuous mic stream are not included in the user’s semantic turn.

pub fn session_resumption(self) -> Self

Enable session resumption: the server issues resumption handles (SessionEvent::SessionResumeUpdate) that a later session can pass to resume_from.

pub fn transparent_resumption(self) -> Self

Enable session resumption in transparent mode (Vertex AI only; left off the wire on Google AI): each resumption update also names the last client message the server consumed (ResumeInfo::last_consumed_index), so a client resuming from the handle knows which messages to send again.

pub fn resume_from(self, handle: impl Into<String>) -> Self

Resume an earlier session from a handle the server issued for it. Implies session_resumption.

pub fn context_window_compression(self, target_tokens: u32) -> Self

Configure context window compression for long sessions.

pub fn context_window_trigger_tokens(self, tokens: u32) -> Self

Set the token threshold that triggers context window compression.

pub fn proactive_audio(self, enabled: bool) -> Self

Enable proactive model responses.

Vertex AI only: Google AI’s setup has no proactivity field and refuses the session over it, so it is left off the wire there (and listed by ignored_settings).

pub fn thinking(self, budget: u32) -> Self

Enable thinking/reasoning with a token budget (Gemini 2.5+).

pub fn thinking_level(self, level: ThinkingLevel) -> Self

Set the thinking level, for models that take one instead of a budget. Gemini 3.8 Live Extended Thinking refuses a setup without it; plain Gemini 3.8 Live refuses one with it.

pub fn include_thoughts(self, enabled: bool) -> Self

Whether thought summaries are delivered (SessionEvent::Thought). Google AI only; see supports_thinking.

pub fn affective_dialog(self, enabled: bool) -> Self

Enable affective dialog (emotionally expressive responses).

pub fn media_resolution(self, res: MediaResolution) -> Self

Set the media resolution for image/video inputs.

pub fn seed(self, seed: u32) -> Self

Set the random seed for deterministic generation.

pub fn input_audio_format(self, format: AudioFormat) -> Self

Set the encoding of the audio sent with send_audio.

pub fn ws_url(&self) -> String

Build the WebSocket URL for connecting to the Gemini Live API.

• Google AI (key): wss://generativelanguage.googleapis.com/ws/...?key={key}
• Google AI (token): wss://generativelanguage.googleapis.com/ws/...?access_token={token}
• Vertex AI: wss://{location}-aiplatform.googleapis.com/ws/... or wss://aiplatform.googleapis.com/ws/... for global

pub fn model_uri(&self) -> String

Build the model URI used in the setup message.

• Google AI / Google AI Token: models/{model}
• Vertex AI: projects/{project}/locations/{location}/publishers/google/models/{model}

pub fn bearer_token(&self) -> Option<String>

The current bearer token when using Vertex AI, None for Google AI.

The transport calls this on every connection attempt to set the Authorization header for the WebSocket upgrade, so a refreshing AccessToken is honoured on reconnect. Google AI endpoints pass the credential as a query parameter instead.

pub fn is_vertex(&self) -> bool

Returns true if this config targets Vertex AI.

pub fn model_profile(&self) -> LiveModelProfile

What the configured model accepts in its setup; see LiveModelProfile.

pub fn supports_text_output(&self) -> bool

Whether the configured model can answer in text.

Native-audio Live models, which are every Live model today including Gemini 3.8 Live, close the session (1007, “The requested combination of response modalities (TEXT) is not supported”) when a setup asks for TEXT. A model this crate does not recognize is assumed to answer in text.

pub fn text_via_transcription(&self) -> bool

A text_only session on a model that can only speak. The setup then asks for audio and its output transcription, and the transcription is delivered as the session’s text (SessionEvent::TextDelta, TextComplete) with no audio, so a text session works on every model.

pub fn supports_async_tools(&self) -> bool

Returns true if the target accepts async tool calling fields: behavior on declarations and scheduling on responses.

Google AI does, and so does Gemini 3.8 Live on Vertex AI. Earlier Vertex AI Live models do not; there the fields are stripped from the wire so callers can set them unconditionally.

pub fn supports_thinking(&self) -> bool

Returns true if the target accepts thinkingConfig in the setup message. Vertex AI does not, and Gemini 3.8 Live does not support thinking on either platform: the config is stripped there, so thinking(..) and include_thoughts(..) are no-ops (listed by ignored_settings).

pub fn supports_system_role_updates(&self) -> bool

Whether a mid-session system-instruction update can go out as a system-role client content turn, as Vertex AI documents.

Google AI closes the session (1007, “Request contains an invalid argument”) on a system role — measured on Gemini 2.5, 3.1 and 3.8 Live — so there the update is sent as a user-role turn that says it replaces the instructions, with turnComplete: false. Gemini 3.x follows it; Gemini 2.5 accepts it without following it, so on 2.5 prefer context injection or a new session for a persona change.

pub fn ignored_settings(&self) -> Vec<&'static str>

Settings in this config that the target does not accept and that to_setup_message therefore leaves off the wire, by their wire names. Empty when everything configured is sent.

Connect logs these as a warning, so a setting that has no effect is visible rather than silent.

let config = SessionConfig::from_vertex("p", "us-central1", "t")
    .model(ModelId::LIVE_3_8)
    .affective_dialog(true)
    .thinking(512);
assert_eq!(config.ignored_settings(), ["thinkingConfig", "enableAffectiveDialog"]);

pub fn uses_access_token(&self) -> bool

Returns true if this config uses an access token (either GoogleAIToken or VertexAI).

Trait Implementations

impl Clone for SessionConfig

fn clone(&self) -> SessionConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.