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écouvert via Agent Registry, il doit s'authentifier auprès du service 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' Agent Development Kit (ADK) ou effectuez une mise à niveau vers celle-ci :

    pip install --upgrade google-adk

    Vous devez effectuer une mise à niveau vers au moins google-adk>=1.29.0.

  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 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, par exemple us-central1.
    • EXTERNAL_API_KEY : si vous utilisez des en-têtes personnalisés, votre clé API externe.

En savoir plus sur les modèles d'authentification

Pour gérer les identifiants, Agent Registry s'appuie sur Agent Identity pour l'authentification intégrée et sur le gestionnaire d'authentification Agent Identity pour les fournisseurs d'authentification et les liaisons. Google Cloud

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. La propre identité de l'agent est fournie via les identifiants par défaut de l'application (ADC) , que vous utilisiez Agent Identity 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 Agent Identity.

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

Utiliser Agent Identity pour les Google Cloud outils

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

L'identité associée à votre agent doit disposer des autorisations Identity and Access Management nécessaires pour les services 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 distants

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 dans la méthode get_remote_a2a_agent().

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

L'exemple suivant montre comment configurer httpx.AsyncClient avec ADC et un délai d'inactivité 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 Agent Identity 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 nécessitent la création d'un fournisseur d'authentification. Vous créez ensuite 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 de votre orchestrateur. Pour obtenir un exemple, consultez Résoudre les liaisons dans votre code ADK.

Accéder à des 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 Agent Identity pour gérer les clés API ou OAuth en deux étapes (2LO) :

  1. Créer le fournisseur d'authentification : créez un fournisseur d'authentification dans le gestionnaire d'authentification Agent Identity 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. Lier le fournisseur d'authentification : pour permettre à votre agent d'orchestration de détecter le fournisseur d'authentification approprié pour une cible, vous devez créer une liaison dans Agent Registry entre votre agent et le fournisseur d'authentification. Avec les 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 à des outils au nom d'un utilisateur

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

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

  1. Créer 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. Mettre à jour l'application cliente : mettez à jour votre client d'application pour gérer l'appel de fonction adk_request_credential et gérer le consentement de l'utilisateur. Pour obtenir des instructions détaillées, consultez Mettre à jour votre application côté client.

  3. Lier le fournisseur d'authentification : pour permettre à votre agent d'orchestration de détecter le fournisseur d'authentification approprié pour une cible, vous devez créer une liaison dans Agent Registry entre votre agent et le fournisseur d'authentification. Avec les 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 la liaison du fournisseur d'authentification créée dans Agent Registry, l'ADK gère le flux d'authentification.

Lorsque vous utilisez le client AgentRegistry pour récupérer 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 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 l'endroit 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

Vous pouvez 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 Agent Identity,

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 associe 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 cibles, qui sont les agents ou les outils. Les en-têtes personnalisés ne sont pas utilisés pour s'authentifier 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 porteur personnalisé pour un ensemble d'outils externe :

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)

Étape suivante

  • 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.