Guardrails: Berechtigungen, Review und Kosten

# 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. Guardrails sind der Vorgesetzte. In dieser Lektion geht es darum, die Review-Gates, Berechtigungsgrenzen und Kostenkontrollen zu bauen, mit denen eine Gemini-Automatisierung laufen kann, ohne zum Risiko zu werden.

Die drei Failure Modes

Jeder unbeaufsichtigte Agent scheitert auf eine von drei Arten:

1. Falsche Aktion, echte Folge. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → schickt einen Draft an einen Kunden, löscht die falschen Zeilen oder merged einen Pull Request, der die Produktion zerlegt.

2. Zu weit gefasster Zugriff. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → hat „Drive“ bekommen, obwohl ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → einen Ordner brauchte, also erreicht eine Prompt Injection oder ein halluzinierter Tool Call alles.

3. Kosten außer Kontrolle. Ein Loop ruft Gemini Pro tausendmal auf, oder eine grounded Search läuft über jede Zeile eines Sheets mit 50.000 Zeilen.

Guardrails ordnen sich dem sauber zu: Review-Gates gegen Folgen, Scopes gegen Zugriff, Budgets und Model Routing gegen Kosten. Behandeln Sie sie als drei getrennte Kontrollen, denn die Lösung für eines bringt für die anderen nichts.

Berechtigungen und Scopes: das Minimum vergeben

Beginnen Sie damit einzugrenzen, was der Agent überhaupt anfassen *kann*, bevor Sie sich darum kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →ümmern, was ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → tun *sollte*.

OAuth-Scopes in Apps Script und Workspace

Wenn Sie eine Automatisierung in Apps Script bauen (der häufigste Weg, Gemini mit Gmail, Sheets und Docs zu verdrahten), werden die Scopes deklariert, nicht angenommen. Pinnen Sie sie explizit in appsscript.json, statt den Editor automatisch weit gefasste 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 (dieses eine Sheet, nicht alle Sheets) und gmail.compose (Drafts erstellen, kein Senden möglich). Dieser eine Unterschied zwischen gmail.compose und gmail.send ist die Grenze zwischen einem Agent, der E-Mails *vorschlägt*, und einem, der sie *sendet*. Nehmen Sie standardmäßig den engeren Scope und zwingen Sie einen Menschen, die Grenze zu überschreiten.

Service Accounts und Vertex AI

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

• Geben Sie dem Service Account roles/aiplatform.user, nicht Owner.
• Wenn ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → aus BigQuery liest, vergeben Sie roles/bigquery.dataViewer auf das *spezifische Dataset*, nicht auf das Projekt.
• Geben Sie einem autonomen Agent niemals Schreibzugriff auf Billing, IAM oder das Löschen von Ressourcen.

Das Prinzip ist: eine Identität pro Agent. Ein Service Account pro Automatisierung bedeutet, dass Sie das Audit Log lesen und die Frage „was hat *dieser* Agent getan“ beantworten kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, ohne geteilte Zugangsdaten entwirren zu müssen.

Gems und Extensions

In der Consumer-Gemini-App ist das Äquivalent zum Scope, welche Extensions aktiviert sind (Gmail, Drive, Maps und so weiter) und worauf ein Gem zugreifen darf. Ein Gem kann sich nicht selbst Zugriff auf einen Connector geben, den Sie nicht eingeschaltet 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, wo der Zugriff breit und kontoweit ist.

Was Sie nie unbeaufsichtigt automatisieren

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

• Externe Kommunikation senden. E-Mail, Chat-Nachrichten, alles, was ein Kunde sieht.
• Irreversible Datenänderungen. Löschungen, Überschreibungen, SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen →änderungen, Zahlungen, Rückerstattungen.
• Code, der ausgeliefert wird. Merging, Deployment oder Push auf einen geschützten Branch.
• Geld ausgeben über einer Schwelle pro Aktion (ein kostenpflichtiger APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → Call, eine Cloud-Ressource).
• Zugriff vergeben an irgendwen oder irgendwas.

Gemini Code Assist und die Gemini CLI gehen schon in diese Richtung: Die CLI zeigt Ihnen einen vorgeschlagenen Shell-Befehl oder eine Dateiänderung und wartet auf Bestätigung, bevor sie ausführt. Dieser Bestätigungsschritt ist keine Reibung, die man entfernt. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → ist das Review-Gate, das seine Arbeit tut. Wenn Sie eigene Agents bauen, kopieren Sie dieses Muster, statt es zu umgehen.

Review-Gates durch Menschen

Ein Review-Gate ist ein bewusster Stopp, an dem der Agent einen *Vorschlag* erzeugt, ihn sichtbar irgendwo ablegt und auf explizite menschliche Freigabe wartet, bevor ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → ausführt. Die Aufgabe des Agents endet bei „gedraftet“. Die Aufgabe eines Menschen beginnt bei „freigeben“.

Das Draft-and-Wait-Muster

Das saubere Gate in Workspace ist der Gmail-Draft. Der Agent schreibt die E-Mail, nutzt aber den Compose-Scope, sodass die Nachricht in den Drafts landet, nicht im Postfach des Empfängers. Der Mensch prüft und klickt auf Senden. Kein zusätzliches UI nötig, und das Gate ist ein Werkzeug, das jeder Nutzer schon kennt.

Hier ist das Muster von Anfang bis Ende: eine eingehende E-Mail mit Gemini klassifizieren und dann eine *Draft*-Antwort erstellen, die 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-2.5-flash",
        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 Draft zur Prüfung.
    create_gmail_draft(result["draft_reply"], flagged=result["needs_human"])
    return result

Zwei Guardrails sind fest eingebaut. Dem Modell wird gesagt, Rückerstattungen und Unsicherheit selbst zu markieren (needs_human), und die Obergrenze der Aktion ist ein Draft, kein Senden. Selbst wenn das Modell falsch urteilt, ist der schlimmste Fall ein ungeprüfter *Draft* in einem Ordner, keine unerwünschte E-Mail im Postfach eines Kunden.

Routing nach Confidence

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

• Automatisch ausführen bei geringen, vollständig reversiblen Aktionen (eine E-Mail labeln, einen Kalender-Tag setzen).
• Zur Prüfung einreihen bei mittlerem Risiko (eine Draft-Antwort, ein vorgeschlagenes Spreadsheet-Update).
• Eskalieren bei hohem Risiko an eine namentlich benannte Person, mit Kontext dabei.

Lassen Sie das Modell sein eigenes needs_human-Signal zurückgeben *und* erzwingen Sie harte Regeln im Code. Vertrauen Sie nie dem Modell allein bei der Entscheidung, ob etwas gefährlich ist, denn eine Prompt Injection kann dieses Flag umdrehen. Die Regel auf Code-Ebene („category == refund eskaliert immer“) ist das echte Guardrail; die Selbsteinschätzung des Modells ist Komfort 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 auf das günstigere Modell routen

Der größte einzelne Hebel ist die Modellwahl. Gemini Flash kostet pro TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → einen Bruchteil von Gemini Pro und ist schnell genug für Klassifikation, Extraktion, Routing und Zusammenfassung. Reservieren Sie Pro für wirklich schweres Reasoning. Ein guter Default: jeder Schritt nutzt Flash, und Sie *befördern* einen Schritt nur dann zu Pro, wenn Sie begründen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, warum.

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

Reduzieren, was Sie senden, und speichern, was wiederverwendbar ist

• Kontextgröße ist Kosten. Langer Kontext ist ein Feature, keine Aufforderung, das gesamte Drive in jeden Call zu stopfen. Senden Sie den relevanten Abschnitt, nicht den Korpus.
• Wiederkehrende Prefixes cachen. Wenn jeder Call einen großen festen System-Prompt oder ein Dokument teilt, nutzen Sie Context Caching, damit Sie nicht wiederholt den vollen Preis für dieselben TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → zahlen.
• Bewusst grounden. Grounding mit Google Search bringt Wert und Kosten. Schalten Sie es für Schritte ein, die frische Fakten brauchen, und für die anderen aus.

Den Loop begrenzen

Agents loopen. Ein Reasoning-Loop ohne Obergrenze kann das Modell für eine Aufgabe dutzende Male aufrufen. Setzen Sie immer eine harte Iterationsgrenze und ein TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Budget pro Run, und scheitern Sie geschlossen, wenn Sie es erreichen:

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 beobachten

In Vertex AI und Google Cloud setzen Sie ein Budget mit Budget-Alerts, 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 übersehen wurde. Bei APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Key-Nutzung aus AI Studio beobachten Sie die Nutzung in der Konsole und rotieren Keys, die geleakt sind. Budgets stoppen Ausgaben nicht von selbst, also kombinieren Sie sie mit den obigen Caps im Code.

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

So greifen die drei Kontrollen in einer realistischen Automatisierung zusammen. Eine wöchentliche Automatisierung liest ein Sales-Sheet, draftet eine Zusammenfassungs-E-Mail an die Führungsebene und wartet auf Freigabe.

• Scope: Apps Script mit spreadsheets.currentonly und gmail.compose. Es kann dieses eine Sheet lesen und einen Draft erstellen. Es kann nicht senden und keine anderen Dateien anfassen.
• Kosten: Flash für die Zusammenfassung (Pro ist Overkill für „fasse diese Tabelle zusammen“). Ein Call pro Woche, mit dem Sheet auf das letzte Quartal gekürzt, nicht die gesamte Historie.
• Review-Gate: Der Output ist ein Gmail-Draft an die Führungsebene. Ein Mensch liest ihn Montagmorgen und sendet, bearbeitet oder verwirft ihn.

Kein Teil davon kann jemandem eine E-Mail schicken, nennenswert Geld ausgeben oder Daten ändern, ohne einen Menschen. Das ist das Ziel: eine Automatisierung, bei der der *schlimmste realistische Fehler* ein Draft ist, den jemand löscht. Entwerfen Sie jeden Agent so, dass sein Failure Mode von der Konstruktion her harmlos ist, nicht weil Sie hoffen, dass das Modell sich benimmt.

Logging: das Guardrail, das Sie nur einmal brauchen

Loggen Sie jede Agent-Aktion: den Input, das Modell und die verbrauchten TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →, die vorgeschlagene Aktion und ob ein Mensch sie freigegeben hat. Wenn etwas schiefgeht (und irgendwann geht etwas schief), ist das Log der Weg, herauszufinden, was passiert ist, und zu belegen, was nicht passiert ist. In Apps Script schreiben Sie in ein eigenes Log-Sheet oder per console.log nach Cloud Logging. In Vertex AI nutzen Sie ADK-Callbacks, um jeden Tool Call zu erfassen. Eine Aktion, die Ihr System nicht erklären kann, ist eine Aktion, der Sie nicht vertrauen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen.

Key Takeaways

• Scope vor Verhalten. Vergeben Sie den engsten OAuth-Scope oder die engste IAM-Rolle, die funktioniert (gmail.compose statt gmail.send, ein Dataset statt das Projekt), und betreiben Sie eine Identität pro Agent, damit das Audit Log lesbar bleibt.
• Machen Sie den Failure Mode harmlos. Bauen Sie Agents so, dass das schlimmste realistische Ergebnis ein *Draft* ist, den ein Mensch löscht. Automatisieren Sie niemals Senden, Löschen, Zahlungen, Deployments oder Zugriffsvergaben unbeaufsichtigt.
• Erzwingen Sie Gates im Code, nicht im Prompt. Lassen Sie das Modell Risiko als Komfortfunktion markieren, aber legen Sie die echten „immer eskalieren“-Regeln in Ihren Control Flow, wo Prompt Injection sie nicht umdrehen kann.
• Standard ist Flash, Loop begrenzen. Nutzen Sie Gemini Flash, außererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → ein Schritt braucht Pro, cachen Sie wiederkehrenden Kontext, kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →ürzen Sie, was Sie senden, und setzen Sie eine harte Iterationsgrenze, damit kein Run eskaliert.
• Stützen Sie es mit Plattform-Budgets und Logs ab. Cloud Billing Alerts fangen auf, was Ihr Code verpasst, und ein vollständiges Action Log ist das, was Ihnen erlaubt, der Automatisierung später zu vertrauen (oder sie abzuschalten).