O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Práticas recomendadas com a API Gemini Live

Para ter resultados melhores com a API Gemini Live, siga estas práticas recomendadas:

Criar instruções claras para o sistema
Defina as ferramentas com precisão
Criar comandos eficazes

Criar instruções claras para o sistema

Para ter o melhor desempenho da API Gemini Live, recomendamos ter um conjunto claramente definido de instruções do sistema (SIs) que definem a persona do agente, as regras de conversação e as proteções, nessa ordem.

Para melhores resultados, separe cada agente em uma SI distinta.

Especifique o perfil do agente: forneça detalhes sobre o nome, a função e as características preferidas do agente. Se você quiser especificar o sotaque, especifique também o idioma de saída preferido (como um sotaque britânico para um falante de inglês).
Especifique as regras de conversação: coloque essas regras na ordem que você espera que o modelo siga. Diferencie os elementos únicos da conversa dos loops de conversa. Exemplo:
- Elemento único: colete os detalhes de um cliente uma vez (como nome, local, número do cartão fidelidade).
- Loop de conversa: o usuário pode discutir recomendações, preços, devoluções e entregas, e pode querer mudar de assunto. Informe ao modelo que não há problema em participar desse loop de conversa pelo tempo que o usuário quiser.
Especifique as chamadas de ferramenta em um fluxo em frases distintas: por exemplo, se uma etapa única para coletar os detalhes de um cliente exigir a invocação de uma função get_user_info, você poderá dizer: Sua primeira etapa é coletar informações do usuário. Primeiro, peça ao usuário para informar o nome, o local e o número do cartão fidelidade. Em seguida, invoque get_user_info com esses detalhes.
Adicione as proteções necessárias: forneça proteções gerais de conversação que você não quer que o modelo faça. Forneça exemplos específicos de se x acontecer, você quer que o modelo faça y. Se você ainda não estiver conseguindo o nível de precisão desejado, use a palavra unmistakably para orientar o modelo a ser preciso.

Defina as ferramentas com precisão

Ao usar ferramentas com a API Gemini Live, seja específico nas definições delas. Informe ao Gemini em que condições uma chamada de ferramenta deve ser invocada. Para mais detalhes, consulte Definições de ferramentas.

Criar comandos eficazes

Use comandos claros: forneça exemplos do que o modelo deve e não deve fazer nos comandos e tente limitar os comandos a um por persona ou função de cada vez. Em vez de comandos longos de várias páginas, use o encadeamento de comandos. O modelo tem melhor desempenho em tarefas com chamadas de função únicas.

# Prompt chaining example.
chainable_long_prompt = """
You need to perform a sequence of tasks.
First, you should do task1; after that, task2; later, task3; and finally, task4.
"""

# New initial prompt
"""
You need to perform a sequence of tasks. Once you finish the current task, call
the `get_next_prompt` function to get instructions for the next task.
"""

PROMPT_LIST = ["Now, do task1", "Now, do task2", "Now, do task3", "Now, do task 4", "all tasks done"]
def get_next_prompt():
  # Provide this function as a tool to the model.
  for prompt in PROMPT_LIST:
    yield prompt

# Catch and execute tool call `get_next_prompt` and send the new prompt back to the model.

Forneça comandos e informações iniciais: a API Gemini Live espera a entrada do usuário antes de responder. Para que a API Gemini Live inicie a conversa, inclua um comando pedindo que ela cumprimente o usuário ou comece a conversa. Inclua informações sobre o usuário para que a API Gemini Live personalize essa saudação.

Retomada da sessão

Use a retomada de sessão transparente: configure a conexão com SessionResumptionConfig(transparent=True) em genai.types.LiveConnectConfig. Isso indica que o cliente pretende lidar com a retomada da sessão de forma integrada, permitindo recursos como a repetição de mensagens não consumidas após a reconexão.

from google.genai import types

session_handle: str | None = None

live_config = types.LiveConnectConfig(
  session_resumption=types.SessionResumptionConfig(
      handle=session_handle,
      transparent=True,
  ),
)

Manter e atualizar o identificador de sessão: detecte mensagens session_resumption_update do servidor. Se resumable for verdadeiro e um new_handle for fornecido, armazene esse identificador. Esse identificador é essencial para se reconectar ao mesmo estado de sessão se ocorrer uma desconexão.
Armazenar em buffer as mensagens enviadas e remover as confirmadas: para garantir que nenhuma mensagem do cliente seja perdida durante uma desconexão, mantenha um buffer de mensagens enviadas para a API Gemini Live. A mensagem session_resumption_update vai conter last_consumed_client_message_index quando a retomada transparente da sessão estiver ativada, indicando a última mensagem processada pelo servidor. Use esse índice para remover as mensagens confirmadas do buffer. Para rastrear mensagens corretamente, o índice gerenciado pelo usuário precisa começar em 1, porque o índice 0 indica que the session is not resumable. Cada mensagem subsequente enviada ao modelo precisa incrementar esse índice em 1. A cada retomada de sessão, verifique se o índice foi redefinido como 1 para a mensagem inicial transmitida usando a nova conexão.
Lide com desconexões de maneira adequada:
- Sinal GoAway: o servidor envia uma mensagem go_away antes de uma desconexão esperada (como um tempo limite). O gerenciador precisa detectar isso e, em seguida, se reconectar de forma proativa usando o identificador mais recente.
- Erros de API: problemas de rede podem causar genai_errors.APIError (por exemplo, códigos 1000 ou 1006 para erros de WebSocket). O gerenciador precisa capturar esses erros nos loops de envio e recebimento e acionar o processo de atualização ou reconexão da sessão.
Implemente a reconexão com a repetição de mensagens: quando ocorrer uma desconexão, crie uma nova sessão usando client.aio.live.connect com o identificador de sessão mais recente. Depois de estabelecer a nova conexão, reenvie todas as mensagens no buffer que não foram confirmadas pelo servidor antes da desconexão. A primeira mensagem enviada no buffer precisa ser marcada como índice 1 para a nova conexão.

Ativar a compactação da janela de contexto

Use ContextWindowCompressionConfig para configurar a janela de contexto da sessão para sessões longas, já que os tokens de áudio ao vivo se acumulam rapidamente (aproximadamente 25 tokens por segundo de áudio).

Aviso: a compactação de contexto vai causar a perda do histórico de conversas.

from google.genai import types

live_config = types.LiveConnectConfig(
  context_window_compression=types.ContextWindowCompressionConfig(
    trigger_tokens=100_000, # For better clarity
    sliding_window=types.SlidingWindow(target_tokens=4_000),
  ),
)

Cálculo do uso de tokens

A estrutura de faturamento da API Gemini Live está detalhada na página de preços. Durante cada turno, a API cobra por todos os tokens de contexto, o que inclui o histórico de conversas e as instruções do sistema fornecidas pelo usuário. Os desenvolvedores podem monitorar e calcular essas cobranças extraindo o campo usage_metadata fornecido na resposta do modelo.

# Example code to get token usage
from google.genai import live

session: live.AsyncSession
async for response in session.receive():
  if response.usage_metadata is not None:
    print("Token usage:", response.usage_metadata)

Detecção de atividade de voz (VAD)

Por padrão, a API Gemini Live usa a VAD fornecida pelo Gemini.

Ao usar a VAD da API Gemini Live, é possível configurar o modelo para retornar eventos de VAD explicitamente. Ao ativar explicit_vad_signal na sua configuração, você pode monitorar e capturar esses eventos diretamente das respostas do modelo.

from google.genai import types
from google.genai import live

live_config = types.LiveConnectConfig(
  explicit_vad_signal=True
)

session: live.AsyncSession
# In receive loop
async for response in session.receive():
  if response.voice_activity is not None:
    print("Get VAD event", response.voice_activity)

Se você preferir usar um sistema personalizado de detecção de atividade, desative a detecção de atividade de voz (VAD) padrão e sinalize manualmente as interações do usuário para o modelo do Gemini. Para isso, transmita eventos ActivityStart ou ActivityEnd para definir os limites de interação.

from google.genai import live
from google.genai import types

# Disable VAD in config
live_config = types.LiveConnectConfig(
  realtime_input_config=types.RealtimeInputConfig(
    automatic_activity_detection=types.AutomaticActivityDetection(
        disabled=True
    ),
  ),
)

session: live.AsyncSession
await session.send_realtime_input( # Send activity start
    activity_start=types.ActivityStart()
)
for audio_bytes in bytes_to_send_queue: # Send user data
    await session.send_realtime_input(
        audio=types.Blob(
            data=audio_bytes,
            mime_type=f"audio/pcm;rate=16000",
        )
    )
await session.send_realtime_input(activity_end=types.ActivityEnd()) # Send activity end

Definir código de idioma do áudio

É recomendável definir explicitamente o código de idioma e voz na configuração para manter a consistência. Sem essa definição, o Gemini pode alterar o idioma da conversa dependendo do contexto fornecido.

from google.genai import types

config = types.LiveConnectConfig(
  speech_config=types.SpeechConfig(
    language_code="en-US",
  ),
)

Mencione também o seguinte na instrução do sistema:

RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.

Para modelos de áudio ao vivo, como gemini-3.8-live, é possível melhorar a qualidade da transcrição para o reconhecimento automático de fala (ASR, na sigla em inglês) multilíngue fornecendo dicas de idioma na configuração da sessão. Para mais informações, consulte Ativar a transcrição de áudio para a sessão.

Controlar o ritmo da fala com uma voz de referência

Em modelos de áudio ao vivo, como o Gemini 3.8 Live, os comandos de instrução do sistema que pedem ao modelo para falar mais rápido ou mais devagar não mudam de forma confiável a taxa de fala sintetizada. Para controlar o ritmo da fala, configure uma voz personalizada no campo replicated_voice_config com uma amostra de áudio de referência acelerada ou desacelerada. As respostas sintetizadas herdam a taxa de fala e a cadência da amostra que você transmite no campo voice_sample_audio.

Para ajustar o ritmo da fala com uma voz de referência, siga estas etapas:

Obtenha uma amostra de áudio limpa de 10 a 20 segundos da voz de destino. Você pode gravar sua própria amostra de voz ou capturar uma resposta de uma voz predefinida usando uma instrução neutra do sistema sem diretrizes de ritmo. Para ver as diretrizes de gravação, consulte Usar uma voz personalizada.
Aplique o alongamento de tempo com preservação de tom para acelerar ou desacelerar a amostra e exporte o resultado como um arquivo WAV mono little-endian assinado de 24 kHz e 16 bits. Use um filtro que preserve o tom, como o filtro atempo do ffmpeg, com um multiplicador entre 0.8 e 1.5 para que a velocidade da fala mude sem alterar o tom ou o timbre da voz. Valores menores que 1.0 diminuem a velocidade da voz, e valores maiores que 1.0 aumentam.

Por exemplo, o comando ffmpeg a seguir acelera uma gravação de referência em 1,25x, preservando o tom e formatando a saída como um arquivo WAV mono de 24 kHz e 16 bits:
```
ffmpeg -i INPUT_WAV \
  -filter:a "atempo=1.25" -ar 24000 -ac 1 -sample_fmt s16 \
  PACED_WAV
```
Substitua:
- INPUT_WAV: o caminho para a amostra de voz original.
- PACED_WAV: o caminho de saída para o arquivo WAV mono de 24 kHz com escala de tempo.

Leia o arquivo WAV com escala de tempo e transmita os bytes para ReplicatedVoiceConfig em LiveConnectConfig:

from google.genai import types

with open("PACED_WAV", "rb") as f:
  voice_sample_bytes = f.read()

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            replicated_voice_config=types.ReplicatedVoiceConfig(
                mime_type="audio/wav",
                voice_sample_audio=voice_sample_bytes,
            ),
        ),
    ),
)

Substitua PACED_WAV pelo caminho para o arquivo WAV mono de 24 kHz com escala de tempo.

Definir o código de idioma da transcrição

Especifique os códigos de idioma da transcrição para aumentar a precisão dela usando o formato de código de idioma BCP-47.

Observação: ativar a transcrição introduz mais tokens.

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']  # This supports multiple language codes.
  ),
  output_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']
  ),
)

Enviesar a transcrição com um vocabulário personalizado

Nomes de produtos, codinomes internos, nomes de medicamentos e identificadores estilizados costumam estar ausentes do vocabulário padrão de um modelo de reconhecimento de fala. Por isso, o modelo transcreve a palavra comum mais próxima. Liste esses termos no campo custom_vocabulary de input_audio_transcription para que o reconhecimento seja direcionado às palavras que os usuários realmente dizem.

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US'],
      custom_vocabulary=['QwikPay', 'Xylotek', 'Traefik', 'oatmilk'],
  ),
)

A configuração anterior produz as seguintes diferenças de transcrição para o mesmo áudio:

Termo falado	Sem `custom_vocabulary`	Com o `custom_vocabulary`
QwikPay	QuickPay	QwikPay
Xylotek	Xilotech	Xylotek
Traefik	Tráfego	Traefik
leite de aveia	leite de aveia	leite de aveia

A ortografia exata é importante quando você transmite transcrições para ferramentas, consultas de pesquisa ou registros de clientes, em que uma quase correspondência, como QuickPay, não corresponde a nada.

Listar o vocabulário personalizado na instrução do sistema não produz o mesmo resultado. O uso de custom_vocabulary influencia o reconhecedor de fala enquanto ele processa o áudio, enquanto a instrução do sistema chega ao modelo somente depois que o áudio é transcrito.

Mantenha a lista segmentada para termos de domínio, nomes de marcas e nomes próprios distintos, em vez de palavras comuns do dia a dia. Você pode fornecer até 1.000 termos.

Armazenamento em buffer do cliente

Não armazene em buffer o áudio de entrada de forma significativa (por exemplo, 1 segundo) antes de enviar. Envie pequenos blocos (entre 20 ms e 40 ms) para minimizar a latência.

Reamostragem

Verifique se o aplicativo cliente reamostra a entrada do microfone (geralmente 44,1 kHz ou 48 kHz) para 16 kHz antes da transmissão.

Exemplo

Este exemplo combina as práticas recomendadas e as diretrizes para o design de instruções do sistema para orientar o desempenho do modelo como coach de carreira.

**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data-driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat what the client says back to them.
Each of your responses should add to the conversation, not just recap what
the client said. Be relatable by bringing in your own background
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.

Definições de ferramentas

Este JSON define as chamadas de função relevantes no exemplo do coach de carreira. Para melhores resultados ao definir funções, inclua os nomes, as descrições, os parâmetros e as condições de invocação.

[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]

Mais informações

Para mais informações sobre como usar a API Gemini Live, consulte: