S'authentifier auprès des outils et des ressources

Lorsqu'un agent d'orchestration appelle un agent distant ou un ensemble d'outils MCP (Model Context Protocol) découverts via Agent Registry, il doit s'authentifier auprès du service Google Cloud sous-jacent qui fournit ces fonctionnalités.

Ce document explique comment gérer l'authentification pour les ressources Agent Registry.

Avant de commencer

Avant de vous authentifier auprès des outils et des ressources, procédez comme suit :

  1. Configurez Agent Registry dans votre projet.

  2. Installez la dernière version de l'ADK ou mettez-la à niveau avec les dépendances A2A nécessaires :

    pip 

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

    uv 

    uv add "google-adk[a2a]"

    Vous devez passer à la version google-adk>=1.29.0 au minimum.

  3. Pour utiliser les identifiants par défaut de l'application (ADC) pour l'authentification, configurez-les :

    gcloud auth application-default login

    Les identifiants ADC doivent disposer des autorisations IAM nécessaires pour les services Google Cloud sous-jacents avec lesquels les agents ou les outils interagissent.

  4. Pour suivre les exemples de ce guide, vous devez configurer des variables d'environnement, par exemple :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet.
    • LOCATION : région ou emplacement du registre, tel que us-central1.
    • EXTERNAL_API_KEY : votre clé API externe si vous utilisez des en-têtes personnalisés.

En savoir plus sur les modèles d'authentification

Pour gérer les identifiants, le registre d'agents s'appuie sur l'identité de l'agent pour l'authentification Google Cloud intégrée et sur le gestionnaire d'authentification de l'identité de l'agent pour les fournisseurs d'authentification et les liaisons.

Vos agents peuvent utiliser leur propre identité ou le gestionnaire d'authentification pour accéder aux outils à l'aide de clés API ou d'OAuth. L'identité propre de l'agent est fournie par le biais des identifiants par défaut de l'application (ADC), que vous utilisiez l'identité de l'agent ou des comptes de service.

Vous pouvez également fournir des en-têtes HTTP personnalisés directement dans vos requêtes ADK pour envoyer un contexte avancé à un agent cible ou si les ensembles d'outils externes ne sont pas compatibles avec le gestionnaire d'authentification de l'identité de l'agent.

Pour déterminer la meilleure approche pour votre cas d'utilisation, consultez Modèles d'authentification.

Utiliser l'identité de l'agent pour les outils Google Cloud

Pour les services Google Cloud tels que Vertex AI ou Cloud Storage, votre agent utilise sa propre identité pour accéder aux outils. Cet accès est géré par les identifiants par défaut de l'application (ADC), que vous utilisiez l'identité de l'agent ou des comptes de service.

L'identité associée à votre agent doit disposer des autorisations Identity and Access Management nécessaires pour les services Google Cloud sous-jacents. Par exemple, si un outil MCP gère des instances de VM Compute Engine, l'identité de l'agent doit disposer de rôles tels que Administrateur d'instances Compute (v1) ou supérieur, en plus du rôle Lecteur de l'API Agent Registry.

Authentifier les agents A2A à distance

Si votre agent d'orchestration se connecte à un agent Google Agent2Agent (A2A) distant à l'aide de sa propre identité, vous devez inclure explicitement httpx.AsyncClient configuré avec vos en-têtes d'authentification Google à la méthode get_remote_a2a_agent().

Nous vous recommandons de définir un délai avant expiration personnalisé pour éviter de dépasser les limites de délai avant expiration du client HTTP par défaut.

L'exemple suivant montre comment configurer httpx.AsyncClient avec ADC et un délai avant expiration personnalisé :

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

Authentifier les outils MCP

Si votre agent d'orchestration utilise sa propre identité pour accéder à un ensemble d'outils MCP, vous pouvez initialiser le client de registre à l'aide de votre ADC et de la méthode 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)

Utiliser le gestionnaire d'authentification pour les outils personnalisés et l'accès délégué

Lorsque votre agent doit se connecter à des API externes, des outils personnalisés ou des serveurs MCP externes, vous pouvez utiliser le gestionnaire d'authentification des identités d'agent pour gérer les identifiants sans les coder en dur dans votre application.

Selon votre cas d'utilisation, vous pouvez configurer le gestionnaire d'authentification pour les scénarios suivants :

Ces modèles vous obligent à créer un fournisseur d'authentification. Vous allez ensuite créer une liaison dans Agent Registry pour associer le fournisseur d'authentification à vos ressources de registre.

Une fois le fournisseur d'authentification configuré, l'ADK gère le flux d'authentification pour votre orchestrateur. Pour obtenir un exemple, consultez Résoudre les liaisons dans votre code ADK.

Accéder aux outils personnalisés

Si vous souhaitez que votre agent se connecte à des outils externes ou personnalisés à l'aide de ses propres identifiants, vous pouvez configurer le gestionnaire d'authentification des identités d'agent pour gérer les clés API ou OAuth à deux étapes (2LO) :

  1. Créez le fournisseur d'authentification : créez un fournisseur d'authentification dans le gestionnaire d'authentification de l'identité de l'agent pour stocker la clé API ou les identifiants OAuth. Pour en savoir plus, consultez S'authentifier à l'aide d'OAuth en deux étapes avec le gestionnaire d'authentification ou S'authentifier à l'aide d'une clé API avec le gestionnaire d'authentification.

  2. Associez le fournisseur d'authentification : pour permettre à votre agent d'orchestration de détecter le bon fournisseur d'authentification pour une cible, vous devez créer une association dans Agent Registry entre votre agent et le fournisseur d'authentification. Grâce aux liaisons, vous n'avez pas besoin de définir manuellement les fournisseurs d'authentification dans votre code.

    Créez une liaison pour associer explicitement votre agent au fournisseur d'authentification. Lorsque vous spécifiez le nom de ressource --auth-provider, vous devez utiliser l'ID de votre projet :

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

    Pour en savoir plus sur la gestion de ces connexions, consultez Gérer les liaisons.

Accéder aux outils pour le compte d'un utilisateur

Si vous souhaitez que votre agent s'authentifie auprès de serveurs ou d'outils MCP distants pour le compte d'un utilisateur individuel, utilisez OAuth en trois étapes (3LO) via le gestionnaire d'authentification de l'identité de l'agent.

Le gestionnaire d'authentification fournit un service entièrement géré par Google pour gérer les jetons OAuth, le consentement utilisateur et les redirections. Lorsque vous interagissez avec l'agent et déclenchez un outil nécessitant des autorisations déléguées, la plate-forme demande automatiquement le consentement de l'utilisateur, stocke les identifiants et reprend le workflow :

  1. Créez le fournisseur d'authentification : créez un fournisseur d'authentification dans le gestionnaire d'authentification Agent Identity et configurez vos URI de redirection OAuth. Pour en savoir plus, consultez S'authentifier à l'aide d'OAuth en trois étapes avec le gestionnaire d'authentification.
  2. Mettez à jour l'application cliente : mettez à jour votre application cliente pour gérer l'appel de fonction adk_request_credential et gérer le consentement utilisateur. Pour obtenir des instructions détaillées, consultez Mettre à jour votre application côté client.

  3. Associez le fournisseur d'authentification : pour permettre à votre agent d'orchestration de détecter le bon fournisseur d'authentification pour une cible, vous devez créer une association dans Agent Registry entre votre agent et le fournisseur d'authentification. Grâce aux liaisons, vous n'avez pas besoin de définir manuellement les fournisseurs d'authentification dans votre code.

    Créez une liaison pour associer explicitement votre agent au fournisseur d'authentification. Lorsque vous spécifiez le nom de ressource --auth-provider, vous devez utiliser l'ID de votre projet :

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

    Pour en savoir plus sur la gestion de ces connexions, consultez Gérer les liaisons.

Résoudre les liaisons dans votre code ADK

Une fois que vous avez créé la liaison du fournisseur d'authentification dans le registre d'agents, l'ADK gère le flux d'authentification.

Lorsque vous utilisez le client AgentRegistry pour extraire un ensemble d'outils MCP, l'ADK résout automatiquement toutes les liaisons associées à ce serveur et applique le schéma approprié. Vous n'avez pas besoin de configurer manuellement les identifiants dans votre code.

L'exemple suivant montre comment récupérer un ensemble d'outils MCP authentifié et l'associer à un agent :

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

Si vous configurez l'autorisation OAuth à trois acteurs (3LO) pour accéder aux outils au nom d'un utilisateur, vous devez également fournir continue_uri à la méthode get_mcp_toolset. Cet URI indique où l'utilisateur est redirigé après avoir donné son consentement :

[...]

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

Utiliser des en-têtes personnalisés pour les outils externes

Pour envoyer un contexte avancé à un agent cible ou si les ensembles d'outils externes ne sont pas compatibles avec le gestionnaire d'authentification de l'identité de l'agent, vous pouvez fournir des en-têtes HTTP personnalisés directement dans vos requêtes ADK.

Configurez des en-têtes personnalisés en fournissant un rappel header_provider lors de l'initialisation de votre client AgentRegistry.

Le rappel header_provider reçoit le contexte d'exécution actuel et renvoie un dictionnaire d'en-têtes HTTP. Le composant RemoteA2aAgent ou McpToolset ajoute automatiquement ces en-têtes aux requêtes en aval.

Les en-têtes personnalisés fournis par le rappel header_provider ne sont envoyés qu'aux services Google Cloud cibles, qui sont les agents ou les outils. Les en-têtes personnalisés ne sont pas utilisés pour l'authentification auprès de l'API Agent Registry elle-même. L'API s'appuie toujours sur ADC.

Cet exemple montre comment fournir une clé API ou un jeton de support personnalisé pour un ensemble d'outils externes :

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)

Étapes suivantes

  • Découvrez comment utiliser Agent Gateway pour appliquer des contrôles d'accès et des périmètres réseau à vos requêtes d'outils authentifiées.