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 fonctions

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 modifications de comportement suivantes :

• 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 lors de l'exécution de l'appel de fonction de blocage, le serveur de l'API Live annule l'appel de fonction en cours.

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

  Planification FunctionResponse	Qui parle	Gemini 2.5 Flash Live API Native Audio	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 l'utilisateur et lit la réponse de l'outil.	Attend que l'utilisateur ait terminé avant de lire la réponse de l'outil.

Atténuer les balayages redondants et les réexécutions d'appels 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 paramètres variés, en balayant deux à cinq fois, avant de répondre. Ce comportement augmente le temps avant le premier son (TTFA) et produit un discours de remplacement inexact.

Les appels de fonction redondants et consécutifs sont dus à Gemini 3.8 Live qui 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 "permanent exhausted", "query window too narrow" ou "invalid argument". Le modèle tente d'élargir ou de varier la requête pour améliorer les résultats, et commence à balayer.

Appliquez les pratiques complémentaires suivantes :

• Renvoie des réponses de fonction informatives : chaque réponse d'outil doit contenir des informations sur l'erreur ou les résultats, afin de guider le modèle Gemini 3.8 Live sur la marche à suivre.

  Le tableau suivant décrit les cas, la façon dont le modèle doit répondre et l'exemple de charge utile requis pour aider le modèle :

  Cas	Ce que le modèle doit faire	Contenu requis de la charge utile
  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, "mauvais fournisseur").	Arrêtez la recherche et demandez à l'utilisateur de clarifier ou de confirmer.	status: 'invalid_argument', reason_code, retryable: false et valid_options
  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 montre un exemple de charge utile dans lequel search_appointment est appelé, mais 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 le 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ègles de réessai des instructions système : complétez les réponses informatives par une contrainte explicite dans les instructions 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 de l'historique supplémentaire en cours 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 à plusieurs reprises pour créer un historique jusqu'au dernier message où turn_complete=True est défini.

Différences de comportement des modèles

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

L'exemple de 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 comment les frameworks tiers fonctionnent 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 de la réflexion : supprimez le niveau de réflexion, car il n'est pas pris en charge par Gemini 3.8 Live.

• Pipecat se connecte aux points de terminaison de la plate-forme d'agent à l'aide de GoogleVertexLLMService sur le connecteur GeminiLiveLLMService.

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

Chaque tour de serveur renvoie un frame usage_metadata. Cette cohérence s'applique à l'ensemble des API Gemini 2.5 Flash Live Native Audio et Gemini 3.8 Live. Les métadonnées d'utilisation sont plus catégorisées (jeton mis en cache, jeton d'utilisation d'outil, jetons dans différentes modalités, etc.).

Limites et mesures d'atténuation connues des modèles

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

Checklist de migration

Vous trouverez ci-dessous une checklist de migration des clients que vous pouvez utiliser lorsque vous migrez 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 pouvant être réessayés et des explications en langage naturel. Ne renvoyez jamais de None nus ni de {} vides.

  • Règles relatives aux instructions système : ajoutez des contraintes explicites interdisant les nouvelles tentatives d'outil silencieuses, exigeant la confirmation de l'utilisateur en cas d'échec des arguments et limitant les appels d'outils consécutifs.

  • Correspondance des ID d'appel d'outil : assurez-vous que FunctionResponse transmet id=fc.id à chaque réponse d'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.

• Réflexion : supprimer les astuces de réflexion au niveau de la requête : pour éviter les pertes audio, supprimez tout le texte de requête qui tente d'appliquer des schémas de réflexion étape par étape ou des limites de jetons.