Gemini · Guardrails : permissions, revue et coût
Un agent capable de lire votre Drive, d'envoyer des e-mails en votre nom et d'appeler des APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → payantes est un employé junior qui a vos identifiants et aucun manager. Les guardrailsguardrailsRègles et contrôles qui maintiennent un système d'IA dans des limites sûres, légales et conformes à la marque, en bloquant les sorties et actions hors cadre.Voir la définition complète → jouent le rôle du manager. Cette leçon porte sur la mise en place des review gates, des limites de permissions et des contrôles de coût qui permettent à une automatisation basée sur Gemini de tourner sans devenir un risque.
Les trois modes de défaillance
Tout agent non supervisé échoue de l'une de ces trois façons :
- Mauvaise action, conséquence réelle. Il envoie un brouillon à un client, supprime les mauvaises lignes ou merge une pull request qui casse la production.
- Accès trop large. On lui a donné « Drive » alors qu'il avait besoin d'un seul dossier, si bien qu'une prompt injection ou un appel d'outil halluciné atteint tout.
- Coût qui s'emballe. Une boucle appelle Gemini Pro mille fois, ou une recherche grounded s'exécute sur chaque ligne d'une feuille de 50 000 lignes.
Les guardrails correspondent directement à ces trois cas : review gates pour les conséquences, scopes pour l'accès, budgets et routage de modèles pour le coût. Traitez-les comme trois contrôles distincts, car corriger l'un ne règle rien pour les autres.
Permissions et scopes : accordez le minimum
Commencez par restreindre ce que l'agent *peut* toucher, avant de vous préoccuper de ce qu'il *doit* faire.
Scopes OAuth dans Apps Script et Workspace
Quand vous construisez une automatisation dans Apps Script (la manière la plus courante de brancher Gemini sur Gmail, Sheets et Docs), les scopes sont déclarés, pas supposés. Fixez-les explicitement dans `appsscript.json` au lieu de laisser l'éditeur accorder automatiquement des scopes larges :
{
"oauthScopes": [
"https://www.googleapis.com/auth/spreadsheets.currentonly",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/script.external_request"
]
}Remarquez spreadsheets.currentonly (cette feuille uniquement, pas toutes les feuilles) et gmail.compose (crcrLe pourcentage de visiteurs ou de prospects qui réalisent une action attendue (achat, inscription, formulaire de contact), calculé en divisant les conversions par le nombre total d'opportunités.Voir la définition complète →éererLe rapport entre les interactions (likes, commentaires, partages) et le reach d'un contenu, utilisé pour mesurer la réaction de l'audience au regard du nombre de personnes touchées.Voir la définition complète → des brouillons, sans pouvoir envoyer). Cette seule différence entre gmail.compose et gmail.send sépare un agent qui *propose* un e-mail d'un agent qui l'*envoie*. Optez par défaut pour le scope le plus étroit et obligez un humain à franchir la ligne.
Comptes de service et Vertex AI
Côté Vertex AI, un agent (par exemple construit avec l'Agent Development Kit) s'exécute sous un compte de service. Appliquez la même discipline avec IAM :
- Donnez au compte de service
roles/aiplatform.user, pasOwner. - S'il lit dans BigQuery, accordez
roles/bigquery.dataViewersur le *dataset concerné*, pas sur le projet. - Ne donnez jamais à un agent autonomeagent autonomeLogiciel qui poursuit un objectif seul : il planifie, utilise des outils et agit avec une intervention humaine limitée.Voir la définition complète → un accès en écriture à la facturation, à IAM ou à la suppression de ressources.
Le principe : une identité par agent. Un compte de service par automatisation vous permet de lire l'audit log et de répondre à « qu'a fait *cet* agent » sans démêler des identifiants partagés.
Gems et applications connectées
Dans l'application Gemini grand public, l'équivalent du scope, ce sont les Apps connectées (Gmail, Drive, Maps, etc. ; on les appelait Extensions jusqu'en 2025) et ce qu'un Gem a le droit de consulter. Un Gem ne peut pas s'accorder l'accès à une app que vous n'avez pas connectée. Pour tout ce qui touche à des données sensibles, construisez l'automatisation dans Apps Script ou Vertex AI, où les scopes sont explicites, et non dans un Gem, où l'accès est large et porte sur tout le compte.
Ce que vous n'automatisez jamais sans supervision
Certaines actions doivent *toujours* attendre un humain, quel que soit le niveau de confiance du modèle. Gardez cette liste courte et sans exception :
- Envoyer une communication externe. E-mails, messages Chat, tout ce qu'un client voit.
- Modifier des données de façon irréversible. Suppressions, écrasements, changements de schémamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète →, paiements, remboursements.
- Du code qui part en production. Merge, déploiement ou push sur une branche protégée.
- Dépenser de l'argent au-delà d'un seuil par action (un appel d'API payant, une ressource cloud).
- Accorder un accès à qui ou quoi que ce soit.
Gemini Code Assist et la Gemini CLI vont déjà dans ce sens : la CLI vous montre la commande shell ou la modification de fichier proposée et attend votre confirmation avant de l'exécuter. Cette étape de confirmation n'est pas une friction à supprimer. C'est la review gate qui fait son travail. Quand vous construisez vos propres agents, reprenez ce modèle au lieu de le contourner.
Review gates humaines
Une review gate est un arrarrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →êt volontaire où l'agent produit une *proposition*, la conserve à un endroit visible et attend une approbation humaine explicite avant d'exécuter. Le travail de l'agent s'arrête à « brouillon rédigé ». Celui de la personne commence à « approuver ».
Le modèle « brouillon puis attente »
La review gate la plus propre dans Workspace, c'est le brouillon Gmail. L'agent rédige l'e-mail mais utilise le scope compose, donc le message arrive dans les Brouillons, pas dans la boîte du destinataire. L'humain relit et clique sur Envoyer. Aucune interface supplémentaire, et la review gate repose sur un outil que tout utilisateur connaît déjà.
Voici ce modèle de bout en bout : classer un e-mail entrant avec Gemini, puis créer une réponse en *brouillon* qu'un humain doit approuver.
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
REVIEW_PROMPT = """You are a support triage assistant.
Read the customer email and return JSON:
{"category": "...", "needs_human": true|false, "draft_reply": "..."}
Set needs_human=true for refunds, legal, or anything you are unsure about.
Never promise refunds or commitments in draft_reply."""
def triage(email_body: str) -> dict:
resp = client.models.generate_content(
model="gemini-flash-latest",
contents=[REVIEW_PROMPT, email_body],
config={"response_mime_type": "application/json"},
)
return resp.parsed
def handle(email_body: str):
result = triage(email_body)
# L'agent n'envoie JAMAIS. Il crée seulement un brouillon à relire.
create_gmail_draft(result["draft_reply"], flagged=result["needs_human"])
return resultDeux guardrails sont intégrés. On demande au modèle de signaler lui-même les remboursements et les incertitudes (needs_human), et le plafond d'action est un brouillon, pas un envoi. Même si le modèle se trompe, le pire cas est un *brouillon* non relu qui reste dans un dossier, pas un e-mail indésirable dans la boîte d'un client.
Routage selon la confiance
Tous les éléments ne demandent pas le même niveau de contrôle. Routez selon le risque :
- Exécution automatique pour les actions à faible enjeu et entièrement réversibles (ajouter un libellé à un e-mail, un tag dans l'agenda).
- File de revue pour les actions à enjeu moyen (un brouillon de réponse, une mise à jour de feuille proposée).
- Escalade des actions à fort enjeu vers une personne nommée, avec le contexte joint.
Laissez le modèle renvoyer son propre signal needs_human *et* appliquez des règles strictes dans le code. Ne laissez jamais le modèle décider seul si quelque chose est dangereux, car une prompt injection peut inverser ce flag. La règle au niveau du code (« category == refund déclenche toujours une escalade ») est le vrai guardrail ; l'auto-évaluation du modèle n'est qu'une commodité en plus.
Build agents with the Agent Development Kit
Maîtriser le coût
Le coût dérape sans bruit. L'agent fonctionne, le résultat paraît correct, et la facture arrive en fin de mois. Mettez les contrôles en place avant d'en avoir besoin.
Routez par défaut vers le modèle le moins cher
Le levier le plus important est le choix du modèle. Gemini Flash coûte une fraction de Gemini Pro par tokentokenUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → et reste assez rapide pour la classification, l'extraction, le routage et la synthèse. Réservez Pro au raisonnement vraiment difficile. Un bon réglage par défaut : chaque étape utilise Flash, et vous ne *promouvez* une étape vers Pro que si vous savez dire pourquoi.
def pick_model(task_complexity: str) -> str:
# Pas cher par défaut. Escalader uniquement pour le raisonnement difficile.
return "gemini-pro-latest" if task_complexity == "hard" else "gemini-flash-latest"Les alias -latest suivent la génération actuelle de Google (Gemini 3 au moment de la rédaction). En production, fixez plutôt une version précise à partir de la page des modèles, et notez les dates de dépréciation dans votre agenda. Un changement de modèle silencieux modifie à la fois la qualité de vos résultats et votre facture.
Réduisez ce que vous envoyez et stockez ce que vous pouvez réutiliser
- La taille du contexte, c'est du coût. Le long contexte est une fonctionnalité, pas une invitation à mettre tout le Drive dans chaque appel. Envoyez l'extrait pertinent, pas le corpus.
- Mettez en cache les préfixes répétés. Si tous les appels partagent un long system prompt fixe ou un même document, utilisez le context caching pour ne pas payer plein tarif les mêmes tokens à chaque fois.
- Utilisez le grounding à bon escient. Le grounding avec Google Search apporte de la valeur et du coût. Activez-le pour les étapes qui ont besoin de faits récents, désactivez-le pour les autres.
Plafonnez la boucle
Les agents bouclent. Une boucle de raisonnement sans plafond peut appeler le modèle des dizaines de fois pour une seule tâche. Fixez toujours un plafond strict d'itérations et un budget de tokens par exécution, et échouez en mode fermé quand vous l'atteignez :
MAX_STEPS = 6
def run_agent(task, step=0):
if step >= MAX_STEPS:
return escalate(task, reason="step_limit_reached")
# ... une étape de raisonnement/d'outil ...Surveillez la facture au niveau de la plateforme
Sur Vertex AI et Google Cloud, configurez un budget et des alertes budgétaires pour être prévenu (ou déclencher un plafond automatique) avant que la dépense franchisse un seuil. Une alerte de facturation est votre dernière ligne de défense quand un guardrail dans le code a été oublié. Pour l'usage par clé d'API depuis AI Studio, suivez la consommation dans la console et faites tourner les clés qui ont fuité. Les budgets n'arrêtent pas la dépense à eux seuls : associez-les aux plafonds dans le code décrits plus haut.
Vérification des acquis
1. Selon la leçon, pourquoi faut-il traiter les review gates, les scopes et les budgets comme trois contrôles distincts ?
2. Quelle est la différence pratique essentielle entre les scopes 'gmail.compose' et 'gmail.send', et pourquoi la leçon recommande-t-elle 'compose' par défaut ?
3. La leçon décrit un agent non supervisé comme « un employé junior qui a vos identifiants et aucun manager ». Quel est le sens de cette analogie ?
4. Sélectionnez TOUS les exemples du mode de défaillance « accès trop large » ou de la bonne façon de l'éviter.
Sélectionnez toutes les réponses correctes.
5. Sélectionnez TOUTES les affirmations qui reflètent le principe d'attribution des permissions minimales décrit dans la leçon.
Sélectionnez toutes les réponses correctes.
Mise en pratique : un reporting hebdomadaire avec review gate
Voici comment les trois contrôles se combinent dans une automatisation réaliste. Une automatisation hebdomadaire lit une feuille Sheets de ventes, rédige un e-mail de synthèse pour la direction et attend l'approbation.
- Scope : Apps Script avec
spreadsheets.currentonlyetgmail.compose. Elle peut lire cette feuille et créer un brouillon. Elle ne peut pas envoyer, ni toucher d'autres fichiers. - Coût : Flash pour la synthèse (Pro est démesuré pour « résume ce tableau »). Un appel par semaine, avec la feuille réduite au dernier trimestre, pas tout l'historique.
- Review gate : le résultat est un brouillon Gmail adressé à la direction. Une personne le lit le lundi matin et l'envoie, le modifie ou le supprime.
Aucune partie de ce dispositif ne peut envoyer un e-mail à qui que ce soit, dépenser de façon significative ou modifier des données sans un humain. C'est l'objectif : une automatisation dont la *pire défaillance réaliste* est un brouillon que quelqu'un supprime. Concevez chaque agent pour que son mode de défaillance soit inoffensif par construction, et non en espérant que le modèle se comporte bien.
Logging : le guardrail dont on n'a besoin qu'une fois
Journalisez chaque action de l'agent : l'entrée, le modèle et les tokens utilisés, l'action proposée et l'éventuelle approbation humaine. Quand quelque chose tourne mal (et cela finira par arriver), le log vous permet de savoir ce qui s'est passé et de prouver ce qui ne s'est pas passé. Dans Apps Script, écrivez dans une feuille de log dédiée ou via console.log vers Cloud Logging. Sur Vertex AI, utilisez les callbacks ADK pour capturer chaque appel d'outil. Une action que votre système ne sait pas expliquer est une action à laquelle vous ne pouvez pas vous fier.
Points clés
- Le scope avant le comportement. Accordez le scope OAuth ou le rôle IAM le plus étroit qui fonctionne (
gmail.composeet nongmail.send, un dataset et non le projet), et utilisez une identité par agent pour que l'audit log reste lisible. - Rendez le mode de défaillance inoffensif. Construisez les agents pour que le pire résultat réaliste soit un *brouillon* qu'un humain supprime. N'automatisez jamais sans supervision les envois, suppressions, paiements, déploiements ou attributions d'accès.
- Appliquez les review gates dans le code, pas dans le prompt. Laissez le modèle signaler le risque par commodité, mais placez les vraies règles « toujours escalader » dans votre logique de contrôle, là où une prompt injection ne peut pas les inverser.
- Flash par défaut, boucle plafonnée. Utilisez Gemini Flash sauf si une étape exige Pro, fixez les versions de modèle en production, mettez en cache le contexte répété, réduisez ce que vous envoyez et fixez une limite stricte d'itérations pour qu'aucune exécution ne s'emballe.
- Adossez le tout à des budgets plateforme et à des logs. Les alertes de facturation Cloud rattrapent ce que votre code laisse passer, et un log complet des actions vous permet ensuite de faire confiance à l'automatisation (ou de la révoquer).