Authentifizierung für Tools und Ressourcen

Mit Agent Registry können sich Ihre Orchestrator-Agenten sicher bei erkannten Remote-Agenten, MCP-Toolsets (Model Context Protocol) undGoogle Cloud -Diensten authentifizieren. Mit Agent Identity und dem Agent Identity-Authentifizierungsmanager können Sie Anmeldedaten, Bindungen und benutzerdefinierte HTTP-Header konfigurieren, wenn Sie Funktionen aufrufen, die über die Agent Registry gefunden wurden.

Hinweis

Führen Sie vor der Authentifizierung bei Tools und Ressourcen die folgenden Schritte aus:

1. Agent Registry einrichten
2. Rufen Sie die Projekt-ID für das Governance-Projekt ab, in dem die Agent Registry aktiviert ist.

3. Installieren oder führen Sie ein Upgrade auf die aktuelle Version des Agent Development Kit (ADK) mit den Abhängigkeiten für A2A, Agent Identity und MCP durch:

   pip

   pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
   

   uv

   uv add "google-adk[a2a,agent-identity,mcp]"
   

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

4. Wenn Sie Standardanmeldedaten für Anwendungen zur Authentifizierung verwenden möchten, konfigurieren Sie sie:

   gcloud auth application-default login
   

   ADC-Anmeldedaten müssen die erforderlichen IAM-Berechtigungen (Identity and Access Management) für die zugrunde liegenden Google Cloud -Dienste haben, mit denen die Agenten oder Tools interagieren.

5. Richten Sie die folgenden Umgebungsvariablen ein:

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

   Ersetzen Sie Folgendes:

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

Informationen zu Authentifizierungsmodellen

Zur Verwaltung von Anmeldedaten verwendet Agent Registry Agent Identity für die integrierteGoogle Cloud -Authentifizierung und den Authentifizierungsmanager für Authentifizierungsanbieter und Bindungen.

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

Wenn Sie sich ohne den Auth Manager authentifizieren müssen, geben Sie benutzerdefinierte HTTP-Header direkt in Ihren ADK-Anfragen an.

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

Agentenidentität für Google Cloud -Tools verwenden

Für Google Cloud -Dienste wie Agent Runtime on Gemini Enterprise Agent Platform 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 die Agentenidentität oder Dienstkonten verwenden.

Die mit Ihrem Agenten verknüpfte Identität muss die erforderlichen IAM-Berechtigungen für die zugrunde liegenden Google Cloud -Dienste haben. Wenn ein MCP-Tool beispielsweise Compute Engine-VM-Instanzen verwaltet, muss die Agentenidentität zusätzlich zur Rolle Agent Registry API Viewer Rollen wie Compute Instance Admin (v1) oder höher haben.

Remote-A2A-Agenten authentifizieren

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

Definieren Sie ein benutzerdefiniertes Zeitlimit, um zu verhindern, dass die standardmäßigen HTTP-Client-Zeitlimits überschritten werden.

Das folgende Beispiel zeigt, wie Sie httpx.AsyncClient mit Standardanmeldedaten für Anwendungen 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,
)

Ersetzen Sie AGENT_ID durch die ID Ihres registrierten Agenten.

MCP-Tools authentifizieren

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

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

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

Ersetzen Sie SERVER_ID durch die ID Ihres registrierten MCP-Servers.

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 verwenden, um Anmeldedaten zu verwalten, ohne sie in Ihrer Anwendung hartcodieren zu müssen.

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

• Auf benutzerdefinierte Tools zugreifen: Authentifizieren Sie den Agenten mit API-Schlüsseln oder 2-Legged OAuth (2LO), wenn der Agent mit seiner eigenen Identität und seinen eigenen Berechtigungen auf ein Tool zugreifen muss.
• Im Namen eines Nutzers auf Tools zugreifen: Authentifizieren Sie den Agenten, der als einzelner Nutzer agiert, mit dreibeinigem OAuth (3LO). Dieses Modell wird empfohlen, wenn der KI-Agent im Namen der Person, die mit ihm interagiert, auf Tools zugreifen muss. Dazu sind die Nutzereinwilligung und eine delegierte Berechtigung erforderlich.

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

Nachdem Sie den Authentifizierungsanbieter konfiguriert haben, verwaltet das ADK den Authentifizierungsablauf für Ihren Orchestrator. Ein Beispiel finden Sie unter Bindungen im ADK-Code auflösen.

Auf benutzerdefinierte Tools zugreifen

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

1. Authentifizierungsanbieter erstellen: Erstellen Sie einen Authentifizierungsanbieter im Authentifizierungsmanager, um den API-Schlüssel oder die OAuth-Anmeldedaten zu speichern. Weitere Informationen finden Sie unter Mit 2-Bein-OAuth mit Auth Manager authentifizieren oder Mit API-Schlüssel mit Auth Manager 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 Agenten, der Zielressource und dem Authentifizierungsanbieter erstellen. Mit Bindungen müssen Sie Authentifizierungsanbieter nicht manuell in Ihrem Code definieren:

   gcloud

   Erstellen Sie eine Bindung, um Ihren Agent explizit mit der Zielressource und dem Authentifizierungsanbieter zu verknüpfen. Führen Sie dazu den Befehl gcloud agent-registry bindings create aus. Wenn Sie den Ressourcennamen --auth-provider-binding angeben, müssen Sie die Projekt-ID Ihres Governance-Projekts verwenden:

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

   Terraform

   Konfigurieren Sie die Ressource google_agent_registry_binding, um Ihren Agenten und die Zielressource mit dem Authentifizierungsanbieter zu verknüpfen:

   resource "google_agent_registry_binding" "custom_tool_binding" {
     project      = "PROJECT_ID"
     location     = "LOCATION"
     binding_id   = "BINDING_NAME"
     display_name = "DISPLAY_NAME"
   
     source {
       identifier = "SOURCE_ID"
     }
   
     target {
       identifier = "TARGET_ID"
     }
   
     auth_provider_binding {
       auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
     }
   }
   

   Ersetzen Sie Folgendes:

   • BINDING_NAME: die eindeutige ID der Bindung.
   • PROJECT_ID: die Projekt-ID Ihres Governance-Projekts.
   • LOCATION: die Registry-Region oder der Registry-Standort, z. B. us-central1 oder global.
   • DISPLAY_NAME: ein menschenlesbarer Anzeigename für die Bindung.
   • SOURCE_ID: die Agent-ID des Quell-Agenten im URN-Format.
   • TARGET_ID: die Registry-ID des Ziel-MCP-Servers oder ‑Endpunkts im URN-Format.
   • AUTH_PROVIDER_ID: die ID Ihres Authentifizierungsanbieters.

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

Im Namen eines Nutzers auf Tools zugreifen

Wenn sich Ihr Agent im Namen eines einzelnen Nutzers bei Remote-MCP-Servern oder ‑Tools authentifizieren soll, verwenden Sie 3-Legged OAuth (3LO) über den Auth Manager.

Der Auth Manager bietet einen vollständig von Google verwalteten Dienst für die Verarbeitung von OAuth-Tokens, Nutzereinwilligungen und Weiterleitungen. Wenn ein Endnutzer mit dem Agenten interagiert und ein Tool auslöst, das delegierte Berechtigungen erfordert, fordert die Plattform den Nutzer automatisch zur Einwilligung auf, speichert die Anmeldedaten und setzt den Workflow fort:

1. Authentifizierungsanbieter erstellen: Erstellen Sie einen Authentifizierungsanbieter im Authentifizierungsmanager und konfigurieren Sie Ihre OAuth-Weiterleitungs-URIs. Weitere Informationen finden Sie unter Mit dreibeinigem OAuth mit Auth Manager authentifizieren.
2. Clientanwendung aktualisieren: Aktualisieren Sie den Anwendungsclient, um den Funktionsaufruf adk_request_credential zu verarbeiten und die Nutzereinwilligung zu verwalten. 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 Agenten, der Zielressource und dem Authentifizierungsanbieter erstellen. Mit Bindungen müssen Sie Authentifizierungsanbieter nicht manuell in Ihrem Code definieren:

   gcloud

   Erstellen Sie eine Bindung, um Ihren Agent explizit mit der Zielressource und dem Authentifizierungsanbieter zu verknüpfen. Führen Sie dazu den Befehl gcloud agent-registry bindings create aus. Wenn Sie den Ressourcennamen --auth-provider-binding angeben, müssen Sie die Projekt-ID Ihres Governance-Projekts verwenden:

   gcloud agent-registry bindings create BINDING_NAME \
       --project=PROJECT_ID \
       --location=LOCATION \
       --display-name="DISPLAY_NAME" \
       --source-identifier="SOURCE_ID" \
       --target-identifier="TARGET_ID" \
       --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" \
       --auth-provider-binding-scopes=SCOPES \
       --auth-provider-binding-continue-uri="https://REDIRECT_URI"
   

   Terraform

   Konfigurieren Sie die google_agent_registry_binding-Ressource mit Ihren OAuth 2.0-Bereichen und dem Weiterleitungs-URI:

   resource "google_agent_registry_binding" "user_delegated_binding" {
     project      = "PROJECT_ID"
     location     = "LOCATION"
     binding_id   = "BINDING_NAME"
     display_name = "DISPLAY_NAME"
   
     source {
       identifier = "SOURCE_ID"
     }
   
     target {
       identifier = "TARGET_ID"
     }
   
     auth_provider_binding {
       auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
       scopes        = [SCOPES]
       continue_uri  = "https://REDIRECT_URI"
     }
   }
   

   Ersetzen Sie Folgendes:

   • BINDING_NAME: die eindeutige ID der Bindung.
   • PROJECT_ID: die Projekt-ID Ihres Governance-Projekts.
   • LOCATION: die Registry-Region oder der Registry-Standort, z. B. us-central1 oder global.
   • DISPLAY_NAME: ein menschenlesbarer Anzeigename für die Bindung.
   • SOURCE_ID: die Agent-ID des Quell-Agenten im URN-Format.
   • TARGET_ID: die Registry-ID der Ziel-MCP-Server- oder Tool-Ressource im URN-Format.
   • AUTH_PROVIDER_ID: die ID Ihres Authentifizierungsanbieters.
   • SCOPES: eine durch Kommas getrennte Liste von OAuth 2.0-Bereichen, z. B. https://www.googleapis.com/auth/cloud-platform. In Terraform muss jeder Bereich in doppelte Anführungszeichen gesetzt werden.
   • REDIRECT_URI: der Weiterleitungs-URI, der für Ihren Authentifizierungsanbieter nach der Nutzereinwilligung konfiguriert wurde.

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

Bindungen im ADK-Code auflösen

Nachdem Sie die Bindung des Authentifizierungsanbieters in 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 Anmeldedaten nicht manuell in Ihrem Code konfigurieren.

Im folgenden Beispiel wird gezeigt, wie Sie ein authentifiziertes MCP-Toolset abrufen und an einen Agenten 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],
)

Ersetzen Sie SERVER_ID durch die ID Ihres registrierten MCP-Servers.

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

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

Ersetzen Sie Folgendes:

• SERVER_ID: die ID Ihres registrierten MCP-Servers.
• REDIRECT_URI: der Weiterleitungs-URI Ihrer Anwendung, an den der Nutzer nach der Einwilligung weitergeleitet wird.

Benutzerdefinierte Header für externe Tools verwenden

Wenn Sie sich authentifizieren oder Anfrageheader übergeben müssen, ohne den Auth Manager zu verwenden, geben Sie benutzerdefinierte HTTP-Header direkt in Ihren ADK-Anfragen an.

Konfigurieren Sie benutzerdefinierte Header, indem Sie bei der Initialisierung des AgentRegistry-Clients einen header_provider-Callback angeben.

Der Callback header_provider empfängt den aktuellen Ausführungskontext und gibt ein Dictionary mit HTTP-Headern zurück. Die McpToolset-Komponente hängt diese Header automatisch an nachgelagerte Anfragen an, die an den MCP-Server gesendet werden.

Benutzerdefinierte Header, die vom header_provider-Callback bereitgestellt werden, werden nur an die Ziel-MCP-Server gesendet. Benutzerdefinierte Header werden nicht zur Authentifizierung bei der Agent Registry API selbst verwendet. Die API verwendet immer Standardanmeldedaten für Anwendungen.

In diesem Beispiel wird gezeigt, wie Sie einen API-Schlüssel oder ein benutzerdefiniertes Inhabertoken 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 MCP toolset requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the target MCP server 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)

Ersetzen Sie Folgendes:

• PROJECT_ID: die Projekt-ID Ihres Governance-Projekts.
• LOCATION: die Registry-Region oder der Registry-Standort, z. B. us-central1.
• EXTERNAL_SERVER_ID: die ID Ihres registrierten externen MCP-Servers.

Nächste Schritte

• Agent Gateway verwenden, um Zugriffssteuerungen und Netzwerkperimeter für Ihre authentifizierten Toolanfragen zu erzwingen