KI-Agenten erstellen, die im Namen des Nutzers handeln, mit Agent Identity and Auth Manager

1. Einführung

Ein KI-Agent mit eigenen Anmeldedaten und einer umfassenden Berechtigung sieht die Daten aller Nutzer. In diesem Codelab erstellen Sie einen Agenten, der eine Drittanbieter-API mit den Anmeldedaten des angemeldeten Nutzers aufruft. Der Agent sieht also genau das, was die Person sehen kann, und nichts weiter.

Sie erstellen ihn mit dem Google Agent Development Kit (ADK) und Gemini Enterprise.

Sie lernen, wie Sie eine Architektur mit zwei Identitäten entwerfen, in der:

1. Der Agent handelt in seinem eigenen Namen (Agent Identity): Mit einer SPIFFE-basierten Agent Identity ruft der Agent Auth Manager auf, speichert Telemetriedaten und ruft Google Cloud APIs auf.
2. Der Agent handelt im Namen des Nutzers (vom Nutzer delegierte Identität): Um auf externe Ressourcen wie GitHub zuzugreifen, löst der Agent einen 3-legged OAuth-Zustimmungsablauf (3LO) aus, um Tools sicher mit den Anmeldedaten des Nutzers abzufragen.

Dazu lernen Sie Folgendes:

1. Erstellen Sie einen ADK-Agenten, der eine Verbindung zum MCP-Server (Model Context Protocol) von GitHub herstellt.
2. Aktualisieren Sie das Tool des Agents von einem statischen GitHub-PAT (persönliches Zugriffstoken) auf den 3-Legged-OAuth-Ablauf (3LO) mit Google Cloud Auth Manager.
3. Stellen Sie den KI-Agenten sicher in der Agent Runtime bereit und stellen Sie die Agent Identity bereit.
4. IAM-Rollen konfigurieren, um dem Agenten im Namen des Nutzers Zugriff auf den Token-Tresor zu gewähren
5. Den End-to-End-Ablauf für die 3LO-Authentifizierung für Auth Manager in Google Cloud verstehen

Vorbereitung

Prüfen Sie zuerst, ob Sie Folgendes haben:

• Ein Google Cloud-Projekt mit aktivierter Abrechnung.
• Das Google Cloud SDK (gcloud-CLI) ist auf Ihrem lokalen Computer installiert und für Ihr Projekt authentifiziert. Version 586.0.0 oder höher ist erforderlich – führen Sie gcloud components update aus.
• Python 3.10 bis 3.13 ist lokal installiert.
• Der uv-Paketmanager ist installiert (pip install uv).
• Ein GitHub-Konto zum Registrieren einer OAuth-Anwendung und zum Erstellen von Tokens. Wenn Sie kein GitHub-Konto haben, können Sie einen beliebigen Drittanbieter-MCP-Server verwenden, der dreibeiniges OAuth 2.0 unterstützt.

2. Projekt einrichten

1. Bei Google Cloud authentifizieren

Authentifizieren Sie sich über die lokale Befehlszeile bei Google Cloud, um sicherzustellen, dass Ihre Umgebung die erforderlichen Berechtigungen hat, um in dieser Lab-Übung Agent Runtime bereitzustellen, Agent Identity bereitzustellen und Auth Manager zu konfigurieren:

Führen Sie die folgenden Befehle aus, um sich in Ihrem Google Cloud-Konto anzumelden und Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zu konfigurieren:

gcloud auth login
gcloud auth application-default login

2. Erforderliche Google Cloud-Dienste aktivieren

Aktivieren Sie die erforderlichen APIs in Ihrem Google Cloud-Projekt, um dieses Lab auszuführen. Führen Sie in Ihrem Terminal den folgenden Befehl aus:

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

Die Ausführung dieses Befehls kann eine Minute dauern. Wenn sie abgeschlossen ist, wird die Eingabeaufforderung wieder angezeigt und bestätigt, dass die APIs aktiv sind.

3. Agents CLI installieren und Projekt einrichten

agents-cli ist das Befehlszeilentool, mit dem ADK-Agents für Gemini Enterprise erstellt, verwaltet, getestet und bereitgestellt werden. Installieren Sie es lokal:

uvx google-agents-cli setup

Installation prüfen:

agents-cli --help

Das Hilfemenü der CLI sollte mit den verfügbaren Befehlen (z. B. deploy, run und status) angezeigt werden.

Generieren Sie das erste Projektgerüst. Sie beginnen mit einem lokalen Prototyp und optimieren ihn später für die Bereitstellung in Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

Dadurch wird das Verzeichnis „secure-agent-demo“ erstellt, das den grundlegenden Agentencode, die Abhängigkeiten und die Testdateien enthält.

4. Erforderliche ADK-Extras hinzufügen

Die generierte pyproject.toml enthält google-adk[gcp,otel-gcp], in der zwei Extras fehlen, die dieser Agent benötigt: mcp für das GitHub-Toolset und agent-identity für Auth Manager später im Lab. Öffnen Sie secure-agent-demo/pyproject.toml und ändern Sie die Zeile google-adk in:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

Installieren Sie dann:

cd secure-agent-demo
agents-cli install

3. Agent erstellen und testen

1. KI-Agenten erstellen

Ersetzen Sie in Ihrem Projekt den Code in der Datei agent.py durch Folgendes:

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

In dieser Datei werden drei Schlüsselkomponenten des Agents definiert:

• Systemanweisung (INSTRUCTION): Legt die Persona fest, schränkt den Assistenten auf die GitHub-Triage ein und erzwingt strenge Sicherheitsregeln (z. B. Nur-Lese-Zugriff und Aufforderung zur Authentifizierung bei Fehlern).
• Agent-Konfiguration (root_agent): Instanziiert ein ADK Agent mit dem Modell gemini-3.8-flash, konfiguriert die HTTP-Wiederholungslogik und stattet den Agent mit dem GitHub-Toolset aus.
• App-Wrapper (app): Kapselt den Stamm-Agenten in einem ADK-App-Container, sodass er in der Agent Runtime bereitgestellt werden kann.

2. GitHub-MCP-Tool hinzufügen

Der Agent stellt über das Model Context Protocol (MCP) eine Verbindung zu GitHub her. Erstellen Sie eine neue Datei mit dem Namen tools.py im Ordner app/, um die Verbindungsparameter des MCP-Gateways zu registrieren. Kopieren Sie den folgenden Code und fügen Sie ihn ein:

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

Mit dieser Funktion wird ein Tool erstellt, das den MCP-Server von GitHub aufruft:

• MCP-Toolset (McpToolset): Ermittelt und registriert GitHub-Funktionen dynamisch als aufrufbare Agent-Tools.
• Verbindungsparameter (StreamableHTTPConnectionParams): Verweist das Toolset auf das öffentliche MCP-Gateway von GitHub.
• Autorisierungsheader: Fügt das GITHUB_TOKEN als Bearer-Token ein und erzwingt den Lesemodus (X-MCP-Readonly: true) direkt auf der Transportschicht.

3. Lokal mit einem persönlichen GitHub-Zugriffstoken testen

So führen Sie den Agenten lokal mit statischen Anmeldedaten aus:

1. Erstellen Sie ein persönliches GitHub-Zugriffstoken. Gewähren Sie dem KI-Agenten Lesezugriff auf Ihre Repositories. Andernfalls kann er nur öffentliche Daten sehen und der Prompt unten gibt nichts zurück.
2. Legen Sie sie in Ihrer Umgebung fest:

   export GITHUB_TOKEN="your_github_pat_here"
   

3. Rufen Sie den Ordner secure-agent-demo auf. Ausführen:

   cd secure-agent-demo
   agents-cli playground
   

4. Öffnen Sie die Playground-Benutzeroberfläche und wählen Sie im Drop-down-Menü den Ordner „app“ aus. Geben Sie im Chatfeld "Fetch my contributions across my private repositories over the last 6 months" ein und prüfen Sie, ob der Agent das GitHub-Tool aufruft und Daten aus Ihren privaten Repositories zurückgibt.

4. Authentifizierungsmanager konfigurieren

Das Festcodieren statischer Anmeldedaten (z. B. eines PAT) ist zwar praktisch für Prototypen, setzt Produktionsanwendungen jedoch dem Risiko von Anmeldedatenlecks, Ausfallzeiten durch manuelles Aktualisieren von Tokens und einem Mangel an cloudnativen Zugriffssteuerungen aus.

Google Cloud bietet hierfür den Agent Identity Auth Manager. Der Authentifizierungsmanager für die Identität von KI-Agenten ist ein Anmeldedaten-Tresor, der zum Schutz von Anmeldedaten entwickelt wurde. Damit können sich Kundenservicemitarbeiter mit einem API-Schlüssel oder einer OAuth-Client-ID und einem Clientschlüssel authentifizieren oder im Namen eines Nutzers über die OAuth-Delegierung mit Endnutzer-Zugriffstokens.

Im Auth Manager konfigurieren Sie Authentifizierungsanbieter, die den Authentifizierungstyp und die Anmeldedaten für bestimmte Drittanbieteranwendungen definieren. Authentifizierungsanbieter sind regional und die Region muss mit der Region übereinstimmen, in der Sie den Agent bereitstellen. Der End-to-End-Workflow von Auth Manager funktioniert so:

1. Dynamisches Abfangen der Einwilligung: Wenn der Agent versucht, ein Tool im Namen eines Nutzers auszuführen, prüft das ADK im Auth Manager, ob gültige Anmeldedaten vorhanden sind. Wenn keine vorhanden ist, gibt Auth Manager eine Autorisierungs-URL zurück, um einen 3-Legged-OAuth-Zustimmungsablauf (3LO) zu starten.
2. Sichere Vault-Speicherung: Sobald der Endnutzer die Anwendung autorisiert, fängt Auth Manager den OAuth-Callback automatisch ab und speichert die resultierenden Nutzerzugriffs- und Aktualisierungstokens in einem sicheren, von Google verwalteten Anmeldedaten-Vault.
3. Automatisierter Tokenlebenszyklus: Auth Manager verwaltet das Ablaufen und Rotieren von Tokens vollständig im Hintergrund. Dadurch ist keine manuelle Tokenaktualisierungslogik oder Ausfallzeit erforderlich.
4. Ausführung von Tools ohne Secrets: Für nachfolgende Aktionen fordert der Agent (der sich über seine SPIFFE Agent Identity authentifiziert) das delegierte Zugriffstoken des Nutzers dynamisch zur Laufzeit vom Auth Manager an. So bleiben sowohl der Client- als auch der Agentencode vollständig ohne Secrets.

Wichtig: In diesem Codelab werden Platzhaltervariablen in Großbuchstaben verwendet (z. B. YOUR_PROJECT_ID, YOUR_PROJECT_NUMBER, YOUR_ORG_ID und YOUR_ENGINE_ID). Ersetzen Sie diese durch Ihre eigenen Google Cloud-Projekt- und Ressourcenwerte, wenn Sie die Befehle ausführen.

Schritt A: GitHub als Auth-Anbieter konfigurieren

Führen Sie den folgenden gcloud-Befehl aus, um einen GitHub-Authentifizierungsanbieter in Ihrem Google Cloud-Projekt zu erstellen. Sie geben die Client-ID und den Clientschlüssel später an: GitHub stellt sie erst aus, wenn die Callback-URL dieses Anbieters bekannt ist.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

Beschreiben Sie den Anbieter, um die generierte OAuth-Weiterleitungs-URL abzurufen:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

Das Feld ist redirectUrl und ist in authProviderTypeParams.threeLeggedOauth verschachtelt. So lesen Sie sie direkt:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

Er sieht so aus: https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Schritt B: OAuth-App in GitHub registrieren

1. Rufen Sie die Seite GitHub Developer Settings auf und klicken Sie auf Register a new OAuth app.
2. Geben Sie für die URL der Startseite die URL Ihrer Frontend-Anwendung ein, z.B. http://localhost:8501 für lokales Prototyping. Sie können sie später in die bereitgestellte URL in der Produktion ändern.
3. Legen Sie den Redirect URI auf den redirectUrl fest, der im vorherigen Schritt abgerufen wurde.
4. Klicken Sie auf Anwendung registrieren und dann auf Neuen Clientschlüssel generieren. Speichern Sie sowohl die Client-ID als auch den Clientschlüssel.

Schritt C: GitHub-Anmeldedaten dem Authentifizierungsanbieter hinzufügen

Ersetzen Sie Ihre Projekt-ID, Client-ID und Ihren Clientschlüssel und führen Sie diesen Befehl aus:

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

Der Befehl gibt den Anbieter mit clientId zurück. Das Secret wird nicht zurückgegeben.

👉 Nach Abschluss dieses Schritts ist Ihr Google Cloud Auth Manager jetzt vollständig mit den Anmeldedaten Ihrer GitHub-OAuth-Anwendung konfiguriert. Google Cloud wird als sicherer Tresor eingerichtet, in dem Einwilligungs- und Token-Lebenszyklen verwaltet werden.

5. PAT-Token zu Auth Manager migrieren

Nachdem der Auth Manager vollständig konfiguriert wurde, müssen Sie als Nächstes den Tool-Code des Agenten aktualisieren. Ersetzen Sie app/tools.py durch den folgenden Code.

👉 Ersetzen Sie die Projekt-ID und den Standort in der Variablen OAUTH_PROVIDER_NAME unten.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

Tool-Code verstehen

Die wichtigste Änderung ist auth_scheme. Wenn Sie es an das Toolset anhängen, fragt ADK jedes Mal, wenn der Agent GitHub aufruft, zuerst den Auth Manager nach dem Token des Nutzers. Wenn noch keines vorhanden ist, wird der Nutzer aufgefordert, sich anzumelden, anstatt dass ein Fehler auftritt. Die hartcodierte GITHUB_TOKEN ist vollständig verschwunden.

6. KI-Agent in Agent Runtime bereitstellen

Nachdem wir das GitHub-MCP-Tool für die Verwendung von Auth Manager aktualisiert haben, müssen wir den Agenten in Agent Runtime bereitstellen. Wenn Sie den Agent mit aktivierter Agent-Identität bereitstellen, wird eine eindeutige SPIFFE-ID für den Agent bereitgestellt.

Beginnen wir mit der Initialisierung der Bereitstellungskonfiguration für das Projekt. Im Terminal ausführen:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

Mit diesem Befehl wird die Projektstruktur auf ADK-Kompatibilität geprüft, die zugrunde liegenden Container-Paketierungskonfigurationen werden vorbereitet und im Stammverzeichnis des Projekts wird eine agents-cli-manifest.yaml-Datei mit Standardbereitstellungseinstellungen generiert.

👉 Öffnen Sie die neu erstellte Datei agents-cli-manifest.yaml und prüfen oder aktualisieren Sie das Feld region auf us-central1, damit Ihr Agent in derselben Region wie Ihr Authentifizierungsanbieter bereitgestellt wird:

region: "us-central1"

Agenten mit einer Agent Identity bereitstellen

Mit adk deploy agent_engine bereitstellen Dadurch wird dem Agent eine eigene Agentenidentität zugewiesen. Das ist eine eindeutige, SPIFFE-basierte kryptografische Identität, die zu dieser Bereitstellung gehört und mit der sich der Agent bei Auth Manager und anderen Google Cloud-Diensten authentifiziert.

👉 Ersetzen Sie YOUR_PROJECT_ID, bevor Sie diese Befehle ausführen:

# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

Die Bereitstellung dauert einige Minuten, da der Container erstellt und hochgeladen werden muss. Nach Abschluss des Vorgangs gibt die CLI den Namen der bereitgestellten Ressource aus. Notieren Sie sich den Wert für reasoningEngines/ENGINE_ID, da Sie ihn benötigen, um Ihren Agent zu autorisieren und den UI-Client darauf zu verweisen.

Verwenden Sie adk deploy agent_engine, nicht agents-cli deploy --agent-identity. Beide werden erfolgreich bereitgestellt, aber es werden unterschiedliche Ressourcenformen erstellt. agents-cli deploy erstellt einen Container-Server ohne classMethods. Der UI-Client, den Sie später ausführen, ruft create_session() für den bereitgestellten Agent auf und schlägt mit 'AgentEngine' object has no attribute 'create_session' fehl. adk deploy agent_engine erzeugt die serialisierte AdkApp-Form, die die 13 Methoden bereitstellt, die der Client benötigt.

Wohin der Nutzer nach der Einwilligung weitergeleitet wird: Sobald ein Nutzer den Zugriff genehmigt hat, wird sein Browser an die Adresse in OAUTH_CONTINUE_URI gesendet, die von Ihrer eigenen Clientanwendung bereitgestellt wird. In diesem Lab wird der Client auf Ihrem Computer ausgeführt. Der Agent verwendet also die Standardeinstellung, die bereits in app/tools.py (http://localhost:8501/validateUserId) festgelegt ist. Sie müssen nichts ändern. Wenn Sie den Client später an einem anderen Ort hosten, aktualisieren Sie den Standardwert vor der Bereitstellung.

Agent Identity autorisieren

Da Ihr Agent jetzt in der Cloud ausgeführt wird, benötigt er die Berechtigung, auf die in Auth Manager gespeicherten Anmeldedaten zuzugreifen. Standardmäßig hat die SPIFFE-Identität des Agents keinen Zugriff auf externe Cloud-Ressourcen.

Führen Sie den folgenden gcloud-Befehl aus, um der Identität Ihres Agenten für die Authentifizierungsanbieterressource die Rolle roles/agentidentity.user zuzuweisen. Dadurch erhält Ihr Agent genau die Berechtigungen, die er zum Anfordern von Nutzer-Tokens aus dem Tresor benötigt, und nichts darüber hinaus.

👉 Ersetzen Sie YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER und YOUR_ENGINE_ID (die Engine-ID finden Sie in der Bereitstellungsausgabe oben).

Führen Sie den folgenden Befehl aus, um YOUR_ORG_ID abzurufen:

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

Weisen Sie Ihrem eigenen Konto dieselbe Rolle beim Anbieter zu. Der UI-Client, den Sie im nächsten Schritt ausführen, ruft die API zur Finalisierung von Anmeldedaten mit Ihren Standardanmeldedaten für Anwendungen auf. Ohne diese schlägt der Einwilligungsablauf mit einem 403 auf agentidentity.authProviders.retrieveCredentials fehl:

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

Diese zweite Bindung ist nur erforderlich, um das Lab lokal auszuführen. Damit kann der Client auf Ihrem Computer die Einwilligung mit Ihren eigenen Anmeldedaten abschließen. In der Produktion wird der Client unter seiner eigenen Identität ausgeführt und nur die oben genannte Agent-Bindung ist erforderlich.

7. 3LO-Einwilligungsablauf

Nachdem der KI-Agent mit einer sicheren Agent-Identität in Agent Runtime bereitgestellt wurde, besteht der nächste Schritt darin, eine benutzerdefinierte Frontend-Oberfläche für Nutzer bereitzustellen, damit sie mit dem KI-Agenten chatten können. Wichtiger ist, dass Google Cloud Auth Manager einen Callback-Handler für Clientanwendungen benötigt, um den Authentifizierungszyklus abzuschließen.

Google Cloud Auth Manager kann Nutzeranmeldedaten zwar sicher in einem Tresor verwalten, den OAuth-Tokenaustausch jedoch nicht selbst abschließen. Beim 3LO-Handshake muss die Clientanwendung die Lücke schließen:

1. Wenn ein Nutzer die GitHub-App autorisiert, leitet GitHub ihn zurück zur redirectUrl des Authentifizierungsanbieters für die Agent-Identität .
2. Auth Manager leitet das Pop-up des Nutzerbrowsers dann an eine clientseitige Callback-URL (continue_uri) weiter.
3. Es liegt in der Verantwortung der Clientanwendung, diese Weiterleitung abzufangen, die Einmal-ID aus den Browser-Cookies zu lesen und den credentials:finalize-Endpunkt von Google Cloud aufzurufen, um den Handshake abzuschließen.
4. Sobald der Kunde den Austausch abgeschlossen hat, speichert Google Cloud das Token sicher im Tresor des Authentifizierungsanbieters. So kann der Kundenservicemitarbeiter das GitHub-Tool aufrufen.

Ohne diesen benutzerdefinierten Client, der den Callback-Endpunkt hostet, bleibt der Handshake unvollständig und die Anmeldedaten können nicht im Tresor gespeichert werden.

Der interaktive OAuth 3LO-Ablauf erstreckt sich über mehrere Ebenen. Hier ist der vollständige Ausführungslebenszyklus einer Toolanfrage. Das wird in der folgenden Erklärung und im nächsten Schritt genauer erläutert.

👉 Klicken Sie auf das Bild, um es zu vergrößern.

Die wichtigsten Pflichten des Kunden bei der Übergabe

• Einwilligungsaufforderung weiterleiten (Schritte 5–6): Der Agent gibt ein adk_request_credential mit der Einwilligungs-URL und einer Einmal-Nonce aus. Der Client öffnet das Pop-up und speichert die Nonce als Cookie.
• Callback für die Weiterleitung hosten (Schritte 10–11) : /validateUserId, wobei Auth Manager das Pop-up nach der Einwilligung sendet.
• Token fertigstellen (Schritte 12 bis 14): Kombinieren Sie den Validierungsstatus aus der Weiterleitung mit der im Cache gespeicherten Nonce und rufen Sie credentials:finalize auf, um das Token im Tresor zu speichern.

Eigenen Client erstellen

Sie müssen diesen Client nicht für das Lab schreiben. Im nächsten Schritt wird ein vorgefertigter Client ausgeführt. Wenn Sie dies in Ihrer eigenen Anwendung implementieren möchten, können Sie sich an den folgenden beiden Referenzen orientieren:

• Clientseitige Anwendung aktualisieren in der Auth Manager-Dokumentation. Dort wird beschrieben, wie Sie die Einwilligungsaufforderung verarbeiten und credentials:finalize aufrufen.
• Der ausführbare Beispielclient im ADK-Python-Repository. Eine vollständige, funktionierende Implementierung der drei oben genannten Verantwortlichkeiten finden Sie unter main.py.

8. UI-Client lokal ausführen

Wie im Ablaufdiagramm für die Einwilligung mit 3LO dargestellt, muss Auth Manager das Browser-Pop-up an einen clientseitigen Callback-Endpunkt weiterleiten. Der Beispielclient hostet diesen Endpunkt unter /validateUserId. Führen wir ihn lokal aus.

Clientdateien in „Lokal“ kopieren

Rufen Sie im GitHub-Repository „adk-python“ den Ordner gcp_auth/client auf. Dieser Ordner enthält die Assets, die zum Erstellen des Chatclient-Containers erforderlich sind.

👉 Kopieren Sie alle Dateien unter gcp_auth/client in Ihre lokale Umgebung:

• main.py: Das FastAPI-Anwendungsscript mit dem Token-Finalisierungs-Callback (/validateUserId), das wir im vorherigen Abschnitt besprochen haben.
• static/: Enthält die HTML-Seiten.

Alternativ können Sie auch einen Sparse-Checkout des Ordners durchführen:

git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout

Client ausführen

1. Rufen Sie den Ordner client auf, den Sie gerade kopiert haben:

   cd adk-python/contributing/samples/integrations/gcp_auth/client
   

2. Erstellen Sie eine virtuelle Umgebung und installieren Sie die Abhängigkeiten des Clients. Der Ordner enthält eine requirements.txt, aber keine pyproject.toml. Daher schlägt uv run uvicorn ... allein mit Failed to spawn: uvicorn fehl:

   uv venv --python 3.13 .venv
   source .venv/bin/activate
   uv pip install --python .venv/bin/python -r requirements.txt
   

3. Richten Sie den Client auf den bereitgestellten Agent aus und starten Sie ihn auf Port 8501:

   export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=us-central1
   export AGENT_ID=YOUR_ENGINE_ID
   
   .venv/bin/uvicorn main:app --port 8501
   

4. Prüfen Sie, ob der Server erfolgreich gestartet wurde und auf http://localhost:8501 wartet.

Verwenden Sie localhost, nicht 127.0.0.1. Für die OAuth-Weiterleitung ist der Hostname localhost erforderlich. Die beiden sind hier nicht austauschbar, auch wenn sie in dieselbe Adresse aufgelöst werden.

9. OAuth-Ablauf testen

Nachdem alle Dienste bereitgestellt, IAM-Bindungen konfiguriert und Umgebungsvariablen festgelegt wurden, können Sie den sicheren End-to-End-Autorisierungsablauf mit Nutzerdelegierung testen.

Schritt A: Toolausführung starten

1. Öffnen Sie einen Browsertab und rufen Sie die Client-URL auf: http://localhost:8501.
2. Legen Sie im linken Bereich den Agent-Typ auf Remote Agent Engine fest.
3. Geben Sie Ihr Google Cloud-Projekt und den Standort ein. Klicken Sie auf Load Remote Agents. Dadurch sollten alle in Ihrem Projekt bereitgestellten KI-Agenten geladen werden.
4. Wählen Sie den richtigen Agenten aus dem Drop-down-Menü aus und speichern Sie die Einstellungen.
5. Geben Sie im Chatfeld Folgendes ein:

   Fetch my contributions across my private repositories over the last 6 months
   

   und drücken Sie die Eingabetaste.
6. Chat-Benutzeroberfläche beobachten: Da der Agent noch keine Anmeldedaten für Ihre Nutzersitzung hat, erhält er eine Authentifizierungsaufforderung und zeigt die Karte „Authentifizierung erforderlich“ im Unterhaltungsverlauf an.

Schritt B: Dreibeinige OAuth-Zustimmung abschließen

1. Es wird ein separates Browser-Pop-up-Fenster geöffnet, in dem Sie über den Auth Manager von Google Cloud zur GitHub-OAuth-Autorisierungsseite weitergeleitet werden.
2. Prüfen Sie die angeforderten Berechtigungen und klicken Sie auf Autorisieren.
3. GitHub leitet Sie zurück zu Google Cloud, das das Pop-up an Ihre localhost-Callback-URL /validateUserId weiterleitet.
4. Der Callback-Dienst verarbeitet und schließt den Anmeldedaten-Handshake ab.

Schritt C: Lebenslauf

1. Sobald das Pop-up-Fenster geschlossen wird, wird das automatisch auf dem Tab des übergeordneten Chats erkannt.
2. Das Frontend sendet eine Nutzlast mit dem Status „resume“ zurück an den Agent.
3. Der Agent ruft das neu ausgetauschte Token sicher von Google Cloud Auth Manager ab, ruft die GitHub-MCP-Tools in Ihrem Namen auf und streamt Daten aus Ihren privaten Repositories direkt zurück in das Chatfenster – Daten, auf die der Agent allein nicht hätte zugreifen können.

Schritt D: Cloud-Logs prüfen

So prüfen Sie, ob der Tausch und die Finalisierung des Tokens sicher verarbeitet wurden:

1. Rufen Sie in der Google Cloud Console den Log-Explorer auf.
2. Suchen Sie in den Serverlogs nach Bestätigungen für die Nonce-Extraktion und die erfolgreiche Validierung:

   INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
   INFO:secure-agent-client:Successfully finalized auth provider credentials.
   

3. Agent Runtime-Logs ansehen: Alternativ können Sie Ausführungsprotokolle direkt in der Agent Platform Console ansehen:
   • Rufen Sie die Agent Runtime Console auf.
   • Klicken Sie in der Liste auf den bereitgestellten Agenten.
   • Wechseln Sie zum Tab Playground. Im unteren Bereich werden die Live-Agent-Logs angezeigt. Dort sehen Sie in Echtzeit den Reasoning-Loop des Agents, Details zur Ausführung von Tools und den Lebenszyklus des Tokenabrufs.

10. Bereinigen

So vermeiden Sie laufende Kosten in Google Cloud:

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

Lokale Dateien bereinigen

Optional können Sie Ihre lokale Umgebung vollständig bereinigen:

1. Beenden Sie den lokalen Uvicorn-Server, indem Sie im Terminal, in dem er ausgeführt wird, Strg + C drücken.
2. Entfernen Sie die Projektverzeichnisse, die in diesem Lab erstellt wurden:

# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Glückwunsch!

Sie haben einen Agenten erstellt und gesichert, der im Namen des angemeldeten Nutzers agiert.

Das haben Sie gelernt:

• Agent-Systemidentität: So arbeitet der Agent mit seiner eigenen Kontoidentität, um sicher mit der GCP-Infrastruktur zu interagieren, Telemetrielogs zu verwalten und APIs zur Finalisierung von Anmeldedaten aufzurufen.
• Delegierte Nutzeridentität: So fordert der Agent die Autorisierung an, im Namen des Nutzers auf externen Plattformen (z. B. GitHub) zu agieren, indem er einen 3-legged OAuth-Zustimmungsablauf (3LO) auslöst.
• Secure Tool Integration: Hier erfahren Sie, wie Sie ADK-Agents über Google Cloud Auth Manager mit MCP-Servern (Model Context Protocol) verbinden, um Nutzer-Tokens dynamisch abzurufen, anstatt fest codierte Secrets zu verwenden.
• IAM-Richtlinienkonfiguration: Hier erfahren Sie, wie Sie detaillierte Berechtigungsbindungen einrichten, um sowohl die Agent Runtime-Identität als auch Ihr eigenes Konto beim Authentifizierungsanbieter zu autorisieren.

Weiterführende Literatur

• Authentifizierungsmanager für die Identität von KI-Agenten, um Informationen zur Konfiguration des Authentifizierungsablaufs und zu Bereichen zu erhalten.
• Agent Runtime – Übersicht
• ADK-Dokumentation
• Model Context Protocol