Struct LiveHandle 

pub struct LiveHandle { /* private fields */ }

Handle for interacting with a running Live session.

Provides send methods for audio/text/video, system instruction updates, event subscription, state access, telemetry, and graceful shutdown.

When ContextDelivery::Deferred is enabled, send_audio, send_text, and send_video automatically flush any pending context turns before forwarding the user content.

Implementations

impl LiveHandle

pub async fn send_audio( &self, data: impl Into<Bytes>, ) -> Result<(), SessionError>

Send audio data (raw PCM16 16kHz bytes).

Configured input processors (see configure_input_audio) run over the frame first; the backend input VAD then sees the processed stream, and under client activity authority its speech edges are forwarded to the server as activityStart/activityEnd. When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the audio frame.

pub fn set_turn_commit(&self, config: TurnCommitConfig)

Install a turn-commit policy between the input VAD’s speech edges and the activity marks sent under client activity authority.

Raw edges make two measured mistakes as turn signals (TurnBench dev set): committing end-of-turn during mid-turn pauses, and treating backchannels (“mm-hm”) over model speech as barge-ins. The policy’s end-hold and interruption-sustain rules suppress both — see TurnCommitConfig for the measured operating points. Without a policy, edges forward to the wire unchanged.

pub fn configure_input_audio( &self, processors: Vec<Box<dyn InputAudioProcessor>>, vad: Option<VadConfig>, authority: ActivityAuthority, )

Configure the input audio path: mic-chain processors applied inside send_audio, an optional replacement input-VAD configuration, and the interruption authority. Call once after connect, before streaming audio; a mid-stream call resets the VAD’s adaptive state.

pub async fn send_text( &self, text: impl Into<String>, ) -> Result<(), SessionError>

Send a text message.

When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the text message.

The text is also recorded on the session transcript as the user side of the current turn, through the same internal control event that ASR of audio produces. Without this a text-driven session would hand every TurnExtractor an empty user turn, since the transcript’s user side is otherwise written only by ASR. Routing through the control event rather than poking the buffer keeps a typed turn and a spoken one the same event downstream.

pub async fn send_video( &self, jpeg_data: impl Into<Bytes>, ) -> Result<(), SessionError>

Send a video/image frame (raw JPEG bytes).

When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the video frame.

pub async fn update_instruction( &self, instruction: impl Into<String>, ) -> Result<(), SessionError>

Update the system instruction mid-session.

pub async fn send_tool_response( &self, responses: Vec<FunctionResponse>, ) -> Result<(), SessionError>

Send tool responses manually (if not using auto-dispatch).

pub async fn playback_drained(&self) -> Result<(), SessionError>

Notify the runtime that client-side playback has drained.

Voice UIs should call this only when it is safe for the model to speak, for example after browser speaker playback has drained and the user is not actively speaking. User audio/text sends intentionally flush context only and leave the prompt armed.

pub async fn user_speech_started(&self) -> Result<(), SessionError>

Notify the runtime that client-side user speech has started.

This is the barge-in edge for voice clients: pending model prompts are cancelled before they can race with user audio, while queued context is kept so the next user send can still carry it.

pub async fn user_speech_ended(&self) -> Result<(), SessionError>

Notify the runtime that client-side user speech has ended.

pub fn voice_state(&self) -> VoiceRuntimeState

Snapshot the reactor-owned voice runtime state.

pub fn input_vad_state(&self) -> BackendVadSnapshot

Snapshot backend input VAD state.

pub async fn flush_deferred_prompt(&self) -> Result<(), SessionError>

Flush deferred context and any pending model prompt.

Prefer Self::playback_drained for voice clients. This compatibility method routes through the same reactor/effect executor path.

pub fn writer(&self) -> Arc<dyn SessionWriter>

Get the user-facing session writer.

When deferred context delivery is enabled, this returns the DeferredWriter that flushes pending context before sends.

pub fn subscribe(&self) -> Receiver<SessionEvent>

Subscribe to raw session events (for custom processing).

pub fn phase(&self) -> SessionPhase

Get the current session phase.

pub async fn disconnect(&self) -> Result<(), SessionError>

Gracefully disconnect the session.

Shutdown sequence:

1. Cancel all in-flight background tool tasks (they are aborted at an await point; tool futures must therefore be drop-safe).
2. Close the L0 session. The terminal Disconnected event makes the event router exit, which closes the lane channels.
3. Grace-await the fast and control lanes (~250 ms each) so they can drain queued events and run their final persistence drain, then abort whatever is still stuck (e.g. a lane blocked in a slow tool).
4. Cancel the telemetry lane.

pub async fn done(&self) -> Result<(), SessionError>

Wait for the session to end (disconnect, GoAway, or error).

pub fn session(&self) -> &SessionHandle

Get the underlying SessionHandle for advanced usage.

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

Latest session-resumption handle issued by the server, if any.

While session resumption is enabled (SessionConfig::session_resumption; L2: Live::builder().session_resume(true)), the Gemini server periodically sends SessionResumptionUpdate messages; this returns the most recent handle (also captured in persistence snapshots as SessionSnapshot::resume_handle).

To survive a server-initiated GoAway or a planned restart, read this handle (e.g. from the on_go_away callback) and pass it to resume_from(handle) on the next connect’s SessionConfig. No automatic reconnect is performed — resumption is an explicit caller decision.

Returns None when resumption is disabled or no update has arrived yet.

pub fn state(&self) -> &State

Access the shared State container.

Extraction results from TurnExtractors are stored here under the extractor’s name. Use state().get::<T>(name) to read typed values.

pub fn telemetry(&self) -> &Arc<SessionTelemetry>

Access the session telemetry (auto-collected by the telemetry lane).

Use telemetry().snapshot() to get a JSON snapshot of all metrics.

pub fn events(&self) -> Receiver<LiveEvent>

Subscribe to semantic events from the processor.

Returns a broadcast receiver. Call multiple times for independent subscribers. Zero-cost when no subscribers exist.

pub fn stream(&self) -> LiveEventStream

Subscribe to semantic events as a [futures_util::Stream].

Stream-flavored sibling of events: each call creates an independent subscriber starting from the current point in the event flow. If the subscriber falls behind the broadcast buffer, the missed events are skipped and the stream continues; the stream ends when the session’s event channel closes. See LiveEventStream.

Example

use futures_util::StreamExt;

let mut stream = handle.stream();
while let Some(ev) = stream.next().await {
    match ev {
        LiveEvent::TextDelta(t) => print!("{t}"),
        LiveEvent::TurnComplete => println!(),
        _ => {}
    }
}

pub fn extracted<T>(&self, name: &str) -> Option<T>

where T: DeserializeOwned,

Convenience: get the latest extraction result by extractor name.

pub fn explain(&self) -> Option<FlowExplanation>

Snapshot the governed flow’s control-plane state: active steps, which tools are admitted vs blocked (with reasons), and unmet requirements.

The deterministic answer to “why did the assistant ask that?” — computed against the live State and the marking the control lane maintains. Returns None when the session is not governed by a flow (Live::govern/observe was not used).

This is a synchronous snapshot: it briefly locks the shared FlowMonitor and never blocks on session I/O.

pub fn update_step_posture( &self, step_id: &str, posture: Option<String>, ) -> bool

Replace a governed step’s posture mid-session. Returns true when the session is governed and the step exists.

Postures are re-projected at every turn boundary, so the edit steers the very next turn. This is the safe subset of live spec editing: the DAG, guards, and tool gates stay fixed (tool declarations cannot change mid-session at the wire level anyway).

pub fn update_step_ground(&self, step_id: &str, ground: Option<String>) -> bool

Replace a governed step’s grounding template mid-session. Same semantics as update_step_posture.

Trait Implementations

impl Clone for LiveHandle

fn clone(&self) -> LiveHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Talk for LiveHandle

async fn talk(&self) -> Result<(), VoiceIoError>

See the trait docs. The five-line voice app: