Guide du développeur pour Gemini 3.5 Flash

Gemini 3.5 Flash est un modèle puissant, rapide et économique de la famille Gemini 3. Conçu pour offrir des capacités agentiques quasi professionnelles sans compromettre les performances ni la valeur, le modèle est désormais en disponibilité générale (GA) pour les développeurs qui utilisent l'API Gemini et pour les entreprises qui utilisent Gemini Enterprise Agent Platform.

Ce document présente les nouveautés de Gemini 2.5 Flash, explique quand l'utiliser et comment migrer vers Gemini 2.5 Flash, et fournit un guide de démarrage rapide pour l'utiliser.

Comment s'intègre-t-il à la famille Gemini ?

Le tableau suivant compare certaines des spécifications de Flash 3.5, Flash 3.1 Pro et Flash 3.1 Flash-Lite :

Consultez la page Modèle Flash 3.5 pour obtenir la liste complète des fonctionnalités, outils et options de consommation compatibles.

Répartition des cas d'utilisation

La stratégie recommandée pour les workflows agentifs utilise une approche par niveaux pour optimiser la qualité, la vitesse et le coût :

• Gemini Pro : à réserver aux tâches cognitives très complexes nécessitant un raisonnement approfondi, comme la planification initiale des racines, la résolution de problèmes complexes, le codage difficile et la prise de décisions critiques.
• Gemini Flash : utilisez-le comme principal "cheval de trait" pour les tâches d'exécution, l'appel d'outils et les étapes de raisonnement intermédiaires. Il offre le meilleur équilibre entre performances et efficacité.
• Gemini Flash-Lite : déployez-le pour les tâches de prétraitement et structurelles à fort volume et à faible latence où la vitesse et le coût sont primordiaux, comme le routage des intentions, l'extraction de données, le taggage et la classification.

Nouveautés de Gemini 3.5 Flash

Gemini 3.5 Flash apporte les modifications et améliorations suivantes à la gamme de modèles Gemini :

• Performances de pointe constantes : notre modèle Flash le plus intelligent, optimisé pour les tâches agentiques et de codage à grande échelle.
• Exécution agentique : déploiement de sous-agents, résolution de problèmes et boucles agentiques rapides à grande échelle.
• Codage amélioré : cycles de codage itératifs, exploration rapide et prototypage pour tester d'autres chemins et explorer dynamiquement des solutions.
• Horizon long : workflows multi-étapes et utilisation d'outils à grande échelle.
• Préservation de la pensée : le modèle conserve automatiquement le raisonnement intermédiaire dans les conversations multitours. Aucune modification de l'API n'est nécessaire.
• Nouveau niveau de réflexion par défaut : le niveau de réflexion par défaut est passé de HIGH à MEDIUM.
• Amélioration de la réflexion LOW : le niveau de réflexion faible a été considérablement amélioré pour les tâches de codage et agentiques qui nécessitent moins d'étapes, offrant une qualité élevée à un coût et une latence réduits.

Pour en savoir plus, consultez la section Principaux changements.

Guide de démarrage rapide

Avant de commencer, vous devez vous authentifier auprès d'Agent Platform à l'aide des Identifiants par défaut de l'application (ADC) ou d'une clé API. Pour en savoir plus, consultez Premiers pas avec Gemini Enterprise Agent Platform.

Dans les blocs de code suivants, remplacez PROJECT_ID par l'ID de votre projet.

Installation

Assurez-vous d'utiliser la dernière version du SDK google-genai :

pip install --upgrade google-genai

Demande de base

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Principales modifications

Cette section décrit plus en détail les modifications suivantes apportées à Gemini 3.5 Flash :

• Nouveau niveau de réflexion par défaut (MEDIUM)
• Préservation des pensées
• Obsolète : paramètres d'échantillonnage
• Obsolète : thinking_budget

Nouveau niveau de réflexion par défaut

Le niveau de réflexion par défaut des modèles Gemini 3 est désormais MEDIUM, alors qu'il était de HIGH dans la version Preview de Gemini 3 Flash. Le niveau de réflexion MEDIUM donne d'excellents résultats pour un large éventail de tâches, tout en étant plus rapide et plus économique.

Voici les niveaux de réflexion acceptés :

• MINIMAL : correspond au paramètre "Sans réflexion" pour la plupart des requêtes. Le modèle peut réfléchir de manière très minimale pour les tâches complexes comme le codage. Réduit la latence pour les applications de chat ou à haut débit.
• LOW : raisonnement léger pour la plupart des tâches, avec une vitesse élevée et un coût réduit.
• MEDIUM : (par défaut) paramètre "Équilibré" pour la plupart des tâches nécessitant un raisonnement.
• HIGH : maximise le raisonnement pour optimiser les performances des tâches. Le modèle peut mettre plus de temps que le paramètre MEDIUM pour générer le premier jeton, mais le résultat sera plus complet.

Par exemple, utilisez HIGH pour les énigmes logiques, les problèmes écrits de mathématiques ou les scénarios complexes où le modèle doit raisonner en plusieurs étapes :

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

Le paramètre thinking_level est facultatif. Si aucune valeur n'est spécifiée, 3.5 Flash utilisera son paramètre par défaut (MEDIUM).

Préservation des pensées

Le modèle conserve automatiquement le raisonnement intermédiaire dans les conversations multitours. Lorsqu'il est présent dans l'historique des conversations, le contexte de raisonnement est automatiquement reporté, ce qui améliore les performances pour les tâches complexes en plusieurs étapes, comme le débogage itératif et le refactoring de code. Aucune modification de l'API n'est nécessaire.

Les réflexions des tours précédents sont désormais conservées par défaut. Le service n'efface plus l'historique des réflexions du contexte de la conversation avant de le transmettre au modèle.

Lorsque vous envoyez l'historique des conversations, soyez cohérent avec les tours précédents : incluez le contexte complet (réflexions, appels de fonction, réponses) ou omettez-le entièrement. Un contexte partiel peut dégrader les performances du modèle.

Obsolète : paramètres d'échantillonnage

Les paramètres d'échantillonnage suivants ne sont plus recommandés pour les modèles Gemini 3 :

• temperature
• top_p
• top_k

Le modèle gère son propre échantillonnage pour obtenir des résultats optimaux. Supprimez ces paramètres de toutes les requêtes. Pour assurer le déterminisme, définissez une instruction système avec des règles explicites pour votre cas d'utilisation spécifique.

Obsolète : thinking_budget

Le paramètre numérique brut thinking_budget n'est plus compatible avec tous les modèles Gemini 3. Utilisez plutôt l'enum de chaîne thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Bonnes pratiques

Cette section décrit les bonnes pratiques suivantes pour l'utilisation de 3.5 Flash :

• Utiliser une correspondance stricte des réponses pour les appels de fonction
• Inclure du contenu multimodal dans la réponse de la fonction parts
• Utiliser des instructions intégrées dans la réponse de la fonction
• Réduire les appels d'outils inutiles

Utiliser une correspondance stricte des réponses pour les appels de fonction

Les réponses non concordantes entraînent généralement des réponses vides avec finish_reason: STOP. Respectez toujours les conventions suivantes :

• Inclure id : chaque FunctionResponse doit inclure le id du FunctionCall correspondant.
• Correspondance de name : le name de la réponse doit correspondre au name de l'appel.
• Nombre de correspondances : renvoie exactement un FunctionResponse pour chaque FunctionCall reçu.

Le code suivant est un exemple d'appel de fonction correct :

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Inclure du contenu multimodal dans la réponse de la fonction parts

Fournir des images en dehors de la réponse de la fonction peut entraîner un comportement inattendu du modèle, tel qu'une fuite de pensée, et une qualité inférieure. Suivez la recommandation incluse dans Présentation de l'appel de fonction et incluez du contenu multimodal dans les parties de réponse de la fonction que vous envoyez au modèle. Le modèle peut traiter ce contenu multimodal lors de son prochain tour pour produire une réponse plus pertinente.

Exemple :

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Utiliser des instructions intégrées dans la réponse de la fonction

Fournir des instructions sur la plate-forme en même temps que les réponses aux fonctions en tant que parts ultérieurs peut entraîner un comportement inattendu du modèle, tel qu'une fuite de pensée, et une qualité inférieure. Au lieu de cela, ajoutez-le à la fin du texte de réponse de la fonction, séparé par deux sauts de ligne.

Exemple :

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Réduire les appels d'outils inutiles

Si vous constatez une utilisation excessive des appels d'outils, deux techniques peuvent vous aider à les minimiser :

1. Réduisez le niveau de réflexion : les niveaux de réflexion plus élevés encouragent le modèle à utiliser davantage d'outils pour explorer et vérifier. En abaissant le niveau, vous pouvez réduire les appels d'outils.

2. Ajoutez une instruction système : si la surutilisation persiste après avoir ajusté le niveau de réflexion, envisagez d'utiliser une requête qui limite l'utilisation des outils. Exemple :

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Migrer de 3.5 Flash ou 3.1 Pro vers 3.6 Flash

Pour migrer vers 3.6 Flash depuis 3.5 Flash ou 3.1 Pro, procédez comme suit :

1. Mettez à jour l'ID du modèle : remplacez la chaîne du modèle dans vos appels d'API par gemini-3.6-flash.
2. Adaptez votre code aux nouvelles règles de l'API de la famille Gemini 3 : Gemini 3.6 Flash applique strictement les règles de paramètres et les conventions d'API établies pour la famille Gemini 3 :
   • Supprimer la température, le top-K et le top-P : supprimez ces paramètres personnalisés de votre charge utile. Bien qu'aucune erreur ne soit générée, le modèle les ignorera complètement. Utilisez plutôt le paramètre thinking_level ou les sorties structurées json_schema pour contrôler le déterminisme de la sortie.
   • Supprimez les pénalités de fréquence et de présence : supprimez toutes les configurations personnalisées pour les pénalités de fréquence ou de présence afin d'éviter que vos appels d'API génèrent des erreurs d'exécution.
   • Assurez-vous que votre intégration de chat ne tente pas de préremplir le modèle : Examinez vos tableaux d'historique des messages pour vous assurer que la charge utile de votre API ne se termine pas par un tour d'utilisateur ou de modèle vide. Si le dernier objet de votre tableau d'historique est un rôle "model" (API GenerateContent) ou un type "model_output" (API Interactions), restructurer la séquence pour éviter de déclencher une erreur de validation stricte.
   • Utilisez thinking_level : supprimez les instances du paramètre thinking_budget obsolète et utilisez thinking_level à la place.
   • Appliquer des conventions strictes pour l'appel de fonctions : le FunctionResponse doit correspondre exactement au id, au name et au nombre d'exécutions du FunctionCall précédent. Si vous devez ajouter des instructions intégrées, placez-les directement dans le texte de réponse de la fonction, séparées par deux sauts de ligne (\n\n).
3. Tenez compte des changements de workflow :
   • Si votre application repose sur des boucles de conversation multitours, testez vos workflows pour vous assurer que la nouvelle concision des étapes du modèle ne déclenche pas de sorties prématurées.
   • Si vous créez des agents de script de base ou de frontend, surveillez les appels execute_code exploratoires inutiles en raison du nouveau biais du modèle en faveur de l'inspection programmatique initiale.

Solutions de contournement pour les exigences concernant le texte avant l'outil

Si votre requête exige que le modèle génère du texte structuré (XLM, YAML, JSON, etc.) (par exemple, <UPDATE>...</UPDATE>) immédiatement avant d'effectuer un appel d'outil, il est possible que l'appel d'outil échoue parfois et qu'une erreur Malformed_Function_Call s'affiche. Pour résoudre ce problème, vous pouvez utiliser l'une des solutions suivantes :

• (Recommandé) Demandez au modèle de placer ses notes avant l'outil dans un appel de fonction update() dédié au lieu de texte brut. Consultez la section suivante pour obtenir des instructions d'implémentation détaillées.
• Demandez au modèle d'écrire des notes sous forme d'en-têtes Markdown (par exemple, # UPDATE, ## PLAN) au lieu de texte structuré.
• Ne demandez pas au modèle de générer du texte avant les appels d'outils.

Solution recommandée : inclure les notes de travail dans un appel de fonction dédié

Au lieu de l'instruction d'origine :

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Utilisez cette instruction mise à jour :

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Mettez à jour toutes les références à l'ancien format XML <UPDATE> dans la demande du client. Ajoutez ensuite la déclaration de fonction correspondante pour la fonction de mise à jour :

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

Le modèle effectue deux appels au cours de la même étape : l'appel update() qui remplace le code XML structuré et l'appel de fonction qu'il souhaite effectuer.

Autres ressources

• Page du modèle Gemini 3.5 Flash
• Notebook d'introduction