Migrer de l'API Gemini 2.5 Flash Live Native Audio vers Gemini 3.8 Live

Ce document décrit les modifications requises lors de la migration de l'API Gemini 2.5 Flash Live Native Audio vers Gemini 3.8 Live.

Modifications des appels de fonction

Le serveur audio natif de l'API Gemini 2.5 Flash Live permet les appels d'outils asynchrones. En revanche, Gemini 3.8 Live est compatible avec les appels de fonction asynchrones, avec les changements de comportement suivants :

• Gemini 3.8 Live permet de bloquer les appels de fonction lorsque la déclaration de fonction déclare behavior=BLOCKING dans la configuration. Si une nouvelle entrée est reçue pendant l'exécution de l'appel de fonction bloquant, le serveur de l'API Live annule l'appel de fonction en cours.

• Le comportement de l'option scheduling=interrupt de FunctionResponse a changé :

  Planification de FunctionResponse	Qui parle	Audio natif de l'API Gemini 2.5 Flash Live	Gemini 3.8 Live
  interrompre	modèle	Arrête immédiatement la réponse du modèle actif et lit la réponse de l'outil.	Arrête immédiatement la réponse du modèle actif et lit la réponse de l'outil.
  interrompre	utilisateur	Interrompt immédiatement ; lit la réponse de l'outil par-dessus l'utilisateur.	Attend que l'utilisateur ait terminé avant de lire la réponse de l'outil.

Limiter les balayages redondants et les nouvelles tentatives d'appel de fonction

Gemini 3.8 Live effectue parfois des appels de fonction redondants consécutifs au cours d'un même tour lorsqu'un outil ne renvoie aucun résultat. Cela peut inclure la répétition de différents paramètres, en balayant deux à cinq fois, avant de répondre. Ce comportement augmente le délai d'émission du premier audio (TTFA) et produit un discours de remplacement inexact.

Les appels de fonction redondants consécutifs sont dus au fait que Gemini 3.8 Live tente de résoudre les requêtes. Lorsqu'un outil renvoie une réponse non informative ou vide, telle que {"results": [], "total_available": 0} ou None, le modèle ne peut pas faire la distinction entre "définitivement épuisé", "fenêtre de requête trop étroite" ou "argument non valide". Le modèle tente d'élargir ou de modifier la requête pour améliorer les résultats, puis commence le balayage.

Appliquez les pratiques complémentaires suivantes :

• Renvoyer des réponses de fonction informatives : chaque réponse d'outil doit contenir des informations sur l'erreur ou les résultats, afin d'indiquer au modèle Gemini 3.8 Live comment procéder.

  Le tableau suivant décrit les cas, la manière dont le modèle doit répondre et un exemple de charge utile requise pour aider le modèle :

  Cas	Ce que le modèle doit faire	Contenu de la charge utile requis
  Requête valide qui ne renvoie aucun résultat. Il est inutile de réessayer.	Arrêtez la recherche, informez l'utilisateur et proposez-lui des alternatives.	status: 'no_results', retryable: false, et un message explicatif clair en langage naturel.
  Argument non valide ou inexistant (par exemple, "wrong provider").	Arrêtez la recherche et demandez à l'utilisateur de clarifier ou de confirmer.	status: 'invalid_argument', reason_code, retryable: false et valid_options list
  Requête valide avec une fenêtre vide. Une requête plus large est vraiment utile.	Effectuez une nouvelle tentative raisonnable.	status: 'no_results_in_range', retryable: true et retry_hint

  L'exemple suivant illustre une charge utile où search_appointment est appelé, mais où toutes les dates potentielles sont indisponibles. L'utilisateur s'attend à essayer un fournisseur au lieu de balayer les dates :

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

  L'exemple suivant montre comment gérer les cas où check_user_account ne renvoie aucune correspondance exacte. Le résultat attendu est de modifier la requête de recherche ou de redonner le contrôle à l'utilisateur au lieu de réessayer :

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

• Règle de nouvelle tentative pour les instructions système : complétez les réponses informatives par une contrainte explicite dans l'instruction système :

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

Échange de l'historique des sessions

Dans l'API Gemini 2.5 Flash Live Native Audio, send_client_content est utilisé pour configurer l'amorçage de l'historique avant le premier tour et pour ajouter un historique supplémentaire en milieu de session.

Dans Gemini 3.8 Live, si vous souhaitez utiliser la méthode send_client_content pour configurer l'amorçage de l'historique, définissez initial_history_in_client_content=True dans la section HistoryConfig du message de configuration. Après avoir reçu setup_complete. Vous pouvez ensuite appeler send_client_content de manière répétée pour créer un historique jusqu'au dernier message où turn_complete=True est défini.

Mises à jour des instructions système et des outils en cours de session

Dans l'API Gemini 2.5 Flash Live Native Audio, vous mettez à jour l'instruction système pendant une session en envoyant du contenu client avec le rôle system.

Dans Gemini 3.8 Live, appelez send_context_update dans le SDK Google Gen AI ou envoyez un message context_update via WebSockets. Il peut remplacer l'instruction système, la liste des outils ou les deux. Pour en savoir plus, consultez Mettre à jour les instructions système et les outils avec Gemini 3.8 Live.

Différences de comportement du modèle

Le tableau suivant décrit les différences de comportement des modèles pour l'audio, le multimode et la sortie entre l'API Gemini 2.5 Flash Live Native Audio et Gemini 3.8 Live :

Le code Python suivant montre comment définir media_resolution et 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:
    ...

Compatibilité avec les frameworks tiers

Les sections suivantes décrivent le fonctionnement des frameworks tiers avec Gemini 3.8 Live :

LiveKit

Le plug-in Google RealtimeModel de LiveKit est compatible avec Gemini 3.8 Live, mais les paramètres suivants ne sont pas compatibles avec le plug-in Google de LiveKit :

• thinking_level
• enable_affective_dialog
• proactivity

Nous vous recommandons d'être particulièrement prudent lorsque vous utilisez le plug-in Google de LiveKit, car il nécessite une adaptation minutieuse pour fonctionner avec Gemini 3.8 Live.

Pipecat

Pipecat est compatible avec Gemini 3.8 Live, avec les modifications suivantes :

• Configuration du raisonnement : supprimez le niveau de raisonnement, car il n'est pas compatible avec Gemini 3.8 Live.

• Pipecat connecte les points de terminaison Agent Platform à l'aide de GoogleVertexLLMService via le connecteur GeminiLiveLLMService.

Télémétrie de l'utilisation des jetons au niveau du réseau

Chaque tour de serveur renvoie un frame usage_metadata. Cela est cohérent entre l'API Gemini 2.5 Flash Live Native Audio et Gemini 3.8 Live. Les métadonnées d'utilisation sont plus catégorisées, comme les jetons mis en cache, les jetons d'utilisation d'outils, les jetons dans différentes modalités, etc.

Limites connues du modèle et mesures d'atténuation

Pour en savoir plus sur les limites connues et les solutions de contournement lors du développement d'applications avec Gemini 3.8 Live, consultez Limites connues.

Checklist de migration

Voici une checklist de migration client que vous pouvez utiliser pour migrer de l'API Gemini 2.5 Flash Live Native Audio vers Gemini 3.8 Live :

• Appel de fonction :

  • Réponses informatives des outils : refactorisez tous les gestionnaires d'outils pour qu'ils renvoient des codes d'état explicites, des indicateurs de nouvelle tentative et des explications en langage naturel. Ne renvoyez jamais de None brut ni de {} vide.

  • Règle d'instruction système : ajoutez des contraintes explicites interdisant les nouvelles tentatives d'outil silencieuses, exigeant la confirmation de l'utilisateur en cas d'échec d'argument et limitant le nombre d'appels d'outil consécutifs.

  • Correspondance de l'ID d'appel d'outil : assurez-vous que FunctionResponse transmet id=fc.id à chaque réponse de l'outil.

  • Modification du comportement de planification des fonctions : lorsque l'utilisateur parle, scheduling=interrupt passe à scheduling=when_idle pour offrir une expérience utilisateur plus fluide.

• Session : restreindre send_client_content : utilisez send_client_content pour définir l'historique initial en fournissant un HistoryConfig pertinent.

• Session : mettre à jour le contexte avec context_update : remplacez les mises à jour des instructions système en cours de session qui utilisent le rôle system par des appels send_context_update dans le SDK Google Gen AI ou des messages context_update via WebSockets.

• Raisonnement : supprimez les astuces de raisonnement au niveau de la requête : pour éviter les pertes audio, supprimez tout texte de requête qui tente d'appliquer des schémas de raisonnement par étapes ou des limites de jetons.