Autenticarsi per accedere a strumenti e risorse

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Quando un agente orchestratore richiama un agente remoto o un set di strumenti Model Context Protocol (MCP) rilevato tramite Agent Registry, deve autenticarsi con il servizio sottostante che fornisce queste funzionalità.

Questo documento descrive come gestire l'autenticazione per le risorse di Agent Registry.

Prima di iniziare

Prima di eseguire l'autenticazione a strumenti e risorse, completa le seguenti operazioni:

1. Configura Agent Registry nel tuo progetto.

2. Installa o esegui l'upgrade all'ultima versione dell'ADK con le dipendenze A2A necessarie:

   pip

   pip install --upgrade "google-adk[a2a]"
   

   uv

   uv add "google-adk[a2a]"
   

   Devi eseguire l'upgrade almeno alla versione google-adk>=1.29.0.

3. Per utilizzare le Credenziali predefinite dell'applicazione (ADC) per l'autenticazione, configurale:

   gcloud auth application-default login
   

   Le credenziali ADC devono disporre delle autorizzazioni IAM necessarie per i servizi sottostanti con cui interagiscono gli agenti o gli strumenti.

4. Per seguire gli esempi di questa guida, devi configurare le variabili di ambiente, ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • LOCATION: la regione o la posizione del registro, ad esempio us-central1.
   • EXTERNAL_API_KEY: se utilizzi intestazioni personalizzate, la tua chiave API esterna.

Scopri di più sui modelli di autenticazione

Per gestire le credenziali, il registro degli agenti si basa su Agent Identity per l'autenticazione Google Cloud integrata e su Gestore di autenticazione di identità dell'agente per provider di autenticazione e binding.

Gli agenti possono utilizzare la propria identità o Auth Manager per accedere agli strumenti utilizzando chiavi API o OAuth. L'identità dell'agente viene fornita tramite credenziali predefinite dell'applicazione (ADC) indipendentemente dal fatto che utilizzi l'identità dell'agente o service account.

In alternativa, per inviare un contesto avanzato a un agente di destinazione o se i toolset esterni non supportano Agent Identity Auth Manager, puoi fornire intestazioni HTTP personalizzate direttamente nelle richieste ADK.

Per determinare l'approccio migliore per il tuo caso d'uso, consulta Modelli di autenticazione.

Utilizzare Agent Identity per gli strumenti Google Cloud

Per i servizi Google Cloud , come Vertex AI o Cloud Storage, il tuo agente utilizza la propria identità per accedere agli strumenti. Questo accesso viene gestito tramite le credenziali predefinite dell'applicazione (ADC), indipendentemente dal fatto che utilizzi l'identità dell'agente o i service account.

L'identità associata al tuo agente deve disporre delle autorizzazioni Identity and Access Management necessarie per i servizi sottostanti. Ad esempio, se uno strumento MCP gestisce le istanze VM di Compute Engine, l'identità dell'agente deve disporre di ruoli come Compute Instance Admin (v1) o versioni successive, oltre al ruolo Visualizzatore API Agent Registry.

Autenticare gli agenti A2A remoti

Se l'agente orchestratore si connette a un agente Google Agent2Agent (A2A) remoto utilizzando la propria identità, devi includere esplicitamente httpx.AsyncClient configurato con le intestazioni di autenticazione Google nel metodo get_remote_a2a_agent().

Ti consigliamo di definire un timeout personalizzato per evitare di superare i limiti di timeout predefiniti del client HTTP.

L'esempio seguente mostra come configurare httpx.AsyncClient con ADC e un timeout personalizzato:

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

Autenticare gli strumenti MCP

Se l'agente orchestratore utilizza la propria identità per accedere a un set di strumenti MCP, puoi inizializzare il client del registro utilizzando le tue credenziali predefinite dell'applicazione e il metodo get_mcp_toolset():

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)

Utilizzare Auth Manager per strumenti personalizzati e accesso delegato

Quando l'agente deve connettersi ad API esterne, strumenti personalizzati o server MCP esterni, puoi utilizzare il gestore di autenticazione di identità dell'agente per gestire le credenziali senza codificarle nell'applicazione.

A seconda del tuo caso d'uso, puoi configurare Auth Manager per i seguenti scenari:

• Accedi a strumenti personalizzati: autentica l'agente con chiavi API o OAuth a due fattori (2LO) quando l'agente deve accedere a uno strumento utilizzando la propria identità e autorizzazioni.
• Accedere agli strumenti per conto di un utente: autenticare l'agente che agisce come singolo utente con OAuth a tre vie (3LO). Questo modello è consigliato quando l'agente deve accedere agli strumenti per conto della persona che interagisce con lui, richiedendo il consenso dell'utente e l'autorizzazione delegata.

Questi modelli richiedono la creazione di un fornitore di autenticazione. Poi, crei un binding in Agent Registry per collegare il provider di autenticazione alle risorse del registro.

Dopo aver configurato il fornitore di autenticazione, l'ADK gestisce il flusso di autenticazione per l'orchestratore. Per un esempio, consulta la pagina Risolvere i binding nel codice ADK.

Accedere agli strumenti personalizzati

Se vuoi che l'agente si connetta a strumenti esterni o personalizzati utilizzando le proprie credenziali, puoi configurare il gestore di autenticazione di identità dell'agente per gestire le chiavi API o OAuth a due passaggi (2LO):

1. Crea il provider di autenticazione:crea un provider di autenticazione in Agent Identity Auth Manager per archiviare la chiave API o le credenziali OAuth. Per informazioni, consulta Autenticati utilizzando OAuth a due vie con Auth Manager o Autenticati utilizzando una chiave API con Auth Manager.

2. Collega il provider di autenticazione:per consentire all'agente orchestratore di rilevare il provider di autenticazione corretto per una destinazione, devi creare un binding nel registry degli agenti tra l'agente e il provider di autenticazione. Con i binding, non devi definire manualmente i fornitori di autenticazione nel codice.

   Crea un binding per collegare esplicitamente l'agente al provider di autenticazione. Quando specifichi il nome della risorsa --auth-provider, devi utilizzare l'ID progetto:

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

   Per saperne di più sulla gestione di queste connessioni, consulta Gestire le associazioni.

Accedere agli strumenti per conto di un utente

Se vuoi che l'agente si autentichi su server o strumenti MCP remoti per conto di un singolo utente, utilizza OAuth a tre vie (3LO) tramite Agent Identity Auth Manager.

Auth Manager fornisce un servizio completamente gestito da Google per la gestione di token OAuth, consenso dell'utente e reindirizzamenti. Quando interagisci con l'agente e attivi uno strumento che richiede autorizzazioni delegate, la piattaforma chiede automaticamente il consenso all'utente, memorizza le credenziali e riprende il flusso di lavoro:

1. Crea il provider di autenticazione:crea un provider di autenticazione in Agent Identity Auth Manager e configura gli URI di reindirizzamento OAuth. Per informazioni, consulta Autenticarsi utilizzando OAuth a tre vie con Auth Manager.
2. Aggiorna l'applicazione client: aggiorna il client dell'applicazione per gestire la chiamata di funzione adk_request_credential e gestire il consenso dell'utente. Per istruzioni dettagliate, vedi Aggiornare l'applicazione lato client.

3. Collega il provider di autenticazione:per consentire all'agente orchestratore di rilevare il provider di autenticazione corretto per una destinazione, devi creare un binding nel registry degli agenti tra l'agente e il provider di autenticazione. Con i binding, non devi definire manualmente i fornitori di autenticazione nel codice.

   Crea un binding per collegare esplicitamente l'agente al provider di autenticazione. Quando specifichi il nome della risorsa --auth-provider, devi utilizzare l'ID progetto:

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

   Per saperne di più sulla gestione di queste connessioni, consulta Gestire le associazioni.

Risolvere i binding nel codice ADK

Dopo aver creato il binding del provider di autenticazione nel registro degli agenti, l'ADK gestisce il flusso di autenticazione.

Quando utilizzi il client AgentRegistry per recuperare un set di strumenti MCP, l'ADK risolve automaticamente tutti i binding associati a quel server e applica lo schema corretto. Non è necessario configurare manualmente le credenziali nel codice.

L'esempio seguente mostra come recuperare un insieme di strumenti MCP autenticato e allegarlo a un agente:

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

Se configuri l'autorizzazione di terze parti per accedere agli strumenti per conto di un utente, devi anche fornire continue_uri al metodo get_mcp_toolset. Questo URI indica dove viene reindirizzato l'utente dopo aver concesso il consenso:

[...]

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

Utilizzare intestazioni personalizzate per strumenti esterni

Per inviare un contesto avanzato a un agente di destinazione o se i toolset esterni non supportano Agent Identity Auth Manager, puoi fornire intestazioni HTTP personalizzate direttamente nelle richieste ADK.

Configura le intestazioni personalizzate fornendo un callback header_provider durante l'inizializzazione del client AgentRegistry.

Il callback header_provider riceve il contesto di esecuzione corrente e restituisce un dizionario di intestazioni HTTP. Il componente RemoteA2aAgent o McpToolset collega automaticamente queste intestazioni alle richieste downstream.

Le intestazioni personalizzate fornite dal callback header_provider vengono inviate solo ai servizi di destinazione, ovvero gli agenti o gli strumenti. Le intestazioni personalizzate non vengono utilizzate per l'autenticazione nell'API Agent Registry. L'API si basa sempre su ADC.

Questo esempio mostra come fornire una chiave API o un token bearer personalizzato per un insieme di strumenti esterni:

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)

Passaggi successivi

• Scopri come utilizzare Agent Gateway per applicare i controlli dell'accesso e i perimetri di rete alle richieste autenticate degli strumenti.