Struct RealtimeRunner 

pub struct RealtimeRunner { /* private fields */ }

Available on crate feature realtime only.

A runner that manages a realtime session with tool execution.

RealtimeRunner provides a high-level interface for:

• Connecting to realtime providers
• Automatically executing tool calls
• Routing events to handlers
• Managing the session lifecycle

Example

use adk_realtime::{RealtimeRunner, RealtimeConfig, ToolDefinition};
use adk_realtime::openai::OpenAIRealtimeModel;

#[tokio::main]
async fn main() -> Result<()> {
    let model = OpenAIRealtimeModel::new(api_key, "gpt-realtime");

    let runner = RealtimeRunner::builder()
        .model(Box::new(model))
        .instruction("You are a helpful voice assistant.")
        .voice("alloy")
        .tool_fn(
            ToolDefinition::new("get_weather")
                .with_description("Get weather for a location"),
            |call| {
                Ok(serde_json::json!({"temperature": 72, "condition": "sunny"}))
            }
        )
        .build()?;

    runner.connect().await?;
    runner.run().await?;

    Ok(())
}

Implementations

impl RealtimeRunner

pub fn builder() -> RealtimeRunnerBuilder

Create a new builder.

pub async fn connect(&self) -> Result<(), RealtimeError>

Connect to the realtime provider.

pub async fn is_connected(&self) -> bool

Check if currently connected.

pub async fn session_id(&self) -> Option<String>

Get the session ID if connected.

pub async fn send_client_event( &self, event: ClientEvent, ) -> Result<(), RealtimeError>

Send a client event directly to the session.

This method intercepts internal control-plane events (like UpdateSession) to route them through the provider-agnostic orchestration layer instead of forwarding raw JSON to the underlying WebSocket transport. This guarantees that adk-realtime never leaks invalid event payloads to providers (e.g., OpenAI or Gemini) and universally bridges the Cognitive Handoff mechanics transparently.

pub async fn update_session( &self, config: SessionUpdateConfig, ) -> Result<(), RealtimeError>

Update the session configuration.

Delegates to Self::update_session_with_bridge with no bridge message.

Example

use adk_realtime::config::{SessionUpdateConfig, RealtimeConfig};

async fn example(runner: &adk_realtime::RealtimeRunner) {
    let update = SessionUpdateConfig(
        RealtimeConfig::default().with_instruction("You are now a pirate.")
    );
    runner.update_session(update).await.unwrap();
}

pub async fn update_session_with_bridge( &self, config: SessionUpdateConfig, bridge_message: Option<String>, ) -> Result<(), RealtimeError>

Update the session configuration, optionally injecting a bridge message if a transport resumption (Phantom Reconnect) occurs.

The RealtimeRunner will attempt to mutate the session natively if the underlying API supports it (e.g., OpenAI). If it does not (e.g., Gemini), the Runner will queue a transport resumption, executing it only when the session is in a resumable state (Idle) to prevent data corruption.

The runner keeps only one pending resumption. If a new session update arrives while a resumption is already pending, the previous pending resumption is replaced. This is intentional: pending session updates represent desired end state, not an ordered command queue. The policy is last write wins.

pub async fn send_audio_chunk( &self, audio: &AudioChunk, ) -> Result<(), RealtimeError>

Send a typed raw-audio chunk to the session.

This preserves the audio format at the provider boundary and lets the provider choose its native encoding path. Prefer this method when the caller already owns raw audio bytes.

pub async fn send_audio(&self, audio_base64: &str) -> Result<(), RealtimeError>

Send base64-encoded audio to the session.

This compatibility entry point is useful when the caller already has a base64 payload. Raw-audio callers should use send_audio_chunk to avoid forcing an encoding decision at the provider-neutral runner boundary.

pub async fn send_text(&self, text: &str) -> Result<(), RealtimeError>

Send text to the session.

pub async fn send_video_frame( &self, mime_type: &str, data_base64: &str, ) -> Result<(), RealtimeError>

Send a base64-encoded video/image frame (e.g. image/jpeg) for multimodal input, where the provider supports it (Gemini Live; OpenAI as an image-in-context item).

pub async fn commit_audio(&self) -> Result<(), RealtimeError>

Commit the audio buffer (for manual VAD mode).

pub async fn create_response(&self) -> Result<(), RealtimeError>

Trigger a response from the model.

pub async fn interrupt(&self) -> Result<(), RealtimeError>

Interrupt the current response.

pub async fn disconnect_reason(&self) -> Option<DisconnectReason>

Get the next raw event from the session.

Example

use adk_realtime::events::ServerEvent;
use tracing::{info, error};

async fn process_events(runner: &adk_realtime::RealtimeRunner) {
    while let Some(event) = runner.next_event().await {
        match event {
            Ok(ServerEvent::SpeechStarted { .. }) => info!("User is speaking"),
            Ok(_) => info!("Received other event"),
            Err(e) => error!("Error: {e}"),
        }
    }
}

Why the provider ended the stream, once Self::next_event has returned None.

Callers that poll next_event never see the runner’s on_disconnect dispatch, so without this a provider that deliberately closed an idle session is indistinguishable from a dropped socket — and both get recorded as the same generic stream failure.

pub async fn next_event(&self) -> Option<Result<ServerEvent, RealtimeError>>

pub async fn send_tool_response( &self, response: ToolResponse, ) -> Result<(), RealtimeError>

Send a tool response to the session.

Example

use adk_realtime::events::ToolResponse;
use serde_json::json;

async fn example(runner: &adk_realtime::RealtimeRunner) {
    let response = ToolResponse {
        call_id: "call_123".to_string(),
        output: json!({"temperature": 72}),
    };
    runner.send_tool_response(response).await.unwrap();
}

pub async fn dispatch_tool_call( &self, call_id: &str, name: &str, arguments: &str, ) -> Result<(), RealtimeError>

Execute a tool call against the registered handlers, sending the result back to the model when auto_respond_tools is enabled.

This is the same dispatch the run loop performs for a response.function_call_arguments.done event, exposed so that callers driving the session manually via next_event — such as IntegratedRealtimeRunner (available with the integration feature) — can execute tools without re-implementing the lookup/respond logic.

pub async fn send_tool_result( &self, call_id: &str, output: Value, ) -> Result<(), RealtimeError>

Sends a tool result the caller produced, honouring auto_respond_tools.

Used by the integration layer, which runs ADK tools through its own policy pipeline and then needs the result delivered exactly as execute_tool_call would deliver it: the output is sent now, and the single follow-up create_response is deferred until the dispatching response closes, so several parallel calls produce one response.

Example

let result = my_policy_pipeline.run(&call).await?;
runner.send_tool_result(&call.call_id, result).await?;

pub async fn run(&self) -> Result<(), RealtimeError>

Run the event loop, processing events until disconnected.

pub async fn instruction(&self) -> Option<String>

The system instruction the next connection will use.

Exposed so callers and tests can confirm what context a session was actually created with, rather than inferring it from log lines.

pub async fn prepend_instruction_context(&self, block: &str)

Prepends a context block to the system instruction before connecting.

The integration layer uses this to carry prior conversation history and recalled memory into the provider session. Call it before RealtimeRunner::connect: providers read the instruction at session creation, so a later change needs update_session.

Example

runner.prepend_instruction_context("Previously discussed: the refund policy.").await;
runner.connect().await?;

pub async fn respond_after_tools(&self) -> Result<(), RealtimeError>

Trigger the single follow-up response owed after a tool-dispatching turn.

Call this when a response finishes (ResponseDone). If tool output(s) were sent back during that response (auto_respond_tools), the model now needs one create_response to speak its answer — issued here, after the dispatch response is closed and every parallel tool output is in, rather than once per tool call. Gemini’s create_response is a no-op, so this is safely uniform across providers. No-op when nothing is pending.

pub async fn close(&self) -> Result<(), RealtimeError>

Close the session.