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

Mit einem API-Schlüssel und dem Auth-Manager authentifizieren

Wenn sich Ihre Agenten bei externen Tools wie Google Maps oder Weather APIs authentifizieren sollen, konfigurieren Sie die ausgehende Authentifizierung mit API-Schlüssel-Authentifizierungsanbietern im Authentifizierungsmanager für Agent Identity.

API-Schlüssel-Authentifizierungsanbieter verwalten Ihre kryptografischen Schlüssel für Sie. So müssen Sie Schlüssel nicht mehr fest im Code Ihres Agenten codieren oder manuell verwalten.

API-Schlüssel-Workflow

API-Schlüssel-Authentifizierungsanbieter verwenden die Identität des Agenten und erfordern keine Nutzereinwilligung. Google ergreift Maßnahmen, um den API-Schlüssel während der Speicherung zu schützen. Wenn Sie das Agent Development Kit (ADK) verwenden, wird der API-Schlüssel automatisch abgerufen und in die Header für den Toolaufruf eingefügt.

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 Agenten bereit.
Rufen Sie einen API-Schlüssel vom Drittanbieterdienst ab, mit dem Sie eine Verbindung herstellen möchten.
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 API-Schlüssel-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 API-Schlüssel-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen API-Schlüssel-Authentifizierungsanbieter zu erstellen und zu verwenden:

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.

API-Schlüssel vom Drittanbieterdienst abrufen

Bevor Sie einen Authentifizierungsanbieter erstellen, rufen Sie einen API-Schlüssel vom Drittanbieterdienst ab, mit dem sich Ihr Agent verbinden soll.

Wenn Sie eine Verbindung zu einem Drittanbieterdienst außerhalb von Google Cloud, herstellen, rufen Sie den API-Schlüssel im Entwicklerportal dieses Dienstes ab und überspringen Sie die Schritte in diesem Abschnitt.

Wenn Sie eine Verbindung zu Google Cloud Diensten (z. B. Cloud Translation oder Google Maps) herstellen, können Sie einen API-Schlüssel generieren und konfigurieren. Führen Sie dazu die folgenden Schritte aus:

Aktivieren Sie in der Google Cloud Console die erforderlichen API-Dienste für Ihr Projekt:
1. Rufen Sie in der Google Cloud Console die Seite APIs und Dienste >Bibliothek auf.
  Zu „APIs und Dienste“ >„Bibliothek“
2. Suchen Sie nach den APIs, die Ihr Agent verwendet, z. B. die Cloud Translation API oder die Google Maps Weather API, und aktivieren Sie sie.
3. Kopieren Sie die generierte API-Schlüsselstring.
Konfigurieren Sie Ihren API-Schlüssel:
1. Rufen Sie in der Google Cloud Console die Seite APIs und Dienste >Anmeldedaten auf.
  Zu „APIs und Dienste“ >„Anmeldedaten“
2. Klicken Sie auf Anmeldedaten erstellen >API-Schlüssel.
3. Führen Sie im Dialogfeld API-Schlüssel erstellen folgende Schritte aus:
  1. Geben Sie einen eindeutigen Namen für Ihren API-Schlüssel ein.
  2. Wenn Sie den Schlüssel auf die von Ihnen aktivierten APIs beschränken möchten, wählen Sie diese APIs in der Liste API-Einschränkungen auswählen aus.
  3. Optional: Wählen Sie im Abschnitt Schlüssel einschränken, um Sicherheitsrisiken zu reduzieren einen Anwendungstyp aus, um den Zugriff einzuschränken.
  4. Klicken Sie auf Erstellen.
Prüfen Sie Ihren API-Schlüssel, indem Sie eine Testanfrage an den Dienstendpunkt senden.
- Führen Sie den folgenden Befehl aus, um einen Cloud Translation API-Schlüssel zu prüfen:
```
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -d '{"q": "Hello world", "target": "es"}' \
  "https://translation.googleapis.com/language/translate/v2"
```
  Ersetzen Sie YOUR_API_KEY durch den von Ihnen generierten API-Schlüssel.
- Führen Sie den folgenden Befehl aus, um einen Google Maps Weather API-Schlüssel zu prüfen:
```
curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"
```
  Ersetzen Sie YOUR_API_KEY durch den von Ihnen generierten API-Schlüssel.
Wenn der API-Schlüssel gültig und richtig konfiguriert ist, gibt der Dienst die angeforderten Daten zurück.

API-Schlüssel-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 API-Schlüssel-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 Agenten, 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 API-Schlüssel aus.
Klicken Sie auf Erstellen und fortfahren.
Klicken Sie auf Zugriff erlauben, um der Identität Ihres Agenten 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.
Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters den API-Schlüssel ein.
Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

Google Cloud CLI

Erstellen Sie den Authentifizierungsanbieter:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --api-key="API_KEY"

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 Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto auf den Authentifizierungsanbieter zugreifen sollen, gewähren Sie die Rolle Connector-Nutzer (roles/iamconnectors.user) für die Authentifizierungsanbieterressource:

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

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 das Testen (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 für Ihren Authentifizierungsanbieter (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 Tokenservers (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

Im Agentencode authentifizieren

Sie können das ADK verwenden, um Ihren Agenten zu authentifizieren.

ADK

Verweisen Sie im Code Ihres 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 the Google Cloud auth provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud auth provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

# 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 Google Maps MCP

Das folgende Beispiel zeigt eine agent.py-Konfiguration, die einen Agenten mit einem Google Maps-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

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

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

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

maps_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://mapstools.googleapis.com/mcp"),
    auth_scheme=maps_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction="You are a helpful AI assistant designed to provide accurate and useful information. You can also use your Google Maps tools to look up locations and directions.",
    tools=[maps_tools],
)

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

ADK

Verweisen Sie im Code Ihres 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())

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

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

Beispiel: Verbindung zur Google Maps Weather API

Das folgende Beispiel zeigt eine agent.py-Konfiguration, die einen Agenten mit der Google Maps Weather API verbindet. Dazu wird ein authentifiziertes Funktionstool verwendet:

import os
import httpx
from google.adk.agents import Agent
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.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

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

weather_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets the current weather conditions for a location using latitude and longitude."""
    api_key = None
    if http := credential.http:
        if http.additional_headers and "X-GOOG-API-KEY" in http.additional_headers:
            api_key = http.additional_headers["X-GOOG-API-KEY"]
        elif http.credentials and http.credentials.token:
            api_key = http.credentials.token

    if not api_key:
        return "Error: No API key available from the auth provider."

    params = {"location.latitude": latitude, "location.longitude": longitude, "key": api_key}
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://weather.googleapis.com/v1/currentConditions:lookup",
            params=params,
        )
        if response.status_code != 200:
            return f"Error from Weather API: {response.status_code} - {response.text}"
        return response.json()

get_weather_tool = AuthenticatedFunctionTool(
    func=get_weather, auth_config=weather_auth_config
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction="You are a helpful AI assistant. You will use your weather tool to look up current conditions.",
    tools=[get_weather_tool],
)

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

ADK

Verweisen Sie im Code Ihres Agenten 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())

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

# 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],
)

Agent bereitstellen

Wenn Sie Ihren Agenten in Google Cloudbereitstellen, muss Agent Identity aktiviert sein.

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