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

1. Einführung

Ein 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. So sieht er genau das, was diese Person sehen kann, und nicht mehr.

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

Insbesondere erfahren Sie, wie Sie eine Architektur mit zwei Identitäten entwerfen, bei der:

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

Duale Identitätsarchitektur

Dazu lernen Sie Folgendes:

  1. ADK-Agenten erstellen, der eine Verbindung zum MCP-Server (Model Context Protocol) von GitHub herstellt.
  2. Aktualisieren Sie das Tool des KI-Agenten von einem statischen GitHub-PAT (Personal Access Token) auf einen 3-Legged-OAuth-Ablauf (3LO) mit Google Cloud Auth Manager.
  3. Den KI-Agenten sicher in der Agent Runtime bereitstellen und die Agent Identity bereitstellen.
  4. Konfigurieren Sie IAM-Rollen, um der Identität des Agenten im Namen des Nutzers Zugriff auf den Token-Vault zu gewähren.
  5. Machen Sie sich mit dem End-to-End-3LO-Ablauf für Auth Manager in Google Cloud vertraut.

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 lokal installiert.
  • Der uv-Paketmanager ist installiert (pip install uv).
  • Ein GitHub-Konto, um eine OAuth-Anwendung zu registrieren und Tokens zu erstellen. Wenn Sie kein GitHub-Konto haben, können Sie einen beliebigen MCP-Server eines Drittanbieters verwenden, der dreibeiniges OAuth 2.0 unterstützt.

2. Projekt einrichten

1. Bei Google Cloud authentifizieren

Authentifizieren Sie sich in diesem Lab über die lokale Befehlszeile bei Google Cloud, damit Ihre Umgebung die erforderlichen Berechtigungen hat, um Agent Runtime bereitzustellen, Agent Identity einzurichten und Auth Manager zu konfigurieren.

Führen Sie die folgenden Befehle aus, um sich in Ihrem Google Cloud-Konto anzumelden, Ihr aktives Projekt festzulegen (ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID) und Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zu konfigurieren:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
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. Sobald er abgeschlossen ist, wird die Eingabeaufforderung wieder angezeigt und die APIs sind aktiviert.

3. Agents CLI installieren und Projekt einrichten

agents-cli ist das Befehlszeilentool, mit dem ADK-Agenten 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

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

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

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

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

4. Erforderliche ADK-Extras hinzufügen

Fügen Sie die beiden fehlenden Extras in der generierten pyproject.toml hinzu: mcp für das GitHub-Toolset und agent-identity für den Auth Manager, der später im Lab verwendet wird. Öffnen Sie secure-agent-demo/pyproject.toml und ersetzen Sie den gesamten

google-adk

Abhängigkeitszeile durch:

"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. KI-Agenten erstellen und testen

1. KI-Agenten erstellen

Ersetzen Sie den Code in secure-agent-demo/app/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 wichtige Komponenten des KI-Agenten definiert:

  • Systemanweisung (INSTRUCTION): Legt die Persona fest, beschränkt den Assistenten auf die GitHub-Triage und erzwingt strenge Sicherheitsregeln (z. B. Lesezugriff und Aufforderung zur Authentifizierung bei Fehlern).
  • Agentenkonfiguration (root_agent): Instanziiert ein ADK-Agent mit dem gemini-3.8-flash-Modell, konfiguriert die HTTP-Wiederholungslogik und stattet den Agenten mit dem GitHub-Toolset aus.
  • App Wrapper (app): Kapselt den Stamm-Agenten in einen 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 unter secure-agent-demo/app/tools.py, 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",
            },
        )
    )

Diese Funktion erstellt ein Tool, das den MCP-Server von GitHub aufruft:

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

3. Lokal mit einem GitHub-PAT (Personal Access Token) testen

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

  1. Erstellen Sie auf der GitHub-Seite Personal Access Tokens ein feinkörniges persönliches Zugriffstoken:
    • Klicken Sie auf Generate new token und geben Sie dem Token einen Namen.
    • Wählen Sie unter Repository-Zugriff die Option Alle Repositories aus oder wählen Sie bestimmte Repositories aus, mit denen Sie testen möchten.
    • Klicken Sie unter Berechtigungen > Repositories auf + Berechtigungen hinzufügen und wählen Sie Inhalte, Probleme und Pull-Anfragen als Schreibgeschützt aus. (Metadaten wird automatisch auf „Schreibgeschützt“ gesetzt.)
    • Klicken Sie auf Generate token (Token generieren) und kopieren Sie den generierten Tokenwert. (Wenn Sie ein Personal access token (classic) verwenden, wählen Sie den Bereich repo aus.)
  2. Legen Sie sie in Ihrer Umgebung fest:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. Wechseln Sie zum Ordner secure-agent-demo (falls Sie sich noch nicht darin befinden) und starten Sie den lokalen Playground:
    cd secure-agent-demo
    agents-cli playground
    
  4. Öffnen Sie die Playground-Oberfläche und wählen Sie im Drop-down-Menü den Ordner app aus. Geben Sie im Chatfeld einen gezielten Prompt wie "Get the last 2 GitHub issues reported against my name" oder "List my 3 most recently updated repositories" ein und prüfen Sie, ob der Agent das GitHub-MCP-Toolset aufruft und Ihre GitHub-Daten zurückgibt. Wenn Sie testen möchten, ob der KI-Agent Ihr PAT-Token tatsächlich verwendet, um in Ihrem Namen Aktionen auszuführen, fragen Sie ihn nach Ihren privaten Repositories oder Beiträgen.

4. Auth Manager konfigurieren

Das Hardcodieren statischer Anmeldedaten (z. B. eines PAT) ist zwar für das Prototyping praktisch, birgt aber das Risiko, dass Anmeldedaten in Produktionsanwendungen offengelegt werden, dass es zu Ausfallzeiten durch manuelle Tokenaktualisierungen kommt und dass keine cloudnativen Zugriffssteuerungen vorhanden sind.

Um dieses Problem zu lösen, bietet Google Cloud den Agent Identity-Authentifizierungsmanager. Der Agent Identity-Authentifizierungsmanager ist ein Anmeldedatenspeicher, der zum Schutz von Anmeldedaten dient. Agenten können sich 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.

In 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 des Auth Managers funktioniert so:

Workflow für Auth Manager

  1. Dynamische Einwilligungserfassung: 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-Einwilligungsablauf (3LO) zu initiieren.
  2. Sicherer Vault-Speicher: 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 Vault für Anmeldedaten.
  3. Automatisierter Token-Lebenszyklus: Auth Manager verwaltet den Ablauf und die Rotation von Tokens vollständig im Hintergrund. Dadurch entfällt die Notwendigkeit einer manuellen Logik für die Token-Aktualisierung und es kommt nicht zu Ausfallzeiten.
  4. Geheimnisfreie Toolausführung: Für nachfolgende Aktionen fordert der KI-Agent (der sich über seine SPIFFE-Agentenidentität authentifiziert) das delegierte Zugriffstoken des Nutzers dynamisch zur Laufzeit vom Auth Manager an. So bleiben sowohl der Client- als auch der Agentencode vollständig geheimnisfrei.

Schritt A: GitHub als Authentifizierungsanbieter konfigurieren

Führen Sie den folgenden gcloud-Befehl aus, um einen GitHub-Authentifizierungsanbieter in Ihrem Google Cloud-Projekt zu erstellen. Die Client-ID und den Clientschlüssel geben Sie 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="YOUR_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="YOUR_PROJECT_ID" \
    --location="us-central1"

Das Feld ist redirectUrl, verschachtelt unter authProviderTypeParams.threeLeggedOauth. So liest du sie direkt:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_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-Anwendung in GitHub registrieren

  1. Rufen Sie die Seite GitHub Developer Settings auf, wählen Sie in der linken Seitenleiste OAuth Apps aus und klicken Sie auf New OAuth App (oder Register a new application, wenn Sie noch keine erstellt haben).
  2. Füllen Sie die Felder des OAuth-Anwendungsformulars aus:
    • Anwendungsname: Geben Sie einen Namen für Ihre Anwendung ein (z. B. secure-agent-demo).
    • Homepage-URL: Geben Sie die URL Ihrer Frontend-Anwendung ein (http://localhost:8501 für lokales Prototyping; Sie können sie in der Produktion auf Ihre bereitgestellte URL aktualisieren).
    • Anwendungsbeschreibung: Optional (Sie können dieses Feld leer lassen).
    • Authorization callback URL (Redirect URI): Fügen Sie die in Schritt A abgerufene redirectUrl ein.
    • Geräteablauf aktivieren: Lassen Sie das Häkchen weg.
  3. Klicken Sie auf Anwendung registrieren.
  4. Kopieren Sie auf der angezeigten Anwendungsseite die Client-ID, klicken Sie dann auf Neuen Clientschlüssel generieren und kopieren Sie den generierten Clientschlüssel. Speichern Sie beide Werte. Sie werden im nächsten Schritt als YOUR_GITHUB_CLIENT_ID und YOUR_GITHUB_CLIENT_SECRET verwendet.

Schritt C: GitHub-Anmeldedaten zum Authentifizierungsanbieter hinzufügen

Ersetzen Sie YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID und YOUR_GITHUB_CLIENT_SECRET durch Ihre Werte 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 sichtbarem clientId zurück. Das Secret wird nicht zurückgegeben.

👉 Nachdem Sie diesen Schritt abgeschlossen haben, ist Ihr Google Cloud Auth Manager jetzt vollständig mit den Anmeldedaten Ihrer GitHub-OAuth-Anwendung konfiguriert. Google Cloud fungiert als sicherer Vault, der die Einwilligung und den Lebenszyklus von Tokens verwaltet.

5. PAT-Token auf Auth Manager umstellen

Nachdem der Auth Manager vollständig konfiguriert ist, müssen Sie als Nächstes den Toolcode des KI-Agenten aktualisieren. Ersetzen Sie den Inhalt von secure-agent-demo/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,
    )

Toolcode verstehen

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

6. KI-Agent in Agent Runtime bereitstellen

Nachdem wir das GitHub-MCP-Tool so aktualisiert haben, dass es Auth Manager verwendet, müssen wir den Agenten in der Agent Runtime bereitstellen. Wenn Sie ihn mit aktivierter Agent-Identität bereitstellen, wird für den KI-Agenten eine eindeutige SPIFFE-ID bereitgestellt.

Initialisieren Sie die Bereitstellungskonfiguration für das Projekt. Prüfen Sie, ob sich Ihr Terminal im Stammverzeichnis des Projekts secure-agent-demo befindet, und führen Sie dann Folgendes aus:

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-Paketkonfigurationen werden vorbereitet und im Stammverzeichnis des Projekts wird eine agents-cli-manifest.yaml-Datei mit Standardbereitstellungseinstellungen vorab ausgefüllt.

👉 Öffnen Sie die neu erstellte agents-cli-manifest.yaml-Datei 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"

KI-Agenten mit einer Agentenidentität bereitstellen

Stellen Sie die Anwendung mit adk deploy agent_engine bereit. Dadurch wird der KI-Agent mit einer eigenen Agentenidentität ausgestattet – einer eindeutigen, SPIFFE-basierten kryptografischen Identität, die zu dieser Bereitstellung gehört und die der KI-Agent zur Authentifizierung bei Auth Manager und anderen Google Cloud-Diensten verwendet.

👉 Ersetzen Sie im Verzeichnis secure-agent-demo den Platzhalter YOUR_PROJECT_ID und führen Sie die folgenden Befehle aus:

# Write a config file inside the `app/` folder instructing Agent Runtime to provision 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"

Das Erstellen und Hochladen des Containers dauert einige Minuten. Anschließend gibt die Befehlszeile den Namen der bereitgestellten Ressource aus. Notieren Sie sich den Wert „reasoningEngines/ENGINE_ID“, da Sie ihn benötigen, um Ihren Agenten zu autorisieren und den UI-Client darauf zu verweisen.

Agentenidentität autorisieren

Da Ihr Agent jetzt in der Cloud ausgeführt wird, benötigt er die Berechtigung, auf die im 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 Authentifizierungsanbieter-Ressource die Rolle roles/agentidentity.user zuzuweisen. Dadurch erhält Ihr Agent genau die Berechtigungen, die er benötigt, um Nutzer-Tokens aus dem Vault anzufordern, und keine weiteren.

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

# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
  --format="value(projectNumber)"

Binden Sie dann die IAM-Richtlinie an den Authentifizierungsanbieter (ersetzen Sie YOUR_PROJECT_ID und das Hauptkonto --member):

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"

👉 Sie können den vollständigen --member="principal://..."-Wert für Ihren bereitgestellten KI-Agenten auch über die Google Cloud Console abrufen: Rufen Sie die Agent Runtime-Konsole auf, wählen Sie Ihren bereitgestellten KI-Agenten aus, rufen Sie den Tab Identität auf und kopieren Sie den vollständigen principal://...-String direkt.

Weisen Sie jetzt Ihrem eigenen Konto dieselbe Rolle beim Anbieter zu. Der UI-Client, den Sie im nächsten Schritt ausführen, ruft die API zur Finalisierung der Anmeldedaten mit Ihren Standardanmeldedaten für Anwendungen auf. Ohne diese schlägt der Einwilligungsablauf mit einem 403-Fehler bei 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"

7. 3LO-Einwilligungsablauf

Nachdem der KI-Agent mit einer sicheren Agent Identity in der Agent Runtime bereitgestellt wurde, besteht der nächste Schritt darin, eine benutzerdefinierte Frontend-Oberfläche bereitzustellen, über die Nutzer mit ihm chatten können. Noch wichtiger ist, dass Google Cloud Auth Manager einen Callback-Handler für die Clientanwendung benötigt, um die Authentifizierungsschleife abzuschließen.

Google Cloud Auth Manager verwaltet Nutzeranmeldedaten zwar sicher in einem Vault, kann den OAuth-Tokenaustausch aber nicht selbst abschließen. Der 3LO-Handshake basiert auf der Clientanwendung, um die Lücke zu schließen:

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

Ohne diesen benutzerdefinierten Client, der den Callback-Endpunkt hostet, bleibt der Handshake unvollständig und der Vault kann die Anmeldedaten nicht speichern.

Der interaktive OAuth-3LO-Ablauf erstreckt sich über mehrere Ebenen. Hier ist der vollständige Ausführungslebenszyklus einer Toolanfrage. Wir gehen darauf in der Erklärung unten und im nächsten Schritt näher ein.

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

3-Legged-OAuth-Sequenzfluss

Die wichtigsten Aufgaben des Kunden beim Handshake

  • Einwilligungsaufforderung weiterleiten (Schritte 5–6): Der Agent gibt eine adk_request_credential mit der Einwilligungs-URL und einer Einmal-Nonce aus. Der Client öffnet das Pop-up und speichert die Nonce als Cookie.
  • Redirect-Callback hosten (Schritte 10–11): /validateUserId, wohin Auth Manager das Pop-up nach der Einwilligung sendet.
  • Token fertigstellen (Schritte 12–14): Kombiniere den Validierungsstatus aus der Weiterleitung mit der im Cache gespeicherten Nonce und rufe credentials:finalize auf, wodurch das Token im Vault gespeichert wird.

Eigenen Client erstellen

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

8. UI-Client lokal ausführen

Wie im Sequenzdiagramm 3LO-Zustimmungsablauf dargestellt, leitet Auth Manager das Browserfenster zurück zu einem clientseitigen Callback-Endpunkt. Der Beispielclient im Repository adk-python hostet diesen Endpunkt unter /validateUserId. Laden Sie es herunter und führen Sie es lokal aus. Gehen Sie dazu so vor:

Clientdateien herunterladen

Das Verzeichnis contributing/samples/integrations/gcp_auth/client in adk-python enthält drei wichtige Assets:

  • main.py: Das FastAPI-Backend, das eine Verbindung zu Ihrer bereitgestellten Agent Engine herstellt und den Callback-Endpunkt /validateUserId hostet, um OAuth-Tokens abzuschließen.
  • static/: Die HTML- und JavaScript-Dateien für die Browser-Chat-UI.
  • requirements.txt: Die Python-Pakete, die zum Ausführen des Client-Servers erforderlich sind.

Da adk-python ein großes Repository ist, verwenden Sie die Funktion Sparse Checkout von Git, um nur den Ordner contributing/samples/integrations/gcp_auth/client herunterzuladen:

  1. Wechseln Sie zuerst ein Verzeichnis nach oben aus secure-agent-demo, damit Sie den Client in einen gleichgeordneten Ordner klonen:
    cd ..
    
  2. Führen Sie die folgenden Befehle aus, um die Repository-Metadaten zu klonen, ohne alle Dateien herunterzuladen (--no-checkout), den Checkout-Pfad auf contributing/samples/integrations/gcp_auth/client zu beschränken und nur diesen Ordner auszuchecken:
    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. Wechseln Sie im Verzeichnis adk-python, das Sie gerade aufgerufen haben, zum Ordner client:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Erstellen und aktivieren Sie eine virtuelle Python-Umgebung und installieren Sie dann die Abhängigkeiten des Clients aus requirements.txt:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. Legen Sie die Umgebungsvariablen fest, die den Client auf Ihr Google Cloud-Projekt, Ihre Region (us-central1) und die ID der bereitgestellten Agent Engine (YOUR_ENGINE_ID) verweisen. Starten Sie dann den lokalen FastAPI-Server 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 überwacht wird.

9. OAuth-Ablauf testen

Nachdem alle Dienste bereitgestellt, IAM-Bindungen konfiguriert und Umgebungsvariablen festgelegt wurden, können Sie den sicheren End-to-End-Ablauf für die nutzerdelegierte Autorisierung 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 unter Konfigurationseinstellungen den Agent-Typ auf Remote Agent (Vertex AI) (oder Remote Agent Engine) fest.
  3. Geben Sie Ihre Google Cloud-Projekt-ID und den Standort (us-central1) ein und klicken Sie dann auf Remote-Agenten laden. Dadurch werden die in Ihrem Projekt bereitgestellten Agenten geladen.
  4. Wählen Sie im Drop-down-Menü Engine auswählen den bereitgestellten app-Agenten aus und klicken Sie auf Einstellungen speichern und anwenden.
  5. Geben Sie im Chatfeld eine gezielte Abfrage ein (z. B. zum Abrufen Ihrer letzten Probleme oder Repositories):
    Get the last 2 GitHub issues reported against my name
    
    (Oder versuchen Sie es mit "List my 3 most recently updated repositories") und drücken Sie die Eingabetaste.
  6. Sehen Sie sich die Chat-Benutzeroberfläche an: Da der KI-Agent noch keine Anmeldedaten für Ihre Nutzersitzung hat, erhält er eine Authentifizierungsaufforderung und zeigt die Karte „Authentifizierung erforderlich“ im Unterhaltungsthread an.
  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 weiter. Von dort wird das Pop-up an Ihre localhost-Callback-URL /validateUserId weitergeleitet.
  4. Der Callback-Dienst verarbeitet und schließt den Handshake der Anmeldedaten ab.

Schritt C: Fortsetzen

  1. Sobald das Pop-up-Fenster geschlossen wird, wird dies automatisch im übergeordneten Chat-Tab erkannt.
  2. Das Frontend sendet eine Nutzlast zum Fortsetzen an den Agent zurück.
  3. Der Agent ruft das neu ausgetauschte Token sicher aus dem Google Cloud Auth Manager ab, ruft die GitHub-MCP-Tools in Ihrem Namen auf und streamt Ihre GitHub-Daten 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 Tokenaustausch und die Finalisierung sicher verarbeitet wurden:

  1. Rufen Sie in der Google Cloud Console den Log-Explorer auf.
  2. Suchen Sie die Server-Logs, die die Nonce-Extraktion und die erfolgreiche Validierung bestätigen:
    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 prüfen: Alternativ können Sie Ausführungslogs direkt in der Agent Platform Console ansehen:
    • Rufen Sie die Agent Runtime-Konsole auf.
    • Klicken Sie in der Liste auf Ihren bereitgestellten KI-Agenten.
    • Wechseln Sie zum Tab Playground. Im unteren Bereich werden die Live-Agentenprotokolle angezeigt. Dort sehen Sie die Reasoning Loop des Agenten, Details zur Toolausführung und den Lebenszyklus des Tokenabrufs in Echtzeit.

10. Bereinigen

So vermeiden Sie laufende Kosten in Google Cloud: Bereinigen Sie Ihre bereitgestellten Ressourcen:

# 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 Sie in diesem Lab erstellt haben:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Glückwunsch!

Sie haben einen KI-Agenten erstellt und abgesichert, der im Namen des angemeldeten Nutzers agiert.

Das haben Sie gelernt:

  • Agentensystemidentität: Wie der Agent unter seiner eigenen Kontoidentität arbeitet, um sicher mit der GCP-Infrastruktur zu interagieren, Telemetrielogs zu verwalten und APIs für die Finalisierung von Anmeldedaten aufzurufen.
  • User Delegated Identity: Wie der Agent die Autorisierung anfordert, im Namen des Nutzers auf externen Plattformen (wie GitHub) zu agieren, indem er einen 3-Legged-OAuth-Zustimmungsablauf (3LO) auslöst.
  • Sichere Toolintegration: ADK-Agenten mit Model Context Protocol-Servern (MCP) über Google Cloud Auth Manager verbinden, um Nutzer-Tokens dynamisch abzurufen, anstatt hartcodierte 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