Autenticarsi per accedere a strumenti e risorse

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei 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 eseguire l'autenticazione 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 i seguenti passaggi:

1. Configura Agent Registry nel tuo progetto.

2. Installa o esegui l'upgrade all'ultima versione di Agent Development Kit (ADK):

   pip install --upgrade google-adk
   

   Devi eseguire l'upgrade ad almeno 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 riportati in 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 località 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, Agent Registry si basa su Agent Identity per l'autentica Google Cloud zione e su Agent Identity auth manager per i provider di autenticazione e i binding.

Gli agenti possono utilizzare la propria identità o il gestore di autenticazione per accedere agli strumenti utilizzando chiavi API o OAuth. L'identità dell'agente viene fornita tramite le Credenziali predefinite dell'applicazione (ADC) , indipendentemente dal fatto che tu stia utilizzando Agent Identity o service account.

In alternativa, per inviare un contesto avanzato a un agente di destinazione o se i set di strumenti esterni non supportano il gestore di autenticazione di Agent Identity, 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 Google Cloud strumenti

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

L'identità associata all'agente deve disporre delle autorizzazioni di 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 avere ruoli come Compute Instance Admin (v1) o superiore, in aggiunta al ruolo Visualizzatore API di 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 del client HTTP predefiniti.

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 ADC 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 il gestore di autenticazione 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 Agent Identity per gestire le credenziali senza codificarle nell'applicazione.

A seconda del caso d'uso, puoi configurare il gestore di autenticazione per i seguenti scenari:

• Accedere a strumenti personalizzati: autentica l'agente con chiavi API o OAuth a due vie (2LO) quando l'agente deve accedere a uno strumento utilizzando la propria identità e le proprie autorizzazioni.
• Accedere agli strumenti per conto di un utente: autentica 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 esso, richiedendo il consenso dell'utente e l'autorizzazione delegata.

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

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

Accedere a 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 Agent Identity per gestire le chiavi API o OAuth a due vie (2LO):

1. Crea il provider di autenticazione: crea un provider di autenticazione nel gestore di autenticazione di Agent Identity per archiviare la chiave API o le credenziali OAuth. Per informazioni, consulta Eseguire l'autenticazione utilizzando OAuth a due vie con il gestore di autenticazione o Eseguire l'autenticazione utilizzando una chiave API con il gestore di autenticazione.

2. Associa il provider di autenticazione: per consentire all'agente orchestratore di rilevare il provider di autenticazione corretto per una destinazione, devi creare un binding in Agent Registry tra l' agente e il provider di autenticazione. Con i binding, non devi definire manualmente i provider 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 i binding.

Accedere agli strumenti per conto di un utente

Se vuoi che l'agente esegua l'autenticazione a server o strumenti MCP remoti per conto di un singolo utente, utilizza OAuth a tre vie (3LO) tramite il gestore di autenticazione di Agent Identity.

Il gestore di autenticazione 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 richiede automaticamente il consenso dell'utente, archivia le credenziali e riprende il flusso di lavoro:

1. Crea il provider di autenticazione: crea un provider di autenticazione nel gestore di autenticazione di Agent Identity e configura gli URI di reindirizzamento OAuth. Per informazioni, consulta Eseguire l'autenticazione utilizzando OAuth a tre vie con il gestore di autenticazione.
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, consulta Aggiornare l'applicazione lato client.

3. Associa il provider di autenticazione: per consentire all'agente orchestratore di rilevare il provider di autenticazione corretto per una destinazione, devi creare un binding in Agent Registry tra l' agente e il provider di autenticazione. Con i binding, non devi definire manualmente i provider 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 i binding.

Risolvere i binding nel codice ADK

Dopo aver creato il binding del provider di autenticazione in Agent Registry, 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 devi configurare manualmente le credenziali nel codice.

L'esempio seguente mostra come recuperare un set di strumenti MCP autenticato e collegarlo 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 hai configurato 3LO per accedere agli strumenti per conto di un utente, devi anche fornire continue_uri al metodo get_mcp_toolset. Questo URI indica la posizione in cui l'utente viene reindirizzato 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 set di strumenti esterni non supportano il gestore di autenticazione di Agent Identity, 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 rispetto all'API Agent Registry stessa. L'API si basa sempre su ADC.

Questo esempio mostra come fornire una chiave API o un token portatore personalizzato per un set 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 controlli di accesso e perimetri di rete alle richieste di strumenti autenticati.