Prácticas recomendadas con la API de Gemini Live

Para obtener mejores resultados con la API de Gemini Live, enfócate en las siguientes prácticas recomendadas:

Diseña instrucciones claras del sistema

Para obtener el mejor rendimiento de la API de Gemini Live, te recomendamos que tengas un conjunto claramente definido de instrucciones del sistema (SI) que definan el arquetipo del agente, las reglas de conversación y las medidas de protección, en este orden.

Para obtener los mejores resultados, separa cada agente en un SI distinto.

  1. Especifica la personalidad del agente: Proporciona detalles sobre el nombre, el rol y las características preferidas del agente. Si quieres especificar el acento, asegúrate de indicar también el idioma de salida preferido (por ejemplo, un acento británico para un hablante de inglés).

  2. Especifica las reglas de conversación: Coloca estas reglas en el orden en que esperas que el modelo las siga. Delimita los elementos únicos de la conversación y los bucles conversacionales. Por ejemplo:

    • Elemento único: Recopila los detalles de un cliente una sola vez (como el nombre, la ubicación o el número de tarjeta de lealtad).
    • Bucle conversacional: El usuario puede hablar sobre recomendaciones, precios, devoluciones y entrega, y es posible que quiera pasar de un tema a otro. Permite que el modelo sepa que puede participar en este ciclo conversacional durante el tiempo que el usuario desee.

  3. Especifica las llamadas a herramientas dentro de un flujo en oraciones distintas: Por ejemplo, si un paso único para recopilar los detalles de un cliente requiere invocar una función de get_user_info, puedes decir: El primer paso es recopilar la información del usuario. Primero, pídele al usuario que proporcione su nombre, ubicación y número de tarjeta de lealtad. Luego, invoca get_user_info con estos detalles.

  4. Agrega las protecciones necesarias: Proporciona las protecciones generales de conversación que no quieres que haga el modelo. No dudes en proporcionar ejemplos específicos de si sucede x, quieres que el modelo haga y. Si aún no obtienes el nivel de precisión deseado, usa la palabra inequívocamente para guiar al modelo y que sea preciso.

Define las herramientas con precisión

Cuando uses herramientas con la API de Gemini Live, sé específico en las definiciones de las herramientas. Asegúrate de indicarle a Gemini en qué condiciones se debe invocar una llamada a la herramienta. Para obtener más detalles, consulta Definiciones de herramientas.

Crea instrucciones eficaces

  • Usa instrucciones claras: Proporciona ejemplos de lo que el modelo debe y no debe hacer en las instrucciones, y trata de limitar las instrucciones a una por arquetipo o rol a la vez. En lugar de usar instrucciones largas de varias páginas, considera usar el encadenamiento de instrucciones. El modelo funciona mejor en tareas con llamadas a funciones ú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.

  • Proporciona comandos e información iniciales: La API de Gemini Live espera la entrada del usuario antes de responder. Para que la API de Gemini Live inicie la conversación, incluye una instrucción que le pida que salude al usuario o que comience la conversación. Incluye información sobre el usuario para que la API de Gemini Live personalice el saludo.

Reanudación de la sesión

  1. Usa la reanudación transparente de la sesión: Configura la conexión con SessionResumptionConfig(transparent=True) en genai.types.LiveConnectConfig. Esto indica que el cliente pretende controlar la reanudación de la sesión sin problemas, lo que permite funciones como la reproducción de mensajes no consumidos al restablecer la conexión.
from google.genai import types

session_handle: str | None = None

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

  1. Mantener y actualizar el identificador de sesión: Escucha los mensajes session_resumption_update del servidor. Si resumable es verdadero y se proporciona un new_handle, almacena este identificador. Este identificador es esencial para volver a conectarse al mismo estado de sesión si se produce una desconexión.

  2. Almacena en búfer los mensajes enviados y descarta los que se hayan confirmado: Para garantizar que no se pierda ningún mensaje del cliente durante una desconexión, mantén un búfer de los mensajes enviados a la API de Gemini Live. El mensaje session_resumption_update contendrá last_consumed_client_message_index cuando se habilite la reanudación transparente de la sesión, lo que indica el último mensaje que procesó el servidor. Usa este índice para quitar los mensajes confirmados del búfer. Para hacer un seguimiento correcto de los mensajes, el índice administrado por el usuario debe comenzar en 1, ya que el índice 0 indica que the session is not resumable. Cada mensaje posterior que se envíe al modelo debe incrementar este índice en 1. En cada reanudación de sesión, asegúrate de que el índice se restablezca en 1 para el mensaje inicial transmitido con la nueva conexión.

  3. Controla las desconexiones de forma correcta:

    • Indicador GoAway: El servidor envía un mensaje go_away antes de una desconexión esperada (como un tiempo de espera). El administrador debe escuchar esto y, luego, volver a conectarse de forma proactiva con el identificador más reciente.
    • Errores de API: Los problemas de red pueden causar genai_errors.APIError (por ejemplo, los códigos 1000 o 1006 para errores de WebSocket). El administrador debe detectar estos errores en los bucles de envío y recepción, y activar el proceso de actualización o reconexión de la sesión.

  4. Implementa la reconexión con reproducción de mensajes: Cuando se produzca una desconexión, crea una sesión nueva con client.aio.live.connect y el identificador de sesión más reciente. Después de establecer la nueva conexión, vuelve a enviar los mensajes del búfer que el servidor no confirmó antes de la desconexión. El primer mensaje enviado en el búfer debe marcarse como índice 1 para la conexión nueva.

Habilita la compresión de la ventana de contexto

Usa ContextWindowCompressionConfig para configurar la ventana de contexto de la sesión para sesiones largas, ya que los tokens de audio en vivo se acumulan rápidamente (aproximadamente 25 tokens por segundo de audio).

Advertencia: La compresión del contexto provocará la pérdida del historial de conversaciones.

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 del uso de tokens

La estructura de facturación de la API de Gemini Live se detalla en la página de precios. En cada turno, la API factura todos los tokens de contexto, que abarcan tanto el historial de conversación como la instrucción del sistema proporcionada por el usuario. Los desarrolladores pueden supervisar y calcular estos cargos extrayendo el campo usage_metadata que se proporciona en la respuesta del 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)

Detección de actividad de voz (VAD)

De forma predeterminada, la API de Gemini Live usa el VAD proporcionado por Gemini.

Cuando utilizas el VAD de la API de Gemini Live, puedes configurar el modelo para que devuelva eventos de VAD de forma explícita. Si habilitas explicit_vad_signal en tu configuración, podrás supervisar y capturar estos eventos directamente desde las respuestas del 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)

Si prefieres usar un sistema de detección de actividad personalizado, debes desactivar la detección de actividad de voz (VAD) predeterminada y señalar manualmente los turnos del usuario al modelo de Gemini. Esto se logra transmitiendo eventos ActivityStart o ActivityEnd para definir los límites de la interacción.

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

Establece el código de idioma del audio

Se recomienda configurar explícitamente el idioma y el código de voz en tu configuración para mantener la coherencia. Sin esta definición, Gemini podría alterar el idioma de la conversación según el contexto proporcionado.

from google.genai import types

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

También menciona lo siguiente en la instrucción del sistema:

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

En el caso de los modelos de audio en vivo, como gemini-3.8-live, puedes mejorar la calidad de la transcripción para el reconocimiento de voz automático (ASR) multilingüe proporcionando sugerencias de idioma en la configuración de tu sesión. Para obtener más información, consulta Cómo habilitar la transcripción de audio para la sesión.

Cómo establecer el código de idioma de la transcripción

Especifica los códigos de idioma de transcripción para aumentar la precisión de la transcripción con el formato de código de idioma BCP-47.

Nota: Habilitar la transcripción introduce más 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']
  ),
)

Cómo sesgar la transcripción con un vocabulario personalizado

Los nombres de productos, los nombres internos en clave, los nombres de medicamentos y los identificadores estilizados suelen estar ausentes del vocabulario predeterminado de un modelo de reconocimiento de voz, por lo que el modelo transcribe la palabra común más cercana. Enumera estos términos en el campo custom_vocabulary de input_audio_transcription para sesgar el reconocimiento hacia las palabras que realmente dicen tus usuarios.

from google.genai import types

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

La configuración anterior produce las siguientes diferencias de transcripción para el mismo audio:

Término hablado Sin custom_vocabulary Con custom_vocabulary
QwikPay QuickPay QwikPay
Xylotek Xilotech Xylotek
Traefik Trafic Traefik
Leche de avena leche de avena Leche de avena

La ortografía exacta es importante cuando pasas transcripciones a herramientas, búsquedas o registros de clientes, en los que una falta de ortografía, como QuickPay, no coincide con nada.

Enumerar el vocabulario personalizado en la instrucción del sistema no produce el mismo resultado. El uso de custom_vocabulary sesga el reconocedor de voz a medida que procesa el audio, mientras que la instrucción del sistema llega al modelo solo después de que se transcribe el audio.

Mantén la lista enfocada en términos de dominio distintos, nombres de marcas y nombres propios, en lugar de palabras comunes de uso diario. Puedes proporcionar hasta 1,000 términos.

Almacenamiento en búfer del cliente

No almacenes en búfer el audio de entrada de forma significativa (por ejemplo, 1 segundo) antes de enviarlo. Envía fragmentos pequeños (entre 20 y 40 ms) para minimizar la latencia.

Nuevo muestreo

Asegúrate de que tu aplicación cliente vuelva a muestrear la entrada del micrófono (a menudo, 44.1 kHz o 48 kHz) a 16 kHz antes de la transmisión.

Ejemplo

En este ejemplo, se combinan las prácticas recomendadas y los lineamientos para el diseño de instrucciones del sistema para guiar el rendimiento del modelo como asesor profesional.

**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.

Definiciones de herramientas

Este JSON define las funciones pertinentes que se llaman en el ejemplo del asesor profesional. Para obtener los mejores resultados cuando definas funciones, incluye sus nombres, descripciones, parámetros y condiciones de invocación.

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

Más información

Para obtener más información sobre el uso de la API de Gemini Live, consulta los siguientes recursos: