Prácticas recomendadas con la API de Gemini Live

Para obtener mejores resultados de 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 de instrucciones del sistema (IS) claramente definido que defina la personalidad del agente, las reglas conversacionales y las barreras de protección, en este orden.

Para obtener mejores resultados, separa cada agente en una IS distinta.

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

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

    • Elemento único: Recopila los detalles de un cliente una vez (como el nombre, la ubicación y el número de tarjeta de lealtad).
    • Bucle conversacional: El usuario puede analizar recomendaciones, precios, devoluciones y entregas, y es posible que desee pasar de un tema a otro. Informa al modelo que está bien participar en este bucle conversacional durante el tiempo que desee el usuario.

  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 get_user_info, puedes decir lo siguiente: Tu primer paso es recopilar información del usuario. Primero, pídele al usuario que proporcione su nombre, ubicación y número de tarjeta de fidelización. Luego, invoca get_user_info con estos detalles.

  4. Agrega las barreras de protección necesarias: Proporciona las barreras de protección conversacionales generales 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 preferido, usa la palabra inequívocamente para guiar al modelo para 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 herramientas. Asegúrate de informarle a Gemini en qué condiciones se debe invocar una llamada a herramienta. Para obtener más detalles, consulta Definiciones de herramientas.

Elabora 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 personalidad o rol a la vez. En lugar de 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 en la que le pidas que salude al usuario o que comience la conversación. Incluye información sobre el usuario para que la API de Gemini Live personalice ese saludo.

Reanudación de sesión

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

session_handle: str | None = None

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

  1. Mantén y actualiza el controlador de sesión: Escucha los mensajes session_resumption_update del servidor. Si resumable es verdadero y se proporciona un new_handle, almacena este controlador. Este controlador 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 quita los reconocidos: Para garantizar que no se pierdan mensajes del cliente durante una desconexión, mantén un búfer de 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 de sesión transparente, lo que indica el último mensaje procesado por el servidor. Usa este índice para quitar los mensajes reconocidos 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 aumentar este índice en 1. En cada reanudación de sesión, asegúrate de que el índice se restablezca a 1 para el mensaje inicial transmitido con la nueva conexión.

  3. Controla las desconexiones correctamente:

    • 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 controlador más reciente.
    • Errores de la 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 la actualización de la sesión o el proceso de reconexión.

  4. Implementa la reconexión con la reproducción de mensajes: Cuando se produce una desconexión, crea una sesión nueva con client.aio.live.connect con el controlador 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 reconoció antes de la desconexión. El primer mensaje enviado en el búfer debe marcarse como índice 1 para la nueva conexión.

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 nativos se acumulan rápidamente (aproximadamente 25 tokens por segundo de audio).

Advertencia: La compresión de 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. Durante cada turno, la API factura todos los tokens de contexto, que abarcan el historial de conversaciones y 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 la VAD que proporciona Gemini.

Mientras usas la VAD de la API de Gemini Live, puedes configurar el modelo para que muestre eventos de VAD de forma explícita. Si habilitas explicit_vad_signal en tu configuración, puedes 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. Para ello, se transmiten 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 establecer de forma explícita 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}.

Para los modelos de audio nativos, como gemini-live-2.5-flash-native-audio, puedes mejorar la calidad de la transcripción para el reconocimiento de voz automático (ASR) multilingüe si proporcionas sugerencias de idioma en la configuración de tu sesión. Para obtener más información, consulta Habilita la transcripción de audio para la sesión.

Establece el código de idioma de 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']
  ),
)

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 ms y 40 ms) para minimizar la latencia.

Reproducción de muestras

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

En este JSON, se definen las funciones relevantes que se llaman en el ejemplo de asesor profesional. Para obtener 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 lo siguiente: