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 Agenten einen dreibeinigen OAuth-Authentifizierungsanbieter.

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

Dreibeiniger OAuth-Workflow

Dreibeinige OAuth-Authentifizierungsanbieter erfordern die Einwilligung des Nutzers, 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 Agenten die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedatenspeicher.
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 für den Toolaufruf ein.

Hinweis

Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.
Aktivieren Sie die Agent Identity 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 Aufforderungen zur Nutzeranmeldung und Weiterleitungen 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:
- Agent Identity-Administrator (roles/agentidentity.admin)
- Agent Identity-Bearbeiter (roles/agentidentity.editor)
Zum Verwenden von Authentifizierungsanbietern:
- Agent Identity-Nutzer (roles/agentidentity.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 dreibeinigen Authentifizierungsanbieters erforderlich:

Zum Erstellen von Authentifizierungsanbietern: agentidentity.authProviders.create
Zum Verwenden von Authentifizierungsanbietern:
- agentidentity.authProviders.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.

So erstellen Sie einen dreibeinigen Authentifizierungsanbieter mit der gcloud CLI:

Konfigurieren Sie Ihre OAuth-Client Anwendung, um Ihren Client zu registrieren und eine Client-ID und einen Clientschlüssel 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 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"

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

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

Gewähren Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklung Umgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Damit Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto auf den Authentifizierungsanbieter zugreifen können, weisen Sie der Authentifizierungsanbieterressource die Rolle Agent Identity-Nutzer (roles/agentidentity.user) zu:

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

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"

Gewähren Sie Zugriff auf Ihr persönliches Nutzerkonto für die lokale Entwicklung und das 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 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: 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-Agenten.
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 einen Clientschlüssel 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 Callback-Weiterleitungs-URI des Authentifizierungsanbieters registrieren.

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
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. Wechseln Sie in der Google Cloud Console zur Seite APIs & Dienste >OAuth-Zustimmungsbildschirm.
    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 Richtlinie zu Nutzerdaten für Google API-Dienste.
  6. Klicken Sie auf Beenden.
2. Erstellen Sie Ihre OAuth-Clientanmeldedaten:
  1. Wechseln Sie in der Google Cloud Console zur Seite APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients.
    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 Bereich 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

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 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

Im folgenden Beispiel wird eine agent.py-Konfiguration gezeigt, die einen Agent 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 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/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 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 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:

Erste Anfrage: Der Agent ruft retrieveCredentials auf.
Einwilligung erforderlich: Wenn der Nutzer keine Einwilligung erteilt hat, gibt die API eine Antwort zurück, in der das Ergebnis als uri_consent_required angegeben ist. Diese Antwort enthält authorization_uri und ein consent_nonce.
Weiterleitung im Front-End: Ihre Anwendung muss den Nutzer zu authorization_uri weiterleiten.
Abschluss: Nachdem der Nutzer die Einwilligung erteilt hat, rufen Sie FinalizeCredentials mit dem 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

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

Wechseln Sie zum Repository und aktivieren Sie eine virtuelle Python-Umgebung:
```
cd adk-python
python3 -m venv .venv
source .venv/bin/activate
```

Wechseln Sie zum Verzeichnis des Beispiel-UI-Clients:

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 die OAuth-Weiterleitungs-URL speziell den Hostnamen localhost erfordert. 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:

Autorisierungstrigger verarbeiten
Endpunkt für die Nutzervalidierung implementieren
Unterhaltung mit dem Agent fortsetzen

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 Dialogfeld zur Nutzerautorisierung zu starten oder eine Weiterleitung auszulösen.

Verwalten Sie den Sitzungskontext, indem Sie die consent_nonce aufzeichnen, die vom Authentifizierungsanbieter bereitgestellt wird. 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 während der Konfiguration als continue_uri angegeben wurde). Dieser Endpunkt muss Folgendes tun:

user_id_validation_state, auth_provider_name und uuid als Abfrageparameter empfangen.
Die Werte user_id und consent_nonce aus Ihrem Sitzungsspeicher abrufen. Wenn mehrere Autorisierungsabläufe gleichzeitig ausgeführt werden, verwenden Sie die uuid, um die richtige Sitzung zu finden.
Rufen Sie die FinalizeCredentials API des Authentifizierungsanbieters mit diesen Parametern auf.
Schließen Sie das Autorisierungsfenster, nachdem Sie eine Erfolgsmeldung erhalten haben.

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

Im folgenden Beispiel wird ein vollständiger FastAPI-Validierungsendpunkt gezeigt, 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>
    """)

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