Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren

Wenn Sie Ihrem KI-Agenten 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 Authentifizierungsanbieter für das dreibeinige OAuth.

Durch die Verwaltung von Anmeldedaten und Tokens machen dreibeinige OAuth-Authentifizierungsanbieter benutzerdefinierten Code für die Verarbeitung von Authentifizierungsabläufen überflüssig.

Dreibeiniger OAuth-Ablauf

Für 3-legged OAuth-Authentifizierungsanbieter ist die Einwilligung des Nutzers erforderlich, da der Agent im Namen des Nutzers auf Ressourcen zugreift.

  1. Aufforderung und Weiterleitung: Die Chatoberfläche fordert den Nutzer auf, sich anzumelden, und leitet ihn dann zur Einwilligungsseite der Drittanbieteranwendung weiter.
  2. Einwilligung und Speicherung: Nachdem der Nutzer die Berechtigung erteilt hat, speichert der Agent Identity-Authentifizierungsmanager die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedatenspeicher.
  3. Einfügen: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Authentifizierungsanbieter ab und fügt es in die Header des Toolaufrufs ein.

Hinweis

  1. Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.

  2. Aktivieren Sie die Agent Identity API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    API aktivieren

  3. Agent erstellen und bereitstellen.
  4. Sie benötigen eine Frontend-Anwendung, um Nutzeranmeldeaufforderungen und Weiterleitungen zu Drittanbieter-Einwilligungsseiten zu verarbeiten.
  5. Prüfen Sie, ob Sie die Rollen haben, die für diese Aufgabe erforderlich sind.

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 3-Legged-Authentifizierungsanbieters benötigen:

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 3-Legged-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen 3-Legged-Authentifizierungsanbieter zu erstellen und zu verwenden:

  • So erstellen Sie Authentifizierungsanbieter: agentidentity.authProviders.create
  • So verwenden Sie Authentifizierungsanbieter:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

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

Anbieter für die 3-legged-Authentifizierung erstellen

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

So erstellen Sie einen Anbieter für die 3-legged-Authentifizierung mit der gcloud CLI:

  1. Konfigurieren Sie Ihre OAuth-Clientanwendung, 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.

  2. Erstellen Sie den Authentifizierungsanbieter mit Ihren Clientanmeldedaten:

    gcloud alpha agent-identity authProviders 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"
  3. Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste aufgeführt ist und den Status ENABLED hat: 
    gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  4. Gewähren Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklungsumgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Damit Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto auf den Authentifizierungsanbieter zugreifen können, weisen Sie die Rolle Agent Identity User (roles/agentidentity.user) für die Authentifizierungsanbieterressource zu:

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

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

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

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der Ort, 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 Token-Server-URL (z. B. https://oauth2.googleapis.com/token).
  • CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben.
  • CLIENT_SECRET: Der OAuth-Clientschlüssel, den 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-Agents.
  • USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.

OAuth-Clientanwendung konfigurieren

Bevor Sie Ihre OAuth-Clientanmeldedaten registrieren, müssen Sie eine Client-ID und einen Clientschlüssel vom Autorisierungsserver des Drittanbieters (z. B. Google, GitHub oder Jira) abrufen.

Wenn Sie eine Verbindung zu einem Drittanbieterdienst außerhalb vonGoogle Cloudherstellen, rufen Sie die OAuth-Clientanmeldedaten über das 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 Callback-Weiterleitungs-URI des Authentifizierungsanbieters registrieren.

  1. Erstellen Sie den Weiterleitungs-URI mit der folgenden Vorlage:

    https://agentidentitycredentials.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/oauthcallback

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • LOCATION: Die Region, in der Ihr Authentifizierungsanbieter bereitgestellt wird, z. B. us-west1.
    • AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters.

    Beispiel: https://agentidentitycredentials.googleapis.com/v1alpha/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback

  2. Wenn Sie eine Verbindung zu Google Cloud -Diensten (z. B. BigQuery) herstellen, können Sie den Einwilligungsbildschirm konfigurieren und OAuth-Clientanmeldedaten in der Google Cloud -Konsole 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 Bereich App-Informationen einen Anwendungsnamen (z. B. „BigQuery Manager Application“) und eine Support-E-Mail-Adresse ein.
      3. Wählen Sie im Bereich Zielgruppe die Option Intern oder Extern aus.
      4. Geben Sie Ihre Kontaktdaten ein, um Benachrichtigungen zu erhalten.
      5. Lesen und akzeptieren Sie die Nutzerdatenrichtlinie für Google API-Dienste.
      6. Klicken Sie auf Beenden.

    2. OAuth-Clientanmeldedaten erstellen:

      1. Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients auf.

        Rufen Sie „APIs & Dienste“ > „OAuth-Zustimmungsbildschirm“ >„Clients“ auf.

      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 Clientschlüssel.

Im Agent-Code authentifizieren

Zur Authentifizierung Ihres Agenten können Sie das ADK verwenden oder die Agent Identity API direkt aufrufen.

ADK

Verweisen Sie im Code Ihres KI-Agenten 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 Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/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 herstellen

Das folgende Beispiel zeigt eine agent.py-Konfiguration, die einen Agenten mit dem BigQuery-MCP-Server 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
CredentialManager.register_auth_provider(GcpAuthProvider())

# URI to redirect user to after consent is granted.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/authProviders/{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 KI-Agenten 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/authProviders/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 KI-Agenten mit dem MCP-Toolset für die Agent-Registrierung 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 scheme
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/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 agentidentitycredentials.retrieveCredentials API aufrufen, um das Token zu erhalten.

Da es sich um einen mehrstufigen OAuth-Ablauf handelt, muss Ihr Agent den Lebenszyklus des Vorgangs verarbeiten:

  1. Erste Anfrage: Der Kundenservicemitarbeiter ruft retrieveCredentials an.
  2. Einwilligung erforderlich: Wenn der Nutzer keine Einwilligung erteilt hat, gibt die API eine Antwort mit dem Ergebnis uri_consent_required zurück. Diese enthält authorization_uri und eine consent_nonce.
  3. Frontend-Weiterleitung: Ihre Anwendung muss den Nutzer an authorization_uri weiterleiten.
  4. Abschluss: Nachdem der Nutzer die Einwilligung erteilt hat, rufen Sie FinalizeCredentials mit consent_nonce auf, um den Ablauf abzuschließen und das Token zu erhalten.

Clientseitige Anwendung aktualisieren

Um die Nutzeranmeldung und ‑weiterleitung für 3-Legged-OAuth zu verarbeiten, muss Ihre clientseitige Anwendung die folgenden Schritte ausführen, um die Nutzereinwilligung zu verwalten und die Unterhaltung fortzusetzen:

Beispiel-UI-Server

Sie können einen vollständigen Beispiel-UI-Server herunterladen und ausführen, der uvicorn verwendet. Bevor Sie beginnen, müssen Sie ein GitHub-Konto haben und pip installiert sein.

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

  1. Klonen Sie das GitHub-Repository adk-python:

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

  2. Rufen Sie das Repository auf und aktivieren Sie eine virtuelle Python-Umgebung:

    cd adk-python
python3 -m venv .venv
source .venv/bin/activate

  3. Wechseln Sie zum Verzeichnis des Beispiel-UI-Clients:

    cd contributing/samples/integrations/gcp_auth/client

  4. Installieren Sie die Clientabhängigkeiten:

    pip install -r requirements.txt

  5. Bevor Sie den Server starten, legen Sie die Umgebungsvariable AGENT_PROJECT_DIR fest, um das Verzeichnis anzugeben, in dem sich Ihr Agent-Code befindet. Andernfalls sucht die Anwendung standardmäßig im übergeordneten Ordner des Clientverzeichnisses nach Agents.

    Starten Sie den Beispiel-UI-Server mit uvicorn. Achten Sie darauf, dass der Port mit dem in Ihrem OAuth-Client konfigurierten Weiterleitungs-URI übereinstimmt:

    export AGENT_PROJECT_DIR="/path/to/your/agent_project"
uvicorn main:app --port 8501 --reload

  6. Öffnen Sie http://localhost:8501 in Ihrem Browser. Hinweis: Sie müssen localhost und nicht 127.0.0.1 verwenden, da für die OAuth-Weiterleitungs-URL der Hostname localhost erforderlich ist. Legen Sie die Einstellungen fest, klicken Sie auf Speichern und Einstellungen übernehmen und interagieren Sie dann mit dem Agent.

Anwendung mit benutzerdefinierter Benutzeroberfläche

So implementieren Sie diese Funktionen direkt in einer benutzerdefinierten UI-Anwendung:

Autorisierungstrigger 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 Nutzerautorisierungsdialogfeld 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 während des Validierungsschritts zu bestätigen. Speichern Sie die Werte auth_config und auth_request_function_call_id in der Sitzung, damit der Ablauf fortgesetzt werden kann, 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 Nutzerüberprüfung implementieren

Implementieren Sie einen Validierungs-Endpunkt auf Ihrem Webserver (derselbe URI, der während der Konfiguration als continue_uri angegeben wurde). Dieser Endpunkt muss Folgendes tun:

  1. user_id_validation_state, auth_provider_name und uuid als Abfrageparameter empfangen.
  2. Rufen Sie die Werte user_id und consent_nonce aus dem Sitzungsspeicher ab. Wenn mehrere Autorisierungsabläufe gleichzeitig ausgeführt werden, verwenden Sie uuid, um die richtige Sitzung abzugleichen.
  3. Rufen Sie die FinalizeCredentials-API des Authentifizierungsanbieters mit diesen Parametern auf.
  4. Schließen Sie das Autorisierungsfenster, nachdem Sie eine Erfolgsmeldung erhalten haben.
Beispiel: FastAPI-Validierungsendpunkt (main.py)

Das folgende Beispiel zeigt einen vollständigen FastAPI-Validierungsendpunkt, der den OAuth-Callback 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://agentidentitycredentials.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>
    """)

Agent-Unterhaltung 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 in einer neuen Anfrage an den Kundenservicemitarbeiter als function_response 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 Agenten in Google Cloudbereitstellen, muss die Agentenidentität aktiviert sein.

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

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]"
        ],
    },
)

Nächste Schritte