Migrar do áudio nativo da API Gemini 2.5 Flash Live para o Gemini 3.8 Live

Este documento descreve as mudanças necessárias ao migrar do áudio nativo da API Gemini 2.5 Flash Live para o Gemini 3.8 Live.

Mudanças na chamada de função

O servidor de áudio nativo da API Gemini 2.5 Flash Live permite chamadas assíncronas de ferramentas. Por outro lado, o Gemini 3.8 Live oferece suporte à chamada de função assíncrona com as seguintes mudanças de comportamento:

• O Gemini 3.8 Live oferece suporte à função de bloqueio de chamadas quando a declaração de função declara behavior=BLOCKING na configuração. Se uma nova entrada for recebida durante a execução da chamada de função de bloqueio, o servidor da API Live vai cancelar a chamada de função atual.

• O comportamento da opção scheduling=interrupt para FunctionResponse mudou:

  Programação de FunctionResponse	Quem está falando	Áudio nativo da API Gemini 2.5 Flash Live	Gemini 3.8 Live
  interromper	modelo	Interrompe a resposta imediata do modelo ativo e reproduz a resposta da ferramenta.	Interrompe a resposta imediata do modelo ativo e reproduz a resposta da ferramenta.
  interromper	usuário	Interrompe imediatamente e reproduz a resposta da ferramenta para o usuário.	Aguarde até que o usuário termine antes de reproduzir a resposta da ferramenta.

Como reduzir varreduras redundantes e novas tentativas de chamadas de função

Às vezes, o Gemini Live 3.8 faz chamadas de função redundantes consecutivas em uma única vez quando uma ferramenta não retorna resultados. Isso pode incluir repetir parâmetros variados, fazer uma varredura de duas a cinco vezes antes de responder. O comportamento aumenta o tempo até o primeiro áudio (TTFA, na sigla em inglês) e produz uma fala de substituição imprecisa.

As chamadas de função redundantes consecutivas são causadas pelo Gemini 3.8 Live ao tentar resolver consultas. Quando uma ferramenta retorna uma resposta não informativa ou vazia, como {"results": [], "total_available": 0} ou None, o modelo não consegue distinguir entre "permanentemente esgotado", "janela de consulta muito estreita" ou "argumento inválido". O modelo tenta ampliar ou variar a consulta para melhorar os resultados e começa a fazer uma varredura.

Aplique as seguintes práticas complementares:

• Retorne respostas informativas de funções: toda resposta da ferramenta precisa conter informações sobre o erro ou os resultados para orientar o modelo Gemini 3.8 Live sobre como proceder.

  A tabela a seguir descreve os casos, como o modelo deve responder e um exemplo de payload necessário para ajudar o modelo:

  Caso	O que o modelo deve fazer	Conteúdo obrigatório do payload
  Consulta válida que não retorna resultados. Tentar de novo não vai ajudar.	Pare de pesquisar, informe o usuário e ofereça alternativas.	status: 'no_results', retryable: false, e uma mensagem explicativa clara em linguagem natural.
  Argumento inválido ou inexistente (por exemplo, "provedor errado").	Pare de pesquisar e peça para o usuário esclarecer ou confirmar.	Lista de status: 'invalid_argument', reason_code, retryable: false e valid_options
  Consulta válida com uma janela vazia. Uma consulta mais ampla realmente ajuda.	Faça uma nova tentativa razoável.	status: 'no_results_in_range', retryable: true e retry_hint

  O exemplo a seguir demonstra um payload em que search_appointment é chamado, mas todas as datas possíveis estão indisponíveis. O usuário espera experimentar um fornecedor em vez de varrer as datas:

  def search_appointment(vendor: str, date: Datetime):
  
  # BEFORE (Invites Sweeping):
  {
    "results": [],
    "total_available": 0
  }
  
  # AFTER - Exhausted / Dead End (Stops Sweeping):
  {
    "results": [],
    "status": "no_availability",
    "retryable": false,
    "message": "No appointments are available for this provider for the foreseeable future. Searching other dates will not surface anything; openings only come from cancellations.",
    "suggested_next_step": "offer_waitlist_or_a_different_provider"
  }
  
  # AFTER - Invalid Argument (Prompts User Clarification):
  {
    "results": [],
    "status": "invalid_argument",
    "reason": "no_such_provider",
    "retryable": false,
    "message": "There is no provider named 'Mr. Johnson'. Ask the caller to confirm the name.",
    "valid_options": ["Dr. Johnson", "Dr. Chen"]
  }
  

  O exemplo a seguir demonstra o processamento quando check_user_account não retorna correspondências exatas. O resultado esperado é modificar a consulta de pesquisa ou transferir o controle de volta para o usuário em vez de tentar novamente:

  def check_user_account(user_name: str, phone_suffix: str):...
  
  # Checked user account but not existing
  # BEFORE: insufficient error information
  {
   "found": false,
   "matches": []
  }
  
  # AFTER: providing sufficient information to the LiveAPI to avoid further retries because the retries have been exhausted.
  {
   "status": "EXHAUSTED",
   "retryable": false,
   "search_criteria": {
     "name": "Alex Rivera",
     "phone_suffix": "4921"
   },
   "search_scope": "Checked active orders, archived accounts, and guest checkouts across all regions.",
   "guidance": "Exhaustive search completed with 0 matches. Do NOT retry with parameter substrings or variations. Inform the user that no account was found matching those details, and ask if they have an Order ID or billing email."
  }
  

• Política de novas tentativas de instruções do sistema: complemente respostas informativas com uma restrição explícita na instrução do sistema:

  "When a tool returns no results, tell the user the result before calling the
  tool again. If a call fails for a reason fundamental to the arguments (for
  example, the entity does not exist), do not silently retry with variations;
  ask the user to clarify or confirm. You may broaden a query once when a
  result set is simply empty. Do not run repeated searches with different
  parameters on your own initiative. Hard cap: Never issue more than two
  consecutive function calls without saying something back to the user."
  

Troca de histórico de sessões

No áudio nativo da API Gemini 2.5 Flash Live, send_client_content é usado para configurar o seeding de histórico antes da primeira vez e para adicionar mais histórico durante a sessão.

No Gemini 3.8 Live, se você quiser usar o método send_client_content para configurar a inclusão de histórico, na seção HistoryConfig da mensagem de configuração, defina initial_history_in_client_content=True. Depois de receber setup_complete. Em seguida, chame send_client_content repetidamente para criar o histórico até a última mensagem em que turn_complete=True está definido.

Diferenças no comportamento do modelo

A tabela a seguir descreve as diferenças no comportamento do modelo para áudio, multimodelos e saída entre o áudio nativo da API Gemini 2.5 Flash Live e o Gemini 3.8 Live:

O código Python a seguir demonstra a definição de media_resolution e custom_vocabulary:

# Example: Setting media_resolution for image frames in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,  # or MEDIA_RESOLUTION_LOW or MEDIA_RESOLUTION_MEDIUM
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    # Send image frames with the configured resolution budget
    ...


# Example: Setting custom_vocabulary for domain-specific word biasing in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["Gemini", "MagicWord", "Lagrangian"],
    ),
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    ...

Compatibilidade com frameworks de terceiros

As seções a seguir descrevem como os frameworks de terceiros funcionam com o Gemini 3.8 Live:

LiveKit

O plugin do Google do LiveKit RealtimeModel é compatível com o Gemini 3.8 Live, mas as seguintes configurações não são compatíveis com o plugin do Google do LiveKit:

• thinking_level
• enable_affective_dialog
• proactivity

Recomendamos que você tenha muito cuidado ao usar o plug-in do Google do LiveKit, porque ele exige uma adaptação cuidadosa para funcionar com o Gemini 3.8 Live.

Pipecat

O Pipecat é compatível com o Gemini 3.8 Live e as seguintes mudanças:

• Configuração de raciocínio: remova o nível de raciocínio porque ele não é compatível com o Gemini 3.8 Live.

• O Pipecat conecta endpoints da Agent Platform usando o GoogleVertexLLMService no conector GeminiLiveLLMService.

Telemetria de uso de tokens no nível de conexão

Cada vez que o servidor responde, ele retorna um frame usage_metadata. Isso é consistente em áudio nativo da API Gemini 2.5 Flash Live e Gemini 3.8 Live. Os metadados de uso são mais categorizados, como token em cache, token de uso de ferramenta, tokens em diferentes modalidades e assim por diante.

Limitações e mitigações conhecidas do modelo

Para informações sobre limitações e soluções conhecidas ao desenvolver aplicativos com o Gemini 3.8 Live, consulte Limitações conhecidas.

Lista de verificação de migração

Confira a seguir uma lista de verificação de migração de cliente que você pode usar ao migrar do áudio nativo da API Gemini 2.5 Flash Live para o Gemini 3.8 Live:

• Chamada de função:

  • Respostas informativas da ferramenta: refatore todos os gerenciadores de ferramentas para retornar códigos de status explícitos, flags que podem ser repetidas e explicações em linguagem natural. Nunca retorne None sem formatação ou {} vazio.

  • Política de instruções do sistema: adicione restrições explícitas que proíbem novas tentativas silenciosas de ferramentas, exigem confirmação do usuário em falhas de argumentos e limitam chamadas consecutivas de ferramentas.

  • Correspondência de ID de chamada de ferramenta: verifique se FunctionResponse transmite id=fc.id em todas as respostas de ferramentas.

  • Mudança no comportamento de programação de funções: quando o usuário está falando, o scheduling=interrupt passa para scheduling=when_idle para oferecer uma experiência do usuário mais tranquila.

• Sessão: restringir send_client_content: use send_client_content para definir o histórico inicial fornecendo um HistoryConfig adequado.

• Pensamento: elimine hacks de pensamento no nível do comando: para evitar áudio cortado, remova todo o texto do comando que tenta impor esquemas de pensamento ou limites de token.