Gemini · Guardrails: Berechtigungen, Review und Kosten

Ein Agent, der Ihr Drive lesen, in Ihrem Namen E-Mails senden und kostenpflichtige APIs aufrufen kann, ist ein Junior-Mitarbeiter mit Ihren Zugangsdaten und ohne Vorgesetzten. Die GuardrailsGuardrailsRegeln und Kontrollen, die ein KI-System in sicheren, rechtskonformen und markengerechten Grenzen halten und unerwünschte Ausgaben blockieren.Vollständige Definition ansehen → sind der Vorgesetzte. In dieser Lektion geht es darum, Review-Gates, Berechtigungsgrenzen und Kostenkontrollen aufzubauen, mit denen eine Gemini-basierte Automatisierung laufen kann, ohne zum Risiko zu werden.

Die drei Fehlermodi

Jeder unbeaufsichtigte Agent scheitert auf eine von drei Arten:

1. Falsche Aktion, reale Folgen. ErErDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → schickt einen Entwurf an einen Kunden, löscht die falschen Zeilen oder merged einen Pull Request, der die Produktion lahmlegt.
2. Zu weit gefasster Zugriff. Er hat „Drive“ erhalten, obwohl er nur einen Ordner brauchte, und so erreicht eine Prompt Injection oder ein halluzinierter Tool-Aufruf alles.
3. Ausufernde Kosten. Eine Schleife ruft Gemini Pro tausendmal auf, oder eine grounded Search läuft über jede Zeile eines Sheets mit 50.000 Zeilen.

Die Guardrails lassen sich sauber zuordnen: Review-Gates für die Folgen, Scopes für den Zugriff, Budgets und Model Routing für die Kosten. Behandeln Sie sie als drei getrennte Kontrollen, denn die Lösung für ein Problem hilft bei den anderen nicht.

Berechtigungen und Scopes: das Minimum vergeben

Schränken Sie zuerst ein, worauf der Agent zugreifen *kann*, bevor Sie sich darum kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →ümmern, was er tun *soll*.

OAuth-Scopes in Apps Script und Workspace

Wenn Sie eine Automatisierung in Apps Script bauen (der gängigste Weg, Gemini mit Gmail, Sheets und Docs zu verbinden), werden die Scopes deklariert, nicht vorausgesetzt. Legen Sie sie explizit in `appsscript.json` fest, statt den Editor automatisch weitreichende Scopes vergeben zu lassen:

{
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

Beachten Sie spreadsheets.currentonly (nur dieses eine Sheet, nicht alle Sheets) und gmail.compose (Entwürfe erstellen, kein Versand möglich). Dieser eine Unterschied zwischen gmail.compose und gmail.send trennt einen Agenten, der E-Mails *vorschlägt*, von einem, der sie *versendet*. Wählen Sie standardmäßig den engeren Scope und lassen Sie diese Grenze nur von einem Menschen überschreiten.

Service Accounts und Vertex AI

Auf der Seite von Vertex AI läuft ein Agent (zum Beispiel einer, der mit dem Agent Development Kit gebaut wurde) unter einem Service Account. Wenden Sie bei IAM dieselbe Disziplin an:

• Geben Sie dem Service Account roles/aiplatform.user, nicht Owner.
• Wenn er aus BigQuery liest, vergeben Sie roles/bigquery.dataViewer für das *konkrete Dataset*, nicht für das Projekt.
• Geben Sie einem autonomen Agenten nie Schreibzugriff auf Billing, IAM oder das Löschen von Ressourcen.

Das Prinzip lautet: eine Identität pro Agent. Mit einem Service Account pro Automatisierung können Sie das Audit-Log lesen und die Frage „Was hat *dieser* Agent getan?“ beantworten, ohne geteilte Zugangsdaten entwirren zu müssen.

Gems und verbundene Apps

In der Gemini-App für Endnutzer entspricht dem Scope die Frage, welche Apps verbunden sind (Gmail, Drive, Maps usw.; bis 2025 hießen sie Extensions) und worauf ein Gem zugreifen darf. Ein Gem kann sich keinen Zugriff auf eine App verschaffen, die Sie nicht verbunden haben. Für alles, was sensible Daten berührt, bauen Sie die Automatisierung in Apps Script oder Vertex AI, wo Scopes explizit sind, und nicht in einem Gem, dessen Zugriff weit gefasst ist und für das ganze Konto gilt.

Was Sie nie unbeaufsichtigt automatisieren

Manche Aktionen sollten *immer* für einen Menschen anhalten, egal wie sicher sich das Modell ist. Halten Sie diese Liste kurz und absolut:

• Externe Kommunikation versenden. E-Mails, Chat-Nachrichten, alles, was ein Kunde sieht.
• Irreversible Datenänderungen. Löschen, Überschreiben, SchemaSchemaEin Schema ist der formale Bauplan, der festlegt, wie Daten in einer Datenbank, einer Datei oder einer Nachricht strukturiert, benannt, typisiert und miteinander verknüpft sind.Vollständige Definition ansehen →änderungen, Zahlungen, Erstattungen.
• Code, der ausgeliefert wird. Mergen, Deployen oder Pushen auf einen geschützten Branch.
• Geld ausgeben oberhalb einer Schwelle pro Aktion (ein kostenpflichtiger APIAPIApplication Programming Interface: eine standardisierte Schnittstelle, über die Anwendungen kommunizieren und Daten austauschen, ohne die interne Funktionsweise der jeweils anderen zu kennen.Vollständige Definition ansehen →-Aufruf, eine Cloud-Ressource).
• Zugriff gewähren, egal wem oder was.

Gemini Code Assist und die Gemini CLI gehen bereits in diese Richtung: Die CLI zeigt Ihnen einen vorgeschlagenen Shell-Befehl oder eine Dateiänderung und wartet auf Bestätigung, bevor sie etwas ausführt. Dieser Bestätigungsschritt ist keine Reibung, die man beseitigen sollte. Hier macht das Review-Gate seine Arbeit. Wenn Sie eigene Agenten bauen, übernehmen Sie dieses Muster, statt es zu umgehen.

Menschliche Review-Gates

Ein Review-Gate ist ein bewusster Halt, an dem der Agent einen *Vorschlag* erstellt, ihn sichtbar ablegt und vor der Ausführung auf die ausdrückliche Freigabe durch einen Menschen wartet. Die Aufgabe des Agenten endet bei „entworfen“. Die Aufgabe eines Menschen beginnt bei „freigeben“.

Das Draft-and-Wait-Muster

Das sauberste Gate in Workspace ist der Gmail-Entwurf. Der Agent schreibt die E-Mail, nutzt aber den compose-Scope, sodass die Nachricht in den Entwürfen landet und nicht im Posteingang des Empfängers. Der Mensch prüft sie und klickt auf Senden. Es braucht keine zusätzliche Oberfläche, und das Gate ist ein Werkzeug, das jeder Nutzer bereits kennt.

Hier das Muster von Anfang bis Ende: eine eingehende E-Mail mit Gemini klassifizieren und dann einen *Entwurf* als Antwort erstellen, den ein Mensch freigeben muss.

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)
    # Der Agent sendet NIE. Er erstellt nur einen Entwurf zur Prüfung.
    create_gmail_draft(result["draft_reply"], flagged=result["needs_human"])
    return result

Zwei Guardrails sind eingebaut. Das Modell wird angewiesen, Erstattungen und Unsicherheit selbst zu markieren (needs_human), und die Obergrenze der Aktion ist ein Entwurf, kein Versand. Selbst wenn das Modell falsch urteilt, ist der schlimmste Fall ein ungeprüfter *Entwurf* in einem Ordner, keine unerwünschte E-Mail im Posteingang eines Kunden.

Routing nach Konfidenz

Nicht jeder Vorgang braucht dieselbe Prüfung. Routen Sie nach Risiko:

• Automatisch ausführen bei Aktionen mit geringem Risiko, die vollständig umkehrbar sind (eine E-Mail labeln, einen Kalender-Tag hinzufügen).
• Zur Prüfung einreihen bei mittlerem Risiko (ein Antwortentwurf, eine vorgeschlagene Aktualisierung im Spreadsheet).
• Eskalieren bei hohem Risiko, an eine namentlich benannte Person mit beigefügtem Kontext.

Lassen Sie das Modell sein eigenes needs_human-Signal zurückgeben, *und* setzen Sie harte Regeln im Code durch. Überlassen Sie die Entscheidung, ob etwas gefährlich ist, nie allein dem Modell, denn eine Prompt Injection kann dieses Flag umdrehen. Die Regel auf Code-Ebene („category == refund eskaliert immer“) ist der eigentliche Guardrail; die Selbsteinschätzung des Modells ist eine Bequemlichkeit obendrauf.

Kosten im Griff behalten

Kosten laufen leise aus dem Ruder. Der Agent funktioniert, der Output sieht gut aus, und die Rechnung kommt am Monatsende. Bauen Sie die Kontrollen, bevor Sie sie brauchen.

Standardmäßig an das günstigere Modell routen

Der größte Hebel ist die Wahl des Modells. Gemini Flash kostet pro TokenTokenEin Token ist die grundlegende Texteinheit, die Sprachmodelle verarbeiten, oft ein Wortfragment, ein ganzes Wort oder ein Satzzeichen und nicht ein einzelnes Zeichen.Vollständige Definition ansehen → einen Bruchteil von Gemini Pro und ist schnell genug für Klassifizierung, Extraktion, Routing und Zusammenfassungen. Behalten Sie Pro für wirklich schwieriges Reasoning vor. Ein guter Standard: Jeder Schritt nutzt Flash, und Sie *stufen* einen Schritt nur dann auf Pro *hoch*, wenn Sie den Grund benennen können.

def pick_model(task_complexity: str) -> str:
    # Standardmäßig günstig. Nur bei schwierigem Reasoning eskalieren.
    return "gemini-pro-latest" if task_complexity == "hard" else "gemini-flash-latest"

Die -latest-Aliase folgen Googles aktueller Generation (zum Zeitpunkt des Schreibens Gemini 3). In der Produktion legen Sie stattdessen eine bestimmte Version von der Modellseite fest und tragen die Deprecation-Termine in Ihren Kalender ein. Ein unbemerkter Modellwechsel verändert die Qualität Ihres Outputs und Ihre Rechnung.

Kürzen, was Sie senden, und speichern, was sich wiederverwenden lässt

• Kontextgröße ist Kosten. Langer Kontext ist ein Feature, keine Aufforderung, bei jedem Aufruf das ganze Drive mitzuschicken. Senden Sie den relevanten Ausschnitt, nicht den gesamten Bestand.
• Wiederkehrende Präfixe cachen. Wenn alle Aufrufe denselben großen, festen System-Prompt oder dasselbe Dokument enthalten, nutzen Sie Context Caching, damit Ihnen dieselben Tokens nicht immer wieder zum vollen Preis berechnet werden.
• Gezielt grounden. Grounding mit der Google-Suche bringt Mehrwert und kostet Geld. Aktivieren Sie es für Schritte, die aktuelle Fakten brauchen, und lassen Sie es bei den übrigen aus.

Die Schleife begrenzen

Agenten laufen in Schleifen. Eine Reasoning-Schleife ohne Obergrenze kann das Modell für eine einzige Aufgabe Dutzende Male aufrufen. Setzen Sie immer eine harte Obergrenze für Iterationen und ein Token-Budget pro Durchlauf, und brechen Sie sicher ab (fail closed), sobald sie erreicht ist:

MAX_STEPS = 6

def run_agent(task, step=0):
    if step >= MAX_STEPS:
        return escalate(task, reason="step_limit_reached")
    # ... ein Reasoning-/Tool-Schritt ...

Die Rechnung auf Plattformebene im Blick behalten

Richten Sie auf Vertex AI und Google Cloud ein Budget und Budgetbenachrichtigungen ein, damit Sie benachrichtigt werden (oder eine automatische Obergrenze auslösen), bevor die Ausgaben eine Schwelle überschreiten. Ein Billing-Alert ist Ihre letzte Verteidigungslinie, wenn ein Guardrail im Code versagt. Bei API-Key-Nutzung über AI Studio überwachen Sie die Nutzung in der Konsole und rotieren Keys, die nach außen gelangt sind. Budgets stoppen Ausgaben nicht von selbst, kombinieren Sie sie also mit den oben beschriebenen Obergrenzen im Code.

Alles zusammen: ein wöchentlicher Report mit Review-Gate

So greifen die drei Kontrollen in einer realistischen Automatisierung ineinander. Eine wöchentliche Automatisierung liest ein Sales-Sheet, entwirft eine Zusammenfassung per E-Mail an die Geschäftsleitung und wartet auf Freigabe.

• Scope: Apps Script mit spreadsheets.currentonly und gmail.compose. Sie kann dieses eine Sheet lesen und einen Entwurf erstellen. Sie kann nicht senden und keine anderen Dateien anfassen.
• Kosten: Flash für die Zusammenfassung (Pro ist für „Fasse diese Tabelle zusammen“ überdimensioniert). Ein Aufruf pro Woche, das Sheet auf das letzte Quartal gekürzt statt der gesamten Historie.
• Review-Gate: Der Output ist ein Gmail-Entwurf an die Geschäftsleitung. Eine Person liest ihn am Montagmorgen und sendet, bearbeitet oder verwirft ihn.

Kein Teil davon kann ohne einen Menschen jemandem eine E-Mail schicken, nennenswert Geld ausgeben oder Daten ändern. Genau das ist das Ziel: eine Automatisierung, bei der der *schlimmste realistische Fehler* ein Entwurf ist, den jemand löscht. Gestalten Sie jeden Agenten so, dass sein Fehlermodus konstruktionsbedingt harmlos ist, statt darauf zu hoffen, dass sich das Modell richtig verhält.

Logging: der Guardrail, den Sie nur einmal brauchen

Loggen Sie jede Aktion des Agenten: den Input, das Modell und die verbrauchten Tokens, die vorgeschlagene Aktion und ob ein Mensch sie freigegeben hat. Wenn etwas schiefgeht (und irgendwann wird etwas schiefgehen), finden Sie über das Log heraus, was passiert ist, und belegen, was nicht passiert ist. In Apps Script schreiben Sie in ein eigenes Log-Sheet oder per console.log in Cloud Logging. Auf Vertex AI nutzen Sie ADK-Callbacks, um jeden Tool-Aufruf zu erfassen. Einer Aktion, die Ihr System nicht erklären kann, können Sie nicht vertrauen.

Das Wichtigste in Kürze

• Scope vor Verhalten. Vergeben Sie den engsten OAuth-Scope oder die engste IAM-Rolle, die funktioniert (gmail.compose statt gmail.send, ein Dataset statt des Projekts), und nutzen Sie eine Identität pro Agent, damit das Audit-Log lesbar bleibt.
• Machen Sie den Fehlermodus harmlos. Bauen Sie Agenten so, dass das schlimmste realistische Ergebnis ein *Entwurf* ist, den ein Mensch löscht. Automatisieren Sie Versand, Löschvorgänge, Zahlungen, Deployments oder Zugriffsvergaben nie unbeaufsichtigt.
• Gates im Code durchsetzen, nicht im Prompt. Lassen Sie das Modell Risiken als Bequemlichkeit markieren, aber verankern Sie die eigentlichen „immer eskalieren“-Regeln in Ihrem Kontrollfluss, wo eine Prompt Injection sie nicht umdrehen kann.
• Standardmäßig Flash, Schleife begrenzen. Nutzen Sie Gemini Flash, solange ein Schritt nicht Pro braucht, legen Sie Modellversionen in der Produktion fest, cachen Sie wiederkehrenden Kontext, kürzen Sie, was Sie senden, und setzen Sie ein hartes Iterationslimit, damit kein Durchlauf ausufert.
• Mit Plattform-Budgets und Logs absichern. Cloud-Billing-Alerts fangen ab, was Ihr Code übersieht, und ein vollständiges Aktions-Log ermöglicht es Ihnen später, der Automatisierung zu vertrauen (oder sie zu widerrufen).