Migra de la API de Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live

En este documento, se describen los cambios necesarios cuando se migra de la API de Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live.

Cambios en las llamadas a funciones

El servidor de audio nativo de la API de Gemini 2.5 Flash Live permite llamadas asíncronas a herramientas. En cambio, Gemini 3.8 Live admite llamadas a funciones asíncronas con los siguientes cambios de comportamiento:

• Gemini 3.8 Live admite el bloqueo de llamadas a funciones cuando la declaración de la función declara behavior=BLOCKING en la configuración. Si se recibe una entrada nueva durante la ejecución de la llamada a función de bloqueo, el servidor de la API de Live cancela la llamada a función actual.

• Se cambió el comportamiento de la opción scheduling=interrupt a FunctionResponse:

  Programación de FunctionResponse	Quién está hablando	Audio nativo de la API de Live de Gemini 2.5 Flash	Gemini 3.8 Live
  interrumpir	modelo	Detiene la respuesta inmediata del modelo activo y reproduce la respuesta de la herramienta.	Detiene la respuesta inmediata del modelo activo y reproduce la respuesta de la herramienta.
  interrumpir	usuario	Interrumpe de inmediato y reproduce la respuesta de la herramienta sobre el usuario.	Espera a que el usuario termine antes de reproducir la respuesta de la herramienta.

Cómo mitigar los reintentos de llamadas a funciones y los análisis redundantes

A veces, Gemini 3.8 Live realiza llamadas a funciones redundantes consecutivas en un solo turno cuando una herramienta no devuelve resultados. Esto puede incluir repetir parámetros variados, hacer un barrido de dos a cinco veces antes de responder. Este comportamiento aumenta el tiempo hasta el primer audio (TTFA) y produce un discurso de resguardo impreciso.

Las llamadas a funciones redundantes consecutivas se deben a que Gemini 3.8 Live intenta resolver las búsquedas. Cuando una herramienta devuelve una respuesta vacía o no informativa, como {"results": [], "total_available": 0} o None, el modelo no puede distinguir entre "agotado de forma permanente", "ventana de búsqueda demasiado estrecha" o "argumento no válido". El modelo intenta ampliar o variar la búsqueda para mejorar los resultados y comienza a explorar.

Aplica las siguientes prácticas complementarias:

• Devuelve respuestas informativas de las funciones: Cada respuesta de la herramienta debe contener información sobre el error o los resultados para guiar al modelo de Gemini 3.8 Live sobre cómo proceder.

  En la siguiente tabla, se describen los casos, cómo debe responder el modelo y un ejemplo de carga útil requerida para ayudar al modelo:

  Caso	Qué debe hacer el modelo	Contenido obligatorio de la carga útil
  Consulta válida que no devuelve resultados. Reintentar no funcionará.	Deja de buscar, informa al usuario y ofrece alternativas.	status: 'no_results', retryable: false, y un mensaje explicativo claro en lenguaje natural.
  Argumento no válido o inexistente (por ejemplo, "proveedor incorrecto").	Deja de buscar y pídele al usuario que aclare o confirme.	status: 'invalid_argument', reason_code, retryable: false y lista de valid_options
  Es una consulta válida que tiene una ventana vacía. Una búsqueda más amplia realmente ayuda.	Realiza un reintento razonable.	status: 'no_results_in_range', retryable: true y retry_hint

  En el siguiente ejemplo, se muestra una carga útil de ejemplo en la que se llama a search_appointment, pero todas las fechas posibles no están disponibles. El usuario espera probar un proveedor en lugar de explorar las fechas:

  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"]
  }
  

  En el siguiente ejemplo, se muestra el control cuando check_user_account no devuelve coincidencias exactas. El resultado esperado es modificar la búsqueda o devolver el control al usuario en lugar de volver a intentarlo:

  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 reintentos de instrucciones del sistema: Complementa las respuestas informativas con una restricción explícita en la instrucción del 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."
  

Intercambio del historial de sesiones

En el audio nativo de la API de Gemini 2.5 Flash Live, send_client_content se usa para configurar la inicialización del historial antes del primer turno y para agregar historial adicional durante la mitad de la sesión.

En Gemini Live 3.8, si quieres usar el método send_client_content para configurar la inicialización del historial, en la sección HistoryConfig del mensaje de configuración, establece initial_history_in_client_content=True. Después de recibir setup_complete Luego, puedes llamar a send_client_content de forma repetida para crear un historial hasta el último mensaje en el que se establece turn_complete=True.

Diferencias en el comportamiento del modelo

En la siguiente tabla, se describen las diferencias en el comportamiento del modelo para el audio, el modelo multimodal y la salida entre el audio nativo de la API de Gemini 2.5 Flash Live y Gemini 3.8 Live:

En el siguiente código de Python, se muestra cómo configurar media_resolution y 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:
    ...

Compatibilidad con frameworks de terceros

En las siguientes secciones, se describe cómo funcionan los frameworks de terceros con Gemini 3.8 Live:

LiveKit

El complemento de Google de LiveKit, RealtimeModel, admite Gemini 3.8 Live, pero la siguiente configuración no es compatible con el complemento de Google de LiveKit:

• thinking_level
• enable_affective_dialog
• proactivity

Te recomendamos que tengas especial cuidado cuando uses el complemento de Google de LiveKit, ya que requiere una adaptación cuidadosa para funcionar con Gemini 3.8 Live.

Pipecat

Pipecat admite Gemini 3.8 Live con los siguientes cambios:

• Configuración de pensamiento: Se quita el nivel de pensamiento, ya que Gemini 3.8 Live no lo admite.

• Pipecat conecta los extremos de Agent Platform con GoogleVertexLLMService a través del conector GeminiLiveLLMService.

Telemetría del uso de tokens a nivel de cable

Cada turno del servidor devuelve un fotograma de usage_metadata. Esto se aplica a la API de Gemini 2.5 Flash Live Native Audio y a Gemini 3.8 Live. Los metadatos de uso están más categorizados, como el token almacenado en caché, el token de uso de herramientas, los tokens en diferentes modalidades, etcétera.

Limitaciones conocidas del modelo y mitigaciones

Para obtener información sobre las limitaciones conocidas y las mitigaciones cuando desarrolles aplicaciones con Gemini 3.8 Live, consulta Limitaciones conocidas.

Lista de tareas para la migración

A continuación, se incluye una lista de verificación de la migración del cliente que puedes usar cuando migres de la API de Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live:

• Llamada a funciones:

  • Respuestas informativas de herramientas: Se refactorizan todos los controladores de herramientas para que devuelvan códigos de estado explícitos, marcas de reintento y explicaciones en lenguaje natural. Nunca devuelvas None sin formato o {} vacío.

  • Política de instrucciones del sistema: Agrega restricciones explícitas que prohíben los reintentos silenciosos de herramientas, requieren la confirmación del usuario en caso de errores de argumentos y limitan las llamadas consecutivas a herramientas.

  • Coincidencia del ID de llamada a la herramienta: Asegúrate de que FunctionResponse pase id=fc.id en cada respuesta de la herramienta.

  • Cambio en el comportamiento de la programación de funciones: Cuando el usuario está hablando, scheduling=interrupt se degrada a scheduling=when_idle para proporcionar una experiencia del usuario más fluida.

• Sesión: Restringe send_client_content: Usa send_client_content para establecer el historial inicial proporcionando un HistoryConfig adecuado.

• Pensamiento: Elimina las sugerencias de pensamiento a nivel de la instrucción: Para evitar que se corte el audio, quita todo el texto de la instrucción que intente aplicar esquemas de pensamiento paso a paso o límites de tokens.