Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren

Wenn Sie Ihrem Agent im Namen eines bestimmten Endnutzers Zugriff auf externe Tools und Dienste (z. B. Jira-Aufgaben oder GitHub-Repositories) gewähren möchten, konfigurieren Sie im Authentifizierungsmanager für die Identität von KI-Agenten einen dreibeinigen OAuth-Authentifizierungsanbieter.

Dreibeinige OAuth-Authentifizierungsanbieter verwalten die Nutzerweiterleitung und Tokens für Sie. So müssen Sie keinen benutzerdefinierten Code schreiben, um komplexe OAuth 2.0-Abläufe zu verarbeiten.

Dreibeiniger OAuth-Workflow

Dreibeinige OAuth-Authentifizierungsanbieter erfordern die Nutzereinwilligung, da der Agent im Namen des Nutzers auf Ressourcen zugreift.

Aufforderung und Weiterleitung: Die Chat-Oberfläche fordert den Nutzer auf, sich anzumelden und leitet ihn dann zur Einwilligungsseite der Drittanbieteranwendung weiter.
Einwilligung und Speicherung: Nachdem der Nutzer die Berechtigung erteilt hat, speichert der Authentifizierungsmanager für die Identität von KI-Agenten die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedatenspeicher.
Einfügung: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Authentifizierungsanbieter ab und fügt es in die Header für den Toolaufruf ein.

Hinweis

Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.
Aktivieren Sie die Agent Identity Connector API.
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen.
API aktivieren
Erstellen und stellen Sie einen Agent bereit.
Sie benötigen eine Front-End-Anwendung, um Nutzeraufforderungen zur Anmeldung und Weiterleitung zu Einwilligungsseiten von Drittanbietern zu verarbeiten.
Prüfen Sie, ob Sie die erforderlichen Rollen haben, um diese Aufgabe auszuführen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwenden eines dreibeinigen Authentifizierungsanbieters benötigen:

Zum Erstellen von Authentifizierungsanbietern:
- IAM Connector-Administrator (roles/iamconnectors.admin)
- IAM Connector-Bearbeiter (roles/iamconnectors.editor)
Zum Verwenden von Authentifizierungsanbietern:
- IAM Connector-Nutzer (roles/iamconnectors.user)
- Vertex AI-Nutzer (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen und Verwenden eines dreibeinigen Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen und Verwenden eines 3-legged Auth-Bereitstellers erforderlich:

Zum Erstellen von Authentifizierungsanbietern: iamconnectors.connectors.create
Zum Verwenden von Authentifizierungsanbietern:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Dreibeinigen Authentifizierungsanbieter erstellen

Erstellen Sie einen Authentifizierungsanbieter, um die Konfiguration und Anmeldedaten für Drittanbieteranwendungen zu definieren.

Verwenden Sie die Google Cloud Console oder die Google Cloud CLI, um einen dreibeinigen Authentifizierungsanbieter zu erstellen.

Console

Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.
Zu Agent Registry
Klicken Sie auf den Namen des Agent, für den Sie einen Authentifizierungsanbieter erstellen möchten.
Klicken Sie auf Identität.
Klicken Sie im Abschnitt Authentifizierungsanbieter auf Authentifizierungsanbieter hinzufügen.
Geben Sie im Bereich Authentifizierungsanbieter hinzufügen einen Namen und eine Beschreibung ein.

Der Name darf nur Kleinbuchstaben, Zahlen oder Bindestriche enthalten, nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.
Wählen Sie in der Liste OAuth-Typ die Option OAuth (3-legged) aus.
Klicken Sie auf Erstellen und fortfahren.
Klicken Sie auf Zugriff erlauben, um der Identität Ihres Agent die Berechtigung zur Verwendung des Authentifizierungsanbieters zu gewähren.
Dadurch wird der Agentenidentität automatisch die Rolle Connector-Nutzer (roles/iamconnectors.user) für die Authentifizierungsanbieterressource zugewiesen.
Kopieren Sie die Rückruf-URL.
Registrieren Sie die Rückruf-URL auf einem separaten Tab in Ihrer OAuth-Clientanwendung eines Drittanbieters.
Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
- Client-ID
- Client-Secret
- Token-URL
- Autorisierungs-URL
Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

gcloud CLI

Konfigurieren Sie Ihre OAuth-Client Anwendung, um Ihren Client zu registrieren und eine Client-ID und ein Client-Secret zu erhalten. Geben Sie den Weiterleitungs-URI mit der Vorlage in diesem Abschnitt an.

Erstellen Sie den Authentifizierungsanbieter mit Ihren Clientanmeldedaten:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste angezeigt wird und der Status ENABLED ist:

gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

Gewähren Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklung Umgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Wenn Sie Ihrem bereitgestellten Agent und Ihrem persönlichen Nutzerkonto Zugriff auf den Authentifizierungsanbieter gewähren möchten, weisen Sie die Rolle Connector-Nutzer (roles/iamconnectors.user) für die Authentifizierungsanbieterressource zu:

Gewähren Sie Zugriff auf die SPIFFE-ID Ihres bereitgestellten Agent (Agentenidentität):

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

Gewähren Sie Zugriff auf Ihr persönliches Nutzerkonto für die lokale Entwicklung und Tests (adk web):

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="user:USER_EMAIL"

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Google Cloud Projekt-ID
LOCATION: Der Standort, an dem Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B. us-west1)
AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters (z. B. bigquery-mcp-3lo-authprovider)
AUTHORIZATION_URL: Die URL des Autorisierungsservers (z. B. https://accounts.google.com/o/oauth2/v2/auth)
TOKEN_URL: Die URL des Token-Servers (z. B. https://oauth2.googleapis.com/token)
CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben
CLIENT_SECRET: Das OAuth-Client-Secret, das Sie vom Drittanbieterdienst generiert haben
ORGANIZATION_ID: Ihre Google Cloud Organisations-ID
PROJECT_NUMBER: Ihre Google Cloud Projektnummer
ENGINE_ID: Die ID Ihres bereitgestellten Reasoning-Engine-Agent
USER_EMAIL: Die E‑Mail-Adresse Ihres persönlichen Nutzerkontos

OAuth-Clientanwendung konfigurieren

Bevor Sie Ihre OAuth-Clientanmeldedaten registrieren, rufen Sie eine Client-ID und ein Client-Secret vom Autorisierungsserver des Drittanbieters ab (z. B. Google, GitHub oder Jira).

Wenn Sie eine Verbindung zu einem Drittanbieterdienst außerhalb von Google Cloudherstellen, rufen Sie die OAuth-Clientanmeldedaten im Entwicklerportal dieses Dienstes ab und überspringen Sie die Schritte in diesem Abschnitt.

Weiterleitungs-URI registrieren

Wenn Sie Ihre OAuth-Clientanmeldedaten konfigurieren, müssen Sie den dedizierten Rückruf-Weiterleitungs-URI des Authentifizierungsanbieters registrieren.

Erstellen Sie den Weiterleitungs-URI mit der folgenden Vorlage:

https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud Projekt-ID
- LOCATION: The region where your auth provider will be deployed (for example,us-west1`)
- CONNECTOR_NAME: Der Name Ihres Authentifizierungsanbieters
Beispiel: https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback
Wenn Sie eine Verbindung zu Google Cloud -Diensten (z. B. BigQuery) herstellen, können Sie den Zustimmungsbildschirm konfigurieren und OAuth Clientanmeldedaten in der Google Cloud Console erstellen:
1. OAuth-Zustimmungsbildschirm konfigurieren:
  1. Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm auf.
    Zu APIs & Dienste >OAuth-Zustimmungsbildschirm
  2. Geben Sie im Abschnitt App-Informationen einen Anwendungsnamen (z. B. „BigQuery Manager Application“) und eine Support-E‑Mail-Adresse ein.
  3. Wählen Sie im Abschnitt Zielgruppe die Option Intern oder Extern aus.
  4. Geben Sie Ihre Kontaktdaten ein, um Benachrichtigungen zu erhalten.
  5. Lesen und akzeptieren Sie die Richtlinie zu Nutzerdaten für Google API-Dienste.
  6. Klicken Sie auf Beenden.
2. Erstellen Sie Ihre OAuth-Clientanmeldedaten:
  1. Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients auf.
    Zu APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients
  2. Klicken Sie auf Anmeldedaten erstellen >OAuth-Client ID.
  3. Wählen Sie in der Liste die Option Webanwendung aus.
  4. Geben Sie einen aussagekräftigen Namen für Ihren OAuth-Client ein.
  5. Klicken Sie im Abschnitt Autorisierte Weiterleitungs-URIs auf URI hinzufügen und geben Sie den erstellten Weiterleitungs-URI ein.
  6. Klicken Sie auf Erstellen. Kopieren Sie im Dialogfeld OAuth-Client erstellt die generierten Werte für Client-ID und Client Secret.

Im Agent-Code authentifizieren

Sie können Ihren Agent mit dem ADK authentifizieren oder die Agent Identity API direkt aufrufen.

ADK

Verweisen Sie im Code Ihres Agent mit dem MCP-Toolset im ADK auf den Authentifizierungsanbieter.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Beispiel: Verbindung zu BigQuery MCP

Im folgenden Beispiel wird eine agent.py-Konfiguration gezeigt, die einen Agent mit dem BigQuery MCP-Server über dreibeiniges OAuth verbindet:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth
from google.genai import types

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

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the callback is received.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/connectors/{bigquery_mcp_auth_provider_id}",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_tools],
)

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

ADK

Verweisen Sie im Code Ihres Agent mit einem authentifizierten Funktionstool im ADK auf den Authentifizierungsanbieter.

import httpx
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

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

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

Verweisen Sie im Code Ihres Agent mit dem MCP-Toolset der Agent Registry im ADK auf den Authentifizierungsanbieter.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/PROJECT_ID/locations/global/mcpServers/agentregistry-00000000-0000-0000-0000-000000000000", auth_scheme=auth_scheme )

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

API direkt aufrufen

Wenn Sie das ADK nicht verwenden, muss Ihr Agent die iamconnectorcredentials.retrieveCredentials API aufrufen, um das Token zu erhalten.

Da es sich um einen mehrstufigen OAuth-Ablauf handelt, gibt die API einen Vorgang mit langer Ausführungszeit (Long Running Operation, LRO) zurück. Ihr Agent muss den Lebenszyklus des Vorgangs verwalten:

Erste Anfrage: Der Agent ruft retrieveCredentials auf.
Einwilligung erforderlich: Wenn der Nutzer keine Einwilligung erteilt hat, gibt die API einen LRO zurück, dessen Metadaten die auth_uri und eine consent_nonce enthalten.
Weiterleitung im Front-End: Ihre Anwendung muss den Nutzer zur auth_uri weiterleiten.
Abschluss: Nachdem der Nutzer die Einwilligung erteilt hat, rufen Sie FinalizeCredential mit der consent_nonce auf, um den Ablauf abzuschließen und das Token zu erhalten.

Clientseitige Anwendung aktualisieren

Um die Nutzeranmeldung und Weiterleitung für dreibeiniges OAuth zu verarbeiten, muss Ihre clientseitige Anwendung die folgenden Schritte ausführen, um die Nutzereinwilligung zu verwalten und die Unterhaltung fortzusetzen:

Beispiel für einen UI-Server

Sie können einen vollständigen Beispiel-UI-Server herunterladen und ausführen, der uvicorn verwendet. Dazu benötigen Sie ein GitHub Konto und pip muss installiert sein.

So richten Sie den Beispiel-UI-Server ein und führen ihn aus:

Klonen Sie das GitHub-Repository adk-python:

git clone https://github.com/google/adk-python.git

Rufen Sie das Repository auf und aktivieren Sie eine virtuelle Python Umgebung:
```
cd adk-python
python3 -m venv .venv
source .venv/bin/activate
```
Rufen Sie das Verzeichnis des Beispiel-UI-Clients auf:
```
cd contributing/samples/integrations/gcp_auth/client
```
Installieren Sie die Clientabhängigkeiten:
```
pip install -r requirements.txt
```
Legen Sie vor dem Starten des Servers die AGENT_PROJECT_DIR Umgebungsvariable fest, um das Verzeichnis anzugeben, in dem sich Ihr Agent-Code befindet. Andernfalls sucht die Anwendung standardmäßig nach Agenten im übergeordneten Ordner des Clientverzeichnisses.

Starten Sie den Beispiel-UI-Server mit uvicorn. Achten Sie darauf, dass der Port mit dem Weiterleitungs-URI übereinstimmt, der in Ihrem OAuth-Client konfiguriert ist:
```
export AGENT_PROJECT_DIR="/path/to/your/agent_project"
uvicorn main:app --port 8501 --reload
```
Öffnen Sie http://localhost:8501 in Ihrem Browser. Hinweis: Sie müssen localhost und nicht 127.0.0.1 verwenden, da dies für die OAuth-Weiterleitungs-URL erforderlich ist. Geben Sie Ihre Einstellungen an, klicken Sie auf Einstellungen speichern und anwenden und interagieren Sie dann mit Ihrem Agent.

Benutzerdefinierte UI-Anwendung

Wenn Sie diese Funktionen direkt in einer benutzerdefinierten UI-Anwendung implementieren möchten, führen Sie die folgenden Schritte aus:

Autorisierungsauslöser verarbeiten
Endpunkt für die Nutzervalidierung implementieren
Unterhaltung mit dem Agent fortsetzen

Autorisierungsauslöser verarbeiten

Wenn ein Agent die Einwilligung des Nutzers benötigt, gibt er einen adk_request_credential-Funktionsaufruf zurück. Ihre Anwendung muss diesen Aufruf abfangen, um ein Dialogfeld zur Nutzerautorisierung zu starten oder eine Weiterleitung auszulösen.

Verwalten Sie den Sitzungskontext, indem Sie die vom Authentifizierungsanbieter bereitgestellte consent_nonce aufzeichnen. Diese Nonce ist erforderlich, um den Nutzer im Validierungsschritt zu bestätigen. Speichern Sie die Werte auth_config und auth_request_function_call_id in der Sitzung, um die Fortsetzung des Ablaufs zu erleichtern, nachdem der Nutzer die Einwilligung erteilt hat.

if (fc := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(fc)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, AUTH_PROVIDER_NAME, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = (
                fc.get('id') if isinstance(fc, dict)
                else getattr(fc, 'id', None)
            )
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    ec = auth_config.exchanged_auth_credential
    if ec and ec.oauth2:
        oauth2 = ec.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Endpunkt für die Nutzervalidierung implementieren

Implementieren Sie einen Validierungsendpunkt auf Ihrem Webserver (derselbe URI, der bei der Konfiguration als continue_uri angegeben wurde). Dieser Endpunkt muss Folgendes tun:

user_id_validation_state und auth_provider_name als Abfrageparameter empfangen.
Die Werte user_id und consent_nonce aus dem Sitzungskontext abrufen.
Die FinalizeCredentials API des Authentifizierungsanbieters mit diesen Parametern aufrufen.
Das Autorisierungsfenster schließen, nachdem eine Erfolgsantwort eingegangen ist.

Beispiel: FastAPI-Validierungsendpunkt (`main.py`)

Im folgenden Beispiel wird ein vollständiger FastAPI-Validierungsendpunkt gezeigt, der den OAuth-Rückruf verarbeitet und die Nutzeranmeldedaten abschließt:

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
    auth_provider_name = request.query_params.get("auth_provider_name")
    session_id = request.cookies.get("session_id")
    session = consent_sessions.get(session_id, {})

    payload = {
        "userId": session.get("user_id"),
        "userIdValidationState": request.query_params.get(
            "user_id_validation_state"
        ),
        "consentNonce": session.get("consent_nonce"),
    }

    base_url = "https://iamconnectorcredentials.googleapis.com/v1alpha"
    finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize"

    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(finalize_url, json=payload)
            resp.raise_for_status()
    except httpx.HTTPError as e:
        err_text = e.response.text if hasattr(e, "response") else str(e)
        status = e.response.status_code if hasattr(e, "response") else 500
        return HTMLResponse(err_text, status_code=status)

    return HTMLResponse("""
        <script>
            window.close();
        </script>
        <p>Success. You can close this window.</p>
    """)

Unterhaltung mit dem Agent fortsetzen

Nachdem der Nutzer die Einwilligung erteilt hat und das Autorisierungsfenster geschlossen wurde, rufen Sie die Werte auth_config und auth_request_function_call_id aus Ihren Sitzungsdaten ab. Wenn Sie die Unterhaltung fortsetzen möchten, fügen Sie diese Details als function_response in eine neue Anfrage an den Agent ein.

if (request.is_auth_resume and session.auth_request_function_call_id
    and session.auth_config):
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Agent bereitstellen

Wenn Sie Ihren Agent in Google Cloudbereitstellen, muss die Agentenidentität aktiviert sein.

Wenn Sie in der Agent Runtime on Gemini Enterprise Agent Platform bereitstellen, verwenden Sie das identity_type=AGENT_IDENTITY Flag:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity]"
        ],
    },
)