Provedores em tempo real

ADK-Rust oferece dois backends em tempo real por trás da mesma interface RealtimeModel, para que uma aplicação possa oferecer ambos e alternar por sessão. Esta página aborda os modelos, as vozes, os endpoints, a autenticação e como escolher.

OpenAI em tempo real (GA)

use adk_realtime::openai::OpenAIRealtimeModel;
use adk_realtime::model::BoxedModel;
use std::sync::Arc;

let model: BoxedModel = Arc::new(OpenAIRealtimeModel::new(
    std::env::var("OPENAI_API_KEY")?,
    "gpt-realtime-2.1",
));

• Transporte: WebSocket (recurso openai) ou WebRTC (openai-webrtc, requer cmake).
• Áudio: PCM16 de 24 kHz na entrada e na saída.
• Vozes: marin (uma voz GA natural), alloy e outras; definidas com RealtimeConfig::with_voice("marin").
• Autenticação: OPENAI_API_KEY. A chave fica no seu servidor (nunca no navegador).

Gemini Live

use adk_realtime::gemini::{GeminiLiveBackend, GeminiRealtimeModel};

let model: BoxedModel = Arc::new(GeminiRealtimeModel::new(
    GeminiLiveBackend::studio(std::env::var("GEMINI_API_KEY")?),
    "models/gemini-3.1-flash-live-preview",
));

• Transporte: WebSocket (recurso gemini, AI Studio) ou Vertex AI Live (vertex-live, OAuth2 / ADC — consulte Agentes em tempo real).
• Áudio: PCM16 de 16 kHz entrada, PCM16 de 24 kHz saída.
• Vozes: Kore e outras; with_voice("Kore").
• Autenticação: GEMINI_API_KEY (ou GOOGLE_API_KEY).

Os nomes dos modelos variam de acordo com o endpoint. O AI Studio (chave API) usa nomes como models/gemini-3.1-flash-live-preview; o Vertex/Agent Platform usa nomes diferentes. O crate GeminiLiveBackend::studio(...) tem como destino o AI Studio por meio do endpoint v1alpha (que também é o usado pelo diálogo afetivo).

Escolhendo um modelo

• Voz geral + ferramentas → gpt-realtime-2.1 ou gemini-3.1-flash-live-preview. Ambos chamam ferramentas de forma confiável. Gemini é mais adequado para vídeo contínuo.
• Voz mais natural / consciente das emoções → áudio nativo do Gemini (gemini-live-2.5-flash-native-audio) com diálogo afetivo — com alguma redução na confiabilidade das chamadas de ferramentas.
• Foco intenso em raciocínio → gpt-realtime-2.1.
• Tradução → os modelos dedicados de tradução (com protocolo próprio).

Selecionando um provedor por sessão

Os aplicativos normalmente leem o provedor de uma solicitação e criam o modelo correspondente. As taxas de áudio são diferentes, portanto, exponha-as também:

#[derive(Clone, Copy)]
enum Provider { OpenAI, Gemini }

impl Provider {
    fn audio_rates(self) -> (u32, u32) {   // (input, output)
        match self {
            Provider::OpenAI => (24_000, 24_000),
            Provider::Gemini => (16_000, 24_000),
        }
    }
}

fn build_model(p: Provider) -> anyhow::Result<(BoxedModel, &'static str)> {
    Ok(match p {
        Provider::OpenAI => (
            Arc::new(OpenAIRealtimeModel::new(std::env::var("OPENAI_API_KEY")?, "gpt-realtime-2.1")),
            "marin",
        ),
        Provider::Gemini => (
            Arc::new(GeminiRealtimeModel::new(
                GeminiLiveBackend::studio(std::env::var("GEMINI_API_KEY")?),
                "models/gemini-3.1-flash-live-preview",
            )),
            "Kore",
        ),
    })
}

Os exemplos permitem substituir todos esses valores por variáveis de ambiente (OPENAI_REALTIME_MODEL, GEMINI_REALTIME_MODEL), para que você possa fixar um modelo sem recompilar.

Matriz de recursos

Próximo: Ferramentas →

Diagnósticos e privacidade de payloads

Os frames em tempo real contêm transcrições, argumentos de ferramentas, resultados de ferramentas e identificadores. Quando um evento reconhecido não pode ser desserializado — divergência no esquema do provedor — o aviso relata um resumo seguro quanto aos campos e omite o frame:

Nota: o resumo agrupa as linhas de log dentro de uma execução. Ele não é um resumo criptográfico e não é estável entre processos.

Para diagnosticar a divergência com o frame em mãos, compile adk-realtime com o recurso record-payloads, que registra os primeiros 300 bytes:

[dependencies]
adk-realtime = { version = "2.1.0", features = ["openai", "record-payloads"] }

O recurso fica desativado por padrão e essa é uma escolha deliberada por build, porque a divergência de esquema é exatamente o momento em que os operadores ampliam a coleta e a retenção de logs.