Authentifizierung für Tools und Ressourcen

Wenn ein Orchestrator-Agent einen Remote-Agenten oder ein MCP-Toolset (Model Context Protocol) aufruft, das über die Agent Registry ermittelt wurde, muss er sich beim zugrunde liegenden Dienst authentifizieren, der diese Funktionen bereitstellt.

In diesem Dokument wird beschrieben, wie Sie die Authentifizierung für Agent Registry-Ressourcen verwalten.

Hinweis

Bevor Sie sich bei Tools und Ressourcen authentifizieren, müssen Sie Folgendes tun:

  1. Agent Registry in Ihrem Projekt einrichten

  2. Installieren Sie die neueste Version des Agent Development Kit (ADK) oder führen Sie ein Upgrade darauf durch:

    pip install --upgrade google-adk

    Sie müssen ein Upgrade auf mindestens google-adk>=1.29.0 durchführen.

  3. Wenn Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für die Authentifizierung verwenden möchten, müssen Sie sie konfigurieren:

    gcloud auth application-default login

    ADC-Anmeldedaten müssen die erforderlichen IAM-Berechtigungen für die zugrunde liegenden Dienste haben, mit denen die Agents oder Tools interagieren.

  4. Wenn Sie die Beispiele in dieser Anleitung nachvollziehen möchten, müssen Sie Umgebungsvariablen einrichten, z. B.:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Projekt-ID.
    • LOCATION: die Region oder der Standort der Registry, z. B. us-central1.
    • EXTERNAL_API_KEY: Wenn Sie benutzerdefinierte Header verwenden, Ihr externer API-Schlüssel.

Weitere Informationen zu Authentifizierungsmodellen

Zur Verwaltung von Anmeldedaten verwendet die Agent Registry die Agent-Identität für die integrierte Google Cloud Authentifizierung und den Authentifizierungsmanager für die Identität von KI-Agenten für Authentifizierungsanbieter und Bindungen.

Ihre Kundenservicemitarbeiter können ihre eigene Identität verwenden oder über den Auth-Manager mit API-Schlüsseln oder OAuth auf Tools zugreifen. Die Identität des KI-Agenten wird über Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bereitgestellt, unabhängig davon, ob Sie die Identität des KI-Agenten oder Dienstkonten verwenden.

Alternativ können Sie erweiterte Kontextinformationen an einen Ziel-Agent senden oder benutzerdefinierte HTTP-Header direkt in Ihren ADK-Anfragen angeben, wenn externe Toolsets den Authentifizierungsmanager für Agent-Identitäten nicht unterstützen.

Informationen zum besten Ansatz für Ihren Anwendungsfall finden Sie unter Authentifizierungsmodelle.

KI-Agentenidentität für Google Cloud -Tools verwenden

Für Google Cloud -Dienste wie Vertex AI oder Cloud Storage verwendet Ihr Agent seine eigene Identität, um auf die Tools zuzugreifen. Dieser Zugriff wird über Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) verwaltet, unabhängig davon, ob Sie Agent Identity oder Dienstkonten verwenden.

Die Identität, die Ihrem Agent zugeordnet ist, muss die erforderlichen IAM-Berechtigungen (Identity and Access Management) für die zugrunde liegenden Dienste haben. Wenn ein MCP-Tool beispielsweise Compute Engine-VM-Instanzen verwaltet, muss die Agent-Identität neben der Rolle „Agent Registry API Viewer“ auch Rollen wie Compute Instance Admin (v1) oder höher haben.

Remote-A2A-Agenten authentifizieren

Wenn Ihr Orchestrator-Agent mit seiner eigenen Identität eine Verbindung zu einem Remote-Google Agent2Agent (A2A)-Agent herstellt, müssen Sie httpx.AsyncClient, das mit Ihren Google-Authentifizierungsheadern konfiguriert ist, explizit in die Methode get_remote_a2a_agent() aufnehmen.

Wir empfehlen, ein benutzerdefiniertes Zeitlimit zu definieren, um zu verhindern, dass die Standardzeitlimitüberschreitungen des HTTP-Clients überschritten werden.

Das folgende Beispiel zeigt, wie Sie httpx.AsyncClient mit ADC und einem benutzerdefinierten Zeitlimit konfigurieren:

import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))

# Connect to a remote A2A agent using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "agents/AGENT_ID"
# Full format: f"projects/{project_id}/locations/{location}/agents/AGENT_ID"
agent_name = "agents/AGENT_ID"
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client,
)

MCP-Tools authentifizieren

Wenn Ihr Orchestrator-Agent eine eigene Identität für den Zugriff auf ein MCP-Toolset verwendet, können Sie den Registry-Client mit Ihrem ADC und der Methode get_mcp_toolset() initialisieren:

import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Retrieve an MCP toolset using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "mcpServers/SERVER_ID"
# Full format: f"projects/{project_id}/locations/{location}/mcpServers/SERVER_ID"
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

Auth Manager für benutzerdefinierte Tools und delegierten Zugriff verwenden

Wenn Ihr Agent eine Verbindung zu externen APIs, benutzerdefinierten Tools oder externen MCP-Servern herstellen muss, können Sie den Authentifizierungsmanager für die Identität von KI-Agenten verwenden, um Anmeldedaten zu verwalten, ohne sie in Ihre Anwendung zu codieren.

Je nach Anwendungsfall können Sie den Auth-Manager für die folgenden Szenarien konfigurieren:

Für diese Modelle müssen Sie einen Auth-Anbieter erstellen. Anschließend erstellen Sie in der Agent Registry eine Bindung, um den Authentifizierungsanbieter mit Ihren Registry-Ressourcen zu verknüpfen.

Nach der Konfiguration des Authentifizierungsanbieters verwaltet das ADK den Authentifizierungsablauf für Ihren Orchestrator. Ein Beispiel finden Sie unter Bindungen in Ihrem ADK-Code auflösen.

Auf benutzerdefinierte Tools zugreifen

Wenn Ihr Agent mit eigenen Anmeldedaten eine Verbindung zu externen oder benutzerdefinierten Tools herstellen soll, können Sie den Authentifizierungsmanager für die Identität von Agenten so konfigurieren, dass er API-Schlüssel oder 2-Legged OAuth (2LO) verarbeitet:

  1. Authentifizierungsanbieter erstellen:Erstellen Sie einen Authentifizierungsanbieter in der Agent Identity-Authentifizierungsverwaltung, um den API-Schlüssel oder die OAuth-Anmeldedaten zu speichern. Weitere Informationen finden Sie unter Mit dem Authentifizierungsmanager mit zweiseitigem OAuth authentifizieren oder Mit dem Authentifizierungsmanager mit einem API-Schlüssel authentifizieren.

  2. Authentifizierungsanbieter binden:Damit Ihr Orchestrator-Agent den richtigen Authentifizierungsanbieter für ein Ziel erkennen kann, müssen Sie in der Agent Registry eine Bindung zwischen Ihrem Agent und dem Authentifizierungsanbieter erstellen. Mit Bindungen müssen Sie Auth-Anbieter nicht manuell in Ihrem Code definieren.

    Erstellen Sie eine Bindung, um Ihren Agenten explizit mit dem Authentifizierungsanbieter zu verknüpfen. Wenn Sie den Ressourcennamen --auth-provider angeben, müssen Sie Ihre Projekt-ID verwenden:

    gcloud alpha agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=LOCATION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--auth-provider="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_ID" \

    Weitere Informationen zum Verwalten dieser Verbindungen finden Sie unter Bindungen verwalten.

Im Namen eines Nutzers auf Tools zugreifen

Wenn Ihr Agent sich im Namen eines einzelnen Nutzers bei Remote-MCP-Servern oder -Tools authentifizieren soll, verwenden Sie 3-legged OAuth (3LO) über den Auth-Manager für die Agent-Identität.

Der Auth-Manager bietet einen vollständig von Google verwalteten Dienst für die Verarbeitung von OAuth-Tokens, Nutzereinwilligung und Weiterleitungen. Wenn Sie mit dem Agent interagieren und ein Tool auslösen, für das delegierte Berechtigungen erforderlich sind, fordert die Plattform den Nutzer automatisch zur Einwilligung auf, speichert die Anmeldedaten und setzt den Workflow fort:

  1. Authentifizierungsanbieter erstellen:Erstellen Sie einen Authentifizierungsanbieter in der Agent Identity-Authentifizierungsverwaltung und konfigurieren Sie Ihre OAuth-Weiterleitungs-URIs. Weitere Informationen finden Sie unter Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren.
  2. Clientanwendung aktualisieren:Aktualisieren Sie den Client Ihrer Anwendung, damit der adk_request_credential-Funktionsaufruf verarbeitet und die Nutzereinwilligung verwaltet werden kann. Eine ausführliche Anleitung finden Sie unter Clientseitige Anwendung aktualisieren.

  3. Authentifizierungsanbieter binden:Damit Ihr Orchestrator-Agent den richtigen Authentifizierungsanbieter für ein Ziel erkennen kann, müssen Sie in der Agent Registry eine Bindung zwischen Ihrem Agent und dem Authentifizierungsanbieter erstellen. Mit Bindungen müssen Sie Auth-Anbieter nicht manuell in Ihrem Code definieren.

    Erstellen Sie eine Bindung, um Ihren Agenten explizit mit dem Authentifizierungsanbieter zu verknüpfen. Wenn Sie den Ressourcennamen --auth-provider angeben, müssen Sie Ihre Projekt-ID verwenden:

    gcloud alpha agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=LOCATION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--auth-provider="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_ID" \

    Weitere Informationen zum Verwalten dieser Verbindungen finden Sie unter Bindungen verwalten.

Bindungen in Ihrem ADK-Code auflösen

Nachdem Sie die Bindung des Authentifizierungsanbieters in der Agent Registry erstellt haben, übernimmt das ADK den Authentifizierungsablauf.

Wenn Sie den AgentRegistry-Client verwenden, um ein MCP-Toolset abzurufen, löst das ADK automatisch alle Bindungen auf, die mit diesem Server verknüpft sind, und wendet das richtige Schema an. Sie müssen die Anmeldedaten nicht manuell in Ihrem Code konfigurieren.

Das folgende Beispiel zeigt, wie Sie ein authentifiziertes MCP-Toolset abrufen und an einen Agent anhängen:

import os
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_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Initialize the registry client
registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide"
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get"
        "the best information (e.g., search for a place first, then get details"
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses,"
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including"
        "full addresses and key details. Use formatting to make recommendations"
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with"
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

Wenn Sie 3LO für den Zugriff auf Tools im Namen eines Nutzers einrichten, müssen Sie auch continue_uri für die get_mcp_toolset-Methode angeben. Dieser URI gibt an, wohin der Nutzer nach der Einwilligung weitergeleitet wird:

[...]

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
# For 3-legged OAuth (3LO), provide continue_uri.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(
    mcp_server_name=mcp_server_name,
    # Replace with your app's redirect URI:
    continue_uri="https://REDIRECT_URI"
)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide"
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get"
        "the best information (e.g., search for a place first, then get details"
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses,"
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including"
        "full addresses and key details. Use formatting to make recommendations"
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with"
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

Benutzerdefinierte Header für externe Tools verwenden

Wenn Sie erweiterten Kontext an einen Ziel-Agent senden möchten oder externe Toolsets den Agent Identity Auth Manager nicht unterstützen, können Sie benutzerdefinierte HTTP-Header direkt in Ihren ADK-Anfragen angeben.

Konfigurieren Sie benutzerdefinierte Header, indem Sie beim Initialisieren Ihres AgentRegistry-Clients einen header_provider-Callback angeben.

Der header_provider-Callback empfängt den aktuellen Ausführungskontext und gibt ein Dictionary mit HTTP-Headern zurück. Die Komponente RemoteA2aAgent oder McpToolset hängt diese Header automatisch an Downstream-Anfragen an.

Benutzerdefinierte Header, die vom header_provider-Callback bereitgestellt werden, werden nur an die Zieldienste gesendet, also an die Agents oder Tools. Benutzerdefinierte Header werden nicht zur Authentifizierung bei der Agent Registry API verwendet. Die API basiert immer auf ADC.

In diesem Beispiel wird gezeigt, wie Sie einen API-Schlüssel oder ein benutzerdefiniertes Bearertoken für ein externes Toolset bereitstellen:

import os
from typing import Any
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
external_api_key = os.environ.get("API_KEY")

# Define the custom header provider.
def my_auth_headers(context: Any) -> dict[str, str]:
    """Returns custom headers injected into the tool or agent requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the MCP server or agent during invocation.
# The header_provider is not used to authenticate against the Agent Registry API.
# The Agent Registry API always uses your Google ADC.
registry = AgentRegistry(
    project_id=project_id,
    location=location,
    header_provider=my_auth_headers
)

# Fetching the toolset automatically attaches the header_provider to the MCP server.
# Replace with the full resource name of your registered MCP server.
mcp_server_name = f"projects/PROJECT_ID/locations/LOCATION/mcpServers/EXTERNAL_SERVER_ID"
external_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

Nächste Schritte