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 Agent Identity-Authentifizierungsmanager einen 3-Legged-OAuth-Authentifizierungsanbieter.

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

Dreibeiniger OAuth-Workflow

Bei dreibeinigen OAuth-Authentifizierungsanbietern ist die Nutzereinwilligung erforderlich, da der Agent im Namen des Nutzers auf Ressourcen zugreift.

  1. Aufforderung und Weiterleitung: Die Chat-Oberfläche fordert den Nutzer auf, sich anzumelden, und leitet ihn dann zur Zustimmungsseite 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. Injektion: 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, falls sie noch nicht aktiviert ist.

    Erforderliche Rollen zum Aktivieren von APIs

    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 Inhaberrolle (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 Nutzeraufforderungen zur Anmeldung und Weiterleitungen zu Einwilligungsseiten von Drittanbietern 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 zum Erstellen und Verwenden eines 3-Legged-Authentifizierungsanbieters erforderlich:

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

3-Legged-Authentifizierungsanbieter erstellen

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

Zum Erstellen eines 3-Legged-Authentifizierungsanbieters können Sie die Google Cloud Console, die Google Cloud CLI oder die REST API verwenden.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.

    Zur Agent Registry

  2. Klicken Sie auf den Namen des KI-Agenten, für den Sie einen Authentifizierungsanbieter erstellen möchten.
  3. Klicken Sie auf Identität.
  4. Klicken Sie im Bereich Authentifizierungsanbieter auf Authentifizierungsanbieter hinzufügen.

  5. Geben Sie im Bereich Authentifizierungsanbieter hinzufügen einen Namen und eine Beschreibung ein.

    Der Name darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, darf nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.

  6. Wählen Sie in der Liste OAuth-Typ die Option OAuth (dreibeinig) aus.
  7. Klicken Sie auf Erstellen und fortfahren.
  8. Klicken Sie auf Zugriff gewähren, um der Agentenidentität die Berechtigung zur Verwendung des Authentifizierungsanbieters zu erteilen.

    Bei diesem Vorgang wird der Agentenidentität automatisch die Rolle Agent Identity User (roles/agentidentity.user) für die Authentifizierungsanbieterressource zugewiesen.

  9. Kopieren Sie die Callback-URL.
  10. Registrieren Sie die Callback-URL in Ihrer OAuth-Clientanwendung eines Drittanbieters in einem separaten Tab.
  11. Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
    • Client-ID
    • Clientschlüssel
    • Token-URL
    • Autorisierungs-URL
    • Standard-URI für „Weiter“: Optional. Geben Sie einen Standard-Weiterleitungs-URI ein, zu dem Nutzer weitergeleitet werden, nachdem sie ihre Einwilligung erteilt haben, wenn zur Laufzeit kein URI für „Weiter“ angegeben wird.
  12. Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

gcloud-CLI

  1. Konfigurieren Sie Ihre OAuth-Clientanwendung, um Ihren Client zu registrieren und eine Client-ID und einen Clientschlüssel zu erhalten. Geben Sie den Weiterleitungs-URI mithilfe der Vorlage in diesem Abschnitt an.

  2. Erstellen Sie den Authentifizierungsanbieter mit Ihren Clientanmeldedaten:

    gcloud agent-identity auth-providers 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" \
    --three-legged-oauth-default-continue-uri="DEFAULT_CONTINUE_URI"

    Ersetzen Sie Folgendes:

    • AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters.
    • PROJECT_ID: Ihre Google Cloud -Projekt-ID
    • LOCATION: Die Region, in der der Authentifizierungsanbieter erstellt wird.
    • CLIENT_ID: Die Client-ID Ihrer OAuth-Clientanwendung.
    • CLIENT_SECRET: Der Clientschlüssel Ihrer OAuth-Clientanwendung.
    • AUTHORIZATION_URL: Der Endpunkt des Autorisierungsservers, an den Nutzer weitergeleitet werden, um ihre Einwilligung zu erteilen.
    • TOKEN_URL: Der Tokenaustausch-Endpunkt auf dem Autorisierungsserver.
    • DEFAULT_CONTINUE_URI: Optional. Der Standard-Weiterleitungs-URI, an den Nutzer nach der Einwilligung weitergeleitet werden. Er wird verwendet, wenn zur Laufzeit kein Fortsetzungs-URI angegeben wird.
  3. Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste aufgeführt ist und den Status ENABLED hat: 
    gcloud agent-identity auth-providers 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 der Authentifizierungsanbieter-Ressource die Rolle Agent Identity User (roles/agentidentity.user) zu:

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

      gcloud agent-identity auth-providers 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 Ihrem persönlichen Nutzerkonto Zugriff für die lokale Entwicklung und Tests (adk web):

      gcloud agent-identity auth-providers 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 über den Drittanbieterdienst generiert haben.
  • CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie über den Drittanbieterdienst generiert haben.
  • ORGANIZATION_ID: Ihre Organisations-ID von Google Cloud .
  • PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.
  • ENGINE_ID: Die ID des bereitgestellten Reasoning-Engine-Agenten.
  • USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.

REST

  1. Konfigurieren Sie Ihre OAuth-Clientanwendung, um Ihren Client zu registrieren und eine Client-ID und einen Clientschlüssel zu erhalten. Geben Sie den Weiterleitungs-URI mithilfe der Vorlage in diesem Abschnitt an.

  2. Erstellen Sie den Authentifizierungsanbieter:

    Mit der Methode authProviders.create der Agent Identity API wird ein dreibeiniger OAuth-Authentifizierungsanbieter in einem Projekt und an einem Standort erstellt.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • PROJECT_ID: Ihre Google Cloud -Projekt-ID. Projekt-IDs sind alphanumerische Strings, wie my-project.
    • 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). Der Name darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, darf nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.
    • CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben.
    • CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie über den Drittanbieterdienst generiert haben.
    • AUTHORIZATION_URL: Die URL des Autorisierungsservers (z. B. https://accounts.google.com/o/oauth2/v2/auth).
    • TOKEN_URL: Die URL des Tokenservicesservers (z. B. https://oauth2.googleapis.com/token).
    • DEFAULT_CONTINUE_URI: Optional. Der Standard-URI, an den Nutzer weitergeleitet werden, nachdem sie ihre Einwilligung erteilt haben, wenn Sie zur Laufzeit keinen Weiterleitungs-URI angeben.

    HTTP-Methode und URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

    JSON-Text anfordern:

    {
  "authProviderTypeParams": {
    "threeLeggedOauth": {
      "clientId": "CLIENT_ID",
      "clientSecret": "CLIENT_SECRET",
      "authorizationUrl": "AUTHORIZATION_URL",
      "tokenUrl": "TOKEN_URL",
      "defaultContinueUri": "DEFAULT_CONTINUE_URI"
    }
  }
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    {
  "name": "projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider",
  "createTime": "2026-04-03T21:15:41.367155Z",
  "updateTime": "2026-04-03T21:15:41.367155Z",
  "authProviderTypeParams": {
    "threeLeggedOauth": {
      "clientId": "my-oauth-client-id",
      "redirectUrl": "https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback",
      "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUrl": "https://oauth2.googleapis.com/token",
      "defaultContinueUri": "http://localhost:8501/validateUserId"
    }
  },
  "state": "ENABLED"
}

  3. Damit Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto Anmeldedaten vom Authentifizierungsanbieter abrufen können, weisen Sie der Authentifizierungsanbieter-Ressource die Rolle Agent Identity User (roles/agentidentity.user) zu:

    Mit der Methode authProviders.setIamPolicy der Agent Identity API wird die Zulassungsrichtlinie für die Authentifizierungsanbieter-Ressource festgelegt.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • PROJECT_ID: Ihre Google Cloud -Projekt-ID. Projekt-IDs sind alphanumerische Strings, wie my-project.
    • LOCATION: Der Standort, an dem Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B. us-west1).
    • AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters.
    • ORGANIZATION_ID: Ihre Organisations-ID von Google Cloud.
    • PROJECT_NUMBER: Die numerische Google Cloud -Projektnummer des Projekts, in dem Ihr Agent bereitgestellt wird (z. B. 987654321098).
    • ENGINE_ID: Die ID des bereitgestellten Reasoning Engine-Agenten.
    • USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.

    HTTP-Methode und URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

    JSON-Text anfordern:

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/agentidentity.user",
        "members": [
          "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
          "user:USER_EMAIL"
        ]
      }
    ]
  }
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    {
  "version": 1,
  "etag": "BwYKmjvelug=",
  "bindings": [
    {
      "role": "roles/agentidentity.user",
      "members": [
        "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
        "user:alex@example.com"
      ]
    }
  ]
}

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 aus dem Entwicklerportal dieses Dienstes ab und überspringen Sie die Schritte in diesem Abschnitt.

Weiterleitungs-URI registrieren

Wenn Sie die Anmeldedaten für Ihren OAuth-Client 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/v1/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/v1/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 Zustimmungsbildschirm konfigurieren und OAuth-Client-Anmeldedaten in der Google Cloud Console erstellen:

    1. Konfigurieren Sie den OAuth-Zustimmungsbildschirm:

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

        Zu „APIs & Dienste“ > „OAuth-Zustimmungsbildschirm“

      2. Geben Sie im Abschnitt App-Informationen einen Anwendungsnamen (z. B. BigQuery Manager-Anwendung) 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. Rufen Sie in der Google Cloud Console die Seite APIs und Dienste > OAuth-Zustimmungsbildschirm > Clients auf.

        Rufen Sie „APIs und 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 Agentencode authentifizieren

Zum Authentifizieren Ihres KI-Agenten können Sie das ADK verwenden oder die Agent Identity API direkt aufrufen.

Wenn Ihre Anwendung Anmeldedaten anfordert, gibt sie einen continue_uri an, zu dem Nutzer nach der Einwilligung weitergeleitet werden. Wenn Sie beim Erstellen des Authentifizierungsanbieters eine default_continue_uri konfiguriert haben, ist die Angabe von continue_uri in Ihrem Agent-Code optional.

ADK

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

from google.adk.agents import Agent
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.
# Optional if default_continue_uri is configured on the auth provider.
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 = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME (ex. 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/AUTH_PROVIDER_NAME",
    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 import Agent
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 = Agent(
    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 „Agent Registry“ im ADK auf den Authentifizierungsanbieter.

Sie erstellen kein Authentifizierungsschema für diesen Ablauf. In der ausgehenden Bindung des MCP-Servers ist bereits festgelegt, welcher Authentifizierungsanbieter verwendet werden soll. Übergeben Sie continue_uri, um anzugeben, wohin der Nutzer nach der Einwilligung weitergeleitet werden soll.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
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"

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    continue_uri=CONTINUE_URI,
)

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

API direkt aufrufen

Wenn Sie das ADK nicht verwenden, muss Ihr KI-Agent die agentidentitycredentials.retrieveCredentials API aufrufen, um das Token abzurufen.

Da es sich um einen mehrstufigen OAuth-Vorgang handelt, muss dein Agent den Lebenszyklus des Vorgangs verwalten:

  1. Erste Anfrage: Der KI-Agent ruft retrieveCredentials auf.
  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 die authorization_uri weiterleiten.
  4. Abschluss: Nachdem der Nutzer seine Einwilligung erteilt hat, rufen Sie FinalizeCredentials mit dem consent_nonce auf, um den Vorgang abzuschließen und das Token abzurufen.

Clientseitige Anwendung aktualisieren

Damit die Nutzeranmeldung und die Weiterleitung für 3-Legged OAuth verarbeitet werden können, 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, benötigen Sie ein GitHub-Konto und müssen pip installiert haben.

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. Rufen Sie das Verzeichnis des Beispiel-UI-Clients auf:

    cd contributing/samples/integrations/gcp_auth/client

  4. Installieren Sie die Clientabhängigkeiten:

    pip install -r requirements.txt

  5. Legen Sie vor dem Starten des Servers 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 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

  6. Ö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 den Hostnamen localhost erfordert.) Legen Sie die Einstellungen fest, klicken Sie auf Einstellungen speichern und anwenden und interagieren Sie dann mit dem Agenten.

Benutzerdefinierte UI-Anwendung

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

Autorisierungstrigger verarbeiten

Wenn ein Agent die Nutzereinwilligung benötigt, gibt er einen adk_request_credential-Funktionsaufruf zurück. Ihre Anwendung muss diesen Aufruf abfangen, um ein Dialogfeld für die Nutzerautorisierung oder eine Weiterleitung zu initiieren.

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 verifizieren. 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 Nutzervalidierung implementieren

Implementiere einen Validierungsendpunkt auf deinem Webserver (dieselbe URI, die bei 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 Ihrem Sitzungsspeicher ab. Wenn mehrere Autorisierungsabläufe gleichzeitig ausgeführt werden, verwenden Sie die uuid, um die richtige Sitzung zuzuordnen.
  3. Rufen Sie die FinalizeCredentials-API des Authentifizierungsanbieters mit diesen Parametern auf.
  4. Schließen Sie das Autorisierungsfenster, wenn Sie eine Erfolgsmeldung erhalten.
Beispiel: FastAPI-Validierungsendpunkt (main.py)

Das folgende Beispiel zeigt einen vollständigen FastAPI-Validierungsendpunkt, der den OAuth-Callback verarbeitet und die Nutzeranmeldedaten finalisiert:

@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/v1"
    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 Agenten 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 Agenten 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 KI-Agenten in Google Cloudbereitstellen, muss die Agentenidentität aktiviert sein.

Agent CLI

Wenn Sie das Agent Development Kit (ADK) und die Agent CLI verwenden, gehen Sie so vor, um Ihren KI-Agenten mit aktivierter Agent Identity bereitzustellen:

  1. Erstellen Sie im Ordner Ihrer Agent-Anwendung eine Konfigurationsdatei mit dem Namen .agent_engine_config.json, um die Agent-Identität zu aktivieren:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. Stellen Sie Ihren Agenten in der Agent Runtime auf der Gemini Enterprise Agent Platform bereit:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Ersetzen Sie Folgendes:

    • AGENT_NAME: Der Name des Ordners Ihrer Agent-Anwendung (z. B. maps_agent).
    • PROJECT_ID: Ihre Projekt-ID in Google Cloud.
    • LOCATION: Die unterstützte Region, in der Sie den Agent bereitstellen möchten (z. B. us-west1).

Python SDK

Wenn Sie die Bereitstellung programmatisch mit dem Vertex AI Python SDK durchführen, verwenden Sie das Flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# 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")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(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,mcp]>=2.7.1",
        ],
    },
)

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID.
  • LOCATION: Die unterstützte Region, in der Sie den Agent bereitstellen möchten (z. B. us-west1).

Nächste Schritte