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-4o-realtime-preview-2024-12-17");

    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(&self, audio_base64: &str) -> Result<(), RealtimeError>

Send audio to the session.

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

Send text to the session.

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 next_event(&self) -> Option<Result<ServerEvent, RealtimeError>>

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

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 run(&self) -> Result<(), RealtimeError>

Run the event loop, processing events until disconnected.

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

Close the session.