Primeiros passos com a Gemini Live API

Se você já tentou criar um assistente de voz, sabe como o fluxo tradicional é engessado. Você grava a voz do usuário, transcreve com um modelo de STT, envia o texto para um LLM, espera a resposta e depois passa tudo por um mecanismo de TTS. 

Quando a resposta chega ao ouvido do usuário, já se passaram vários segundos de silêncio constrangedor. Em vez de uma conversa, vira um ciclo lento de pedido e resposta. 

A Gemini Live API muda esse jogo ao permitir o streaming contínuo de áudio e vídeo por uma conexão WebSocket com estado. Como o modelo processa e gera áudio de forma nativa, ele reage na hora, se adapta às nuances naturais da fala e ainda lida com interrupções (barge-in) no meio da frase. 

Neste tutorial, vou mostrar como construir um Real-Time AI Travel Concierge usando o Google Agent Development Kit (ADK), com foco em código. Vamos equipar nosso agente com Google Search para consultar clima em tempo real no destino, conectá-lo a um banco de voos fictício e subir uma interface local de desenvolvimento para testar diálogo em tempo real e chamadas de ferramentas.

Se você é novo no ecossistema, recomendo começar pelo curso Building AI Agents with Google ADK para consolidar os fundamentos.

O que você vai conquistar: 

• Entender o funcionamento interno, as capacidades e a precificação da Gemini Live API.
• Configurar um ambiente Python com o Google Agent Development Kit. 
• Expor ferramentas nativas (Google Search) e lógica de negócio personalizada (consulta a banco de status de voos) para o assistente de voz. 
• Lançar uma interface web local para conversar ao vivo com seu agente de viagens.

Pré-requisitos: 

• Familiaridade básica com Python. 
• Um projeto no Google Cloud (para acesso ao Vertex AI) ou uma API key do Google AI Studio.

O que é a Gemini Live API? 

Em essência, a Gemini Live API é uma ferramenta para desenvolvedores do Google que permite criar interações em tempo real de voz e visão com modelos Gemini. Em vez de esperar por respostas de texto por turnos, ela viabiliza uma conversa contínua e natural entre o usuário e um agente de IA. 

Tecnicamente, a Gemini Live API foi projetada para streaming bidirecional em tempo real. Diferente das APIs REST HTTP padrão, que usam ciclos sem estado de requisição e resposta, a Live API depende de uma conexão WebSocket (WSS) persistente e com estado. Por esse canal aberto, o cliente transmite áudio bruto, vídeo (enviado como frames de imagem a ~1 FPS) e texto, enquanto o modelo devolve áudio e texto nativos de forma imediata.

Principais capacidades da Gemini Live

• Barge-in (interrupção): Em uma conversa humana natural, não esperamos a outra pessoa terminar um parágrafo inteiro para pedir um esclarecimento. A Gemini Live oferece barge-in nativamente: o usuário pode interromper a fala do modelo no meio da frase, o servidor para o streaming de áudio na hora e se adapta ao novo input.
• Diálogo afetivo e áudio nativo: Em vez de gerar texto e passar por um mecanismo de Text-to-Speech (TTS), modelos como gemini-live-2.5-flash-native-audio e gemini-3.1-flash-live-preview processam e geram áudio de forma nativa. Isso preserva nuances emocionais, risos, adaptação de tom e ritmo de fala, deixando a interação mais humana. 
• Entradas multimodais e uso de ferramentas: A Live API não se limita a áudio. Ela pode “ver” seu ambiente via frames de vídeo e acionar funções ou ferramentas externas (como Google Search ou APIs personalizadas) em tempo real, incorporando os resultados no fluxo de voz.

Preços da Gemini Live API

Como o streaming em tempo real envolve uma conexão contínua e full-duplex, o modelo de cobrança é diferente de APIs estáticas de texto. O Google oferece um nível gratuito generoso para prototipagem no Google AI Studio e um nível pago pronto para produção no Vertex AI. 

O modelo gemini-3.1-flash-live-preview é cobrado por milhão de tokens ou convertido 

diretamente em métrica baseada em duração para mídia de áudio e vídeo:

Se você está prototipando, recomendo fortemente testar de graça no Google AI Studio, que oferece acesso generoso sujeito a limites de taxa. 

Quando estiver pronto para escalar, migre seu projeto para o Vertex AI com provisionamento Pay-as-you-go para produção, garantindo throughput e SLAs de nível corporativo.

Como acessar a Gemini Live API

Como desenvolvedor, você tem algumas escolhas de arquitetura ao implementar a Live API. Como ela depende de WebSockets, a forma de roteamento impacta latência e segurança.

Cliente para servidor vs. servidor para servidor

• Cliente para servidor: Seu frontend (por exemplo, um app web ou mobile) conecta diretamente ao endpoint WebSocket do Google. É a melhor abordagem para minimizar latência, pois o áudio não dá saltos extras. 
• Porém, você não pode expor suas chaves brutas de API do Google Cloud no frontend; é preciso implementar um fluxo de autenticação que gere tokens temporários e efêmeros para acesso seguro do cliente.
• Servidor para servidor: Seu frontend transmite áudio para seu próprio backend, que então abre o WebSocket para a Gemini Live API. É altamente seguro e permite injetar lógica de backend (como autenticação de usuário ou consultas a banco), mas adiciona um pequeno atraso de rede ao stream de áudio.

SDKs e integrações com parceiros

Embora você possa escrever código de WebSocket do zero, a forma mais fácil de começar é usando o GenAI SDK do Google ou o Agent Development Kit (ADK). 

Para produção corporativa, o ecossistema evoluiu rapidamente para suportar integrações WebRTC. Plataformas como LiveKit, Pipecat by Daily, Twilio e Voximplant oferecem infraestrutura robusta para lidar com jitter de rede, cancelamento de eco e roteamento de áudio em tempo real direto para a Gemini Live API.

Construindo um assistente de voz em tempo real com a Gemini Live API

Vamos colocar em prática. Vamos construir um AI Travel Concierge. 

Esse agente vai usar a Gemini Live API para conversar por voz com os usuários e, o mais importante, terá acesso a funções Python personalizadas para consultar status de voos em tempo real durante a conversa.

Usaremos o Google Agent Development Kit (ADK) e o poderoso modelo gemini-3.1-flash-live-preview, otimizado tanto para turnos de texto quanto para streaming bidirecional via WebSocket.

1. Configurando o ambiente

Primeiro, crie um ambiente virtual em Python e instale o pacote ADK necessário. Rode estes comandos no terminal:

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install the Agent Development Kit
pip install google-adkTecnologia

Em seguida, configure as variáveis de ambiente para o ADK autenticar com segurança no seu projeto do Google Cloud:

export GOOGLE_CLOUD_PROJECT="your-project-id" 
export GOOGLE_CLOUD_LOCATION="us-central1"Tecnologia

Se você estiver usando uma Gemini API Key do Google AI Studio, crie um arquivo .env na pasta raiz:

GEMINI_API_KEY=your_google_ai_studio_api_keyTecnologia

2. Inicializando o agente Gemini Live 

Crie um arquivo chamado agent.py no diretório do projeto. O ADK foi projetado para detectar e executar automaticamente a variável root_agent. No código, vamos definir uma função Python personalizada para verificar status de voos e passá-la diretamente para o cinto de ferramentas do agente. Inicialize o diretório do agente: 

mkdir voice_assistant 
touch voice_assistant/__init__.py 
touch voice_assistant/agent.pyTecnologia

Exponha o pacote do agente em voice_assistant/__init__.py:

from . import agentTecnologia

3. Definindo o agente e expondo ferramentas personalizadas 

Abra voice_assistant/agent.py e escreva a configuração do agente de viagens. No código abaixo, definimos uma função Python padrão, check_flight_status. 

No Google ADK, qualquer função Python com type hints adequados e uma docstring é automaticamente convertida em uma ferramenta do agente. O LLM usa a descrição e os parâmetros da docstring para decidir quando e como chamar a função. 

Configuração do modelo 

Aproveitando o Gemini 3.1 Flash Live Preview: para suportar ambos os modos de interação no servidor de desenvolvimento do ADK — chat de texto padrão (que usa endpoints REST generateContent) e a interface de microfone WebSocket bidirecional em tempo real — definimos explicitamente o modelo como gemini-3.1-flash-live-preview.

Diferente de modelos antigos apenas de streaming, que retornam 404 Not Found quando acionados por requisições REST HTTP padrão, o gemini-3.1-flash-live-preview suporta nativamente geração de conteúdo via REST e streaming com WebSocket com estado.

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
def check_flight_status(flight_no: str) -> str:
   """Check the real-time flight status (e.g. delays, gate info, cancellations).
   Args:
       flight_no: The flight number to look up (e.g., AA120, DL450, UA990).
   """
   flight_no = flight_no.upper().strip()
   if "AA120" in flight_no:
       return "Flight AA120 to Paris is currently delayed by 45 minutes due to air traffic control. New departure time: 3:15 PM. Gate status: B22."
   elif "DL450" in flight_no:
       return "Flight DL450 to London is on time. Gate status: Boarding now at Gate C10."
   elif "UA990" in flight_no:
       return "Flight UA990 to Tokyo is cancelled due to adverse weather conditions at the destination. Passengers are advised to rebook at the counter."
   else:
       return f"Flight {flight_no} is currently scheduled on time. No delay reports found in the flight database."
# Define the root agent with search grounding and custom database flight checks
root_agent = Agent(
   model='gemini-3.1-flash-live-preview',
   name='root_agent',
   description='A real-time AI Travel Concierge with flight tracking and search grounding.',
   instruction=(
       'You are an expert AI Travel Concierge. You assist users with real-time flight status checkups, '
       'destination recommendations, and general travel planning. '
       'Always answer professionally and conversationally. '
       'Use the check_flight_status tool when a user asks about a specific flight status. '
       'Use Google Search to look up weather, transit conditions, or travel advisories at destinations.'
   ),
   tools=[google_search, check_flight_status],
)Tecnologia

4. Executando e testando a interface interativa de desenvolvimento

O ADK inclui um servidor de desenvolvimento e uma Web UI integrados. Isso permite testar seu agente localmente sem escrever código de frontend. Inicie o servidor web a partir do seu workspace:

.venv/bin/adk web .Tecnologia

Você deve ver uma saída indicando que o servidor foi iniciado:

1. Abra http://127.0.0.1:8000 no seu navegador.
2. Selecione seu agente na lista de aplicações.
3. Clique no botão de microfone para iniciar uma sessão ao vivo.

Selecione root_agent na lista de aplicações para abrir a interface de chat.

4. Fale no microfone: Você pode verificar o status do voo AA120? O agente vai interpretar seu pedido, reconhecer que precisa de informações do banco, acionar a função Python personalizada check_flight_status e exibir o resultado da chamada de ferramenta em JSON antes de falar a resposta para você.

5. Testando o grounding com Google Search:  Depois, faça uma pergunta de clima no destino: Como está o clima em Londres agora? O agente vai ativar a ferramenta nativa google_search, rastrear a web e sintetizar as condições atuais na resposta em áudio.

6. Testando o recurso de barge-in: Faça uma pergunta ampla como: Conte sobre os melhores sítios históricos para visitar em Roma. Quando o agente começar a listar os lugares, fale por cima em voz alta: Pera, espera! Verifique o voo UA990 em vez disso!. O agente vai parar imediatamente o stream de fala, interromper os detalhes sobre Roma, executar a ferramenta personalizada de rastreamento de voos e informar que o voo UA990 foi cancelado. Isso demonstra a natureza de baixa latência e full-duplex da conexão da Live API.

Boas práticas para produção com a Gemini Live API

Criar aplicações de voz em tempo real traz requisitos específicos de arquitetura de prompts, gestão de estado de rede, ingestão de áudio e escalabilidade. Abaixo estão boas práticas essenciais derivadas das diretrizes oficiais para desenvolvedores.

1. Projetando instruções de sistema claras

Para extrair o melhor desempenho da Gemini Live, estruture suas system instructions (SIs) em uma hierarquia rígida: persona, regras de conversa e guardrails.

• Separe personas: Mantenha o papel de cada agente restrito a uma única instrução de sistema, em vez de sobrecarregar um agente com várias personas.
• Delimite fluxos de conversa: Separe explicitamente elementos de uma só vez (por exemplo, "peça o nome e o número do bilhete do usuário uma única vez") de laços conversacionais abertos (por exemplo, "responda dúvidas sobre recomendações de viagem pelo tempo que quiserem").
• Escreva invocações de ferramentas em frases: Descreva o uso das ferramentas de forma sequencial. Por exemplo: 'Primeiro, peça ao usuário o número do bilhete. Depois, invoque look_up_ticket com esse número.'
• Garanta consistência de idioma: Modelos de áudio nativo podem alternar de idioma se o contexto mudar. Se seu agente for somente em inglês, imponha isso na instrução: RESPONDA EM English. VOCÊ DEVE RESPONDER INEQUIVOCAMENTE EM English.

2. Definições precisas de ferramentas e condições de invocação

Ao expor ferramentas para a Live API:

• Inclua sempre anotações de tipo e descrições detalhadas dos parâmetros.
• Documente explicitamente as condições de invocação dentro da descrição/metadata da ferramenta (por exemplo, "Invoque esta ferramenta somente depois que o usuário confirmar a data de partida e o destino"). Isso evita que o LLM acione funções antes da hora.

3. Gerenciando o contexto de áudio nativo (compressão)

Tokens de áudio nativo se acumulam rapidamente, cerca de 25 tokens por segundo de conversa. Em sessões longas, isso pode encher a janela de contexto e aumentar a latência.

• Ative ContextWindowCompressionConfig nas configurações da conexão para descartar histórico antigo ao atingir um limite:

from google.genai import types
live_config = types.LiveConnectConfig(
   context_window_compression=types.ContextWindowCompressionConfig(
       trigger_tokens=100_000,
       sliding_window=types.SlidingWindow(target_tokens=4_000),
   ),
)Tecnologia

Atenção: a compressão de contexto fará com que partes antigas do histórico da conversa sejam perdidas.

4. Retomada transparente de sessão

Conexões móveis em tempo real estão sujeitas a perda de pacotes e desconexões temporárias. Em vez de iniciar um novo estado de conversa do zero, implemente uma retomada transparente de sessão:

• Configure seu stream com SessionResumptionConfig(transparent=True).
• Escute eventos session_resumption_update do servidor e armazene o new_handle.
• Mantenha um buffer local de mensagens de saída. Quando a conexão cair, capture o APIError ou o sinal GoAway, reconecte usando o handle salvo e reenvie apenas as mensagens do cliente não confirmadas (usando o server-reported last_consumed_client_message_index para podar o buffer).

5. Otimização do streaming de áudio

• Bufferização no cliente: Não faça buffer de frames de áudio longos no cliente antes de enviar. Transmita blocos pequenos (entre 20 ms e 40 ms) continuamente para minimizar a latência de ponta a ponta.
• Ressampling do microfone: Garanta que a captura de áudio no cliente faça o reamostramento das entradas (normalmente 44,1 kHz ou 48 kHz) para 16 kHz PCM antes de enviar pelo WebSocket.
• Sinais explícitos de VAD: Deixe o modelo cuidar da detecção de atividade de voz (VAD). Se o seu frontend precisar mostrar indicadores imediatos de UI (por exemplo, "IA está ouvindo" vs. "IA está pensando"), ative explicit_vad_signal=True na configuração para receber eventos de início/parada de VAD diretamente no fluxo de mensagens do servidor.

6. Segurança (gestão de tokens)

• Nunca codifique chaves mestras no código: Evite expor sua API key do AI Studio ou credenciais de Service Account do Google Cloud no código do lado do cliente (navegador ou apps mobile).
• Implemente troca de tokens efêmeros: Construa um endpoint de autenticação no seu backend seguro. Quando um cliente quiser iniciar uma sessão de voz, o backend gera um token de acesso OAuth ou API de curta duração e com permissões restritas (por exemplo, via Vertex AI IAM) e o envia ao cliente. O cliente usa essa credencial temporária para abrir a conexão WebSocket direta.

Conclusão: o horizonte da IA conversacional

A transição de LLMs baseados em turnos e apenas texto para streaming multimodal de baixa latência representa uma mudança de paradigma na forma como construímos interfaces humano-computador. Ao processar áudio e vídeo de forma nativa por conexões WebSocket com estado, a Gemini Live API permite criar experiências agentic que parecem menos com softwares estáticos e mais com interações humanas fluídas.

Ao longo deste guia, exploramos a arquitetura interna da Gemini Live, analisamos os modelos de preços e construímos um AI Travel Concierge completo usando o Google Agent Development Kit (ADK). Vimos como o ADK mapeia funções Python padrão para ferramentas ativas do agente, dando ao nosso assistente de voz acesso tanto a grounding amplo via web quanto a consultas a bancos internos privados.

O que construir a seguir? 

Agora que você já domina os fundamentos de agentes de voz em tempo real, considere estender seu AI Travel Concierge: 

1. Expor streams de vídeo ao vivo: adicione suporte para transmissão de imagens da câmera para o concierge “ver” mapas, cartões de embarque ou vouchers físicos em tempo real. 
2. Integrar ferramentas transacionais personalizadas: implemente uma ferramenta book_flight ou reserve_hotel que altere estado real, integrando escopos de autenticação para confirmações seguras do usuário. 
3. Roteamento de middleware para produção: saia dos testes locais com ADK para um framework baseado em WebRTC usando LiveKit ou Pipecat, transmitindo chamadas de voz de produção diretamente de apps web e mobile.

Pronto para criar fluxos conversacionais mais avançados? Confira a trilha de habilidades AI Agent Fundamentals da DataCamp para aprofundar seu conhecimento em arquiteturas agentic, uso de ferramentas e deploys de IA generativa.