Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

S'authentifier auprès des outils et des ressources

Agent Registry permet à vos agents d'orchestration de s'authentifier de manière sécurisée auprès des agents distants, des ensembles d'outils MCP (Model Context Protocol) et des servicesGoogle Cloud découverts. À l'aide d'Agent Identity et du gestionnaire d'authentification Agent Identity, vous pouvez configurer des identifiants, des liaisons et des en-têtes HTTP personnalisés lorsque vous appelez des fonctionnalités découvertes via Agent Registry.

Avant de commencer

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

Configurer le registre d'agents.
Obtenez l'ID du projet pour le projet de gouvernance dans lequel Agent Registry est activé.
Installez la dernière version d'Agent Development Kit (ADK) ou effectuez une mise à niveau vers celle-ci avec les dépendances A2A, Agent Identity et MCP :
pip
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
uv
uv add "google-adk[a2a,agent-identity,mcp]"
Vous devez passer au moins à la version google-adk>=1.29.0.
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 (Identity and Access Management) nécessaires pour les services Google Cloud sous-jacents avec lesquels les agents ou les outils interagissent.
Configurez les variables d'environnement suivantes :
```
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 de gouvernance.
- 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'authentificationGoogle Cloud intégrée et sur le gestionnaire d'authentification 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 2.0. L'identité de l'agent est fournie via les identifiants par défaut de l'application (ADC), que vous utilisiez l'identité de l'agent ou des comptes de service.

Si vous devez vous authentifier sans utiliser le gestionnaire d'authentification, fournissez des en-têtes HTTP personnalisés directement dans vos requêtes ADK.

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

Utiliser Agent Identity pour les outils Google Cloud

Pour les services Google Cloud , tels que Agent Runtime sur Gemini Enterprise Agent Platform 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 l'identité de l'agent ou des comptes de service.

L'identité associée à votre agent doit disposer des autorisations IAM 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 distants

Si votre agent orchestrateur 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().

Pour éviter de dépasser les limites de délai d'expiration du client HTTP par défaut, définissez un délai d'expiration personnalisé.

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

Remplacez AGENT_ID par l'ID de votre agent enregistré.

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

Remplacez SERVER_ID par l'ID de votre serveur MCP enregistré.

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 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 :

Accéder à des outils personnalisés : authentifiez l'agent avec des clés API ou OAuth à deux segments (2LO) lorsque l'agent doit accéder à un outil en utilisant sa propre identité et ses propres autorisations.
Accéder aux outils au nom d'un utilisateur : authentifiez l'agent agissant en tant qu'utilisateur individuel avec OAuth en trois étapes (3LO). Ce modèle est recommandé lorsque l'agent doit accéder à des outils au nom de la personne qui interagit avec lui, ce qui nécessite le consentement de l'utilisateur et une autorisation déléguée.

Ces modèles nécessitent que vous créiez un fournisseur d'authentification. Ensuite, vous créez 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 pour qu'il gère les clés API ou l'authentification OAuth à deux étapes (2LO) :

Créer le fournisseur d'authentification : créez un fournisseur d'authentification dans le gestionnaire d'authentification 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.
Lier le fournisseur d'authentification : pour permettre à votre agent orchestrateur de détecter le fournisseur d'authentification approprié pour une cible, vous devez créer une liaison dans le registre d'agents entre votre agent, la ressource cible et le fournisseur d'authentification. Avec les liaisons, vous n'avez pas besoin de définir manuellement les fournisseurs d'authentification dans votre code :
gcloud
Créez une liaison pour associer explicitement votre agent à la ressource cible et au fournisseur d'authentification en exécutant la commande gcloud agent-registry bindings create. Lorsque vous spécifiez le nom de la ressource --auth-provider-binding, vous devez utiliser l'ID du projet de gouvernance :
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
Configurez la ressource google_agent_registry_binding pour associer votre agent et votre ressource cible au fournisseur d'authentification :
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" } }
Remplacez les éléments suivants :
- BINDING_NAME : identifiant unique de la liaison.
- PROJECT_ID : ID de votre projet de gouvernance.
- LOCATION : région ou emplacement du registre, par exemple us-central1 ou global.
- DISPLAY_NAME : nom à afficher lisible par l'humain pour la liaison.
- SOURCE_ID : identifiant de l'agent source au format URN.
- TARGET_ID : identifiant de registre du serveur ou du point de terminaison MCP cible au format URN.
- AUTH_PROVIDER_ID : ID de votre fournisseur d'authentification.
Pour en savoir plus sur la gestion de ces liaisons, 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 au nom d'un utilisateur individuel, utilisez OAuth en trois étapes (3LO) via le gestionnaire d'authentification.

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. Lorsqu'un utilisateur final interagit avec l'agent et déclenche un outil qui nécessite des autorisations déléguées, la plate-forme demande automatiquement son consentement à l'utilisateur, stocke les identifiants et reprend le workflow :

Créer le fournisseur d'authentification : créez un fournisseur d'authentification dans le gestionnaire d'authentification 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.
Mettre à jour l'application cliente : mettez à jour votre application cliente pour gérer l'appel de fonction adk_request_credential et le consentement utilisateur. Pour obtenir des instructions détaillées, consultez Mettre à jour votre application côté client.
Lier le fournisseur d'authentification : pour permettre à votre agent orchestrateur de détecter le fournisseur d'authentification approprié pour une cible, vous devez créer une liaison dans le registre d'agents entre votre agent, la ressource cible et le fournisseur d'authentification. Avec les liaisons, vous n'avez pas besoin de définir manuellement les fournisseurs d'authentification dans votre code :
gcloud
Créez une liaison pour associer explicitement votre agent à la ressource cible et au fournisseur d'authentification en exécutant la commande gcloud agent-registry bindings create. Lorsque vous spécifiez le nom de la ressource --auth-provider-binding, vous devez utiliser l'ID du projet de gouvernance :
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
Configurez la ressource google_agent_registry_binding avec vos champs d'application OAuth 2.0 et l'URI de continuation :
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" } }
Remplacez les éléments suivants :
- BINDING_NAME : identifiant unique de la liaison.
- PROJECT_ID : ID de votre projet de gouvernance.
- LOCATION : région ou emplacement du registre, par exemple us-central1 ou global.
- DISPLAY_NAME : nom à afficher lisible par l'humain pour la liaison.
- SOURCE_ID : identifiant de l'agent source au format URN.
- TARGET_ID : identifiant de registre de la ressource de serveur ou d'outil MCP cible au format URN.
- AUTH_PROVIDER_ID : ID de votre fournisseur d'authentification.
- SCOPES : liste de champs d'application OAuth 2.0 séparés par une virgule, par exemple https://www.googleapis.com/auth/cloud-platform. Dans Terraform, placez chaque champ d'application entre guillemets doubles.
- REDIRECT_URI : URI de redirection configuré pour votre fournisseur d'authentification après le consentement utilisateur.
Pour en savoir plus sur la gestion de ces liaisons, 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 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],
)

Remplacez SERVER_ID par l'ID de votre serveur MCP enregistré.

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 l'emplacement vers lequel l'utilisateur final est redirigé après avoir donné son consentement :

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

Remplacez les éléments suivants :

SERVER_ID : ID de votre serveur MCP enregistré.
REDIRECT_URI : URI de redirection de votre application vers lequel l'utilisateur est envoyé après avoir donné son consentement.

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

Si vous devez vous authentifier ou transmettre des en-têtes de requête sans utiliser le gestionnaire d'authentification, fournissez 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 McpToolset associe automatiquement ces en-têtes aux requêtes en aval envoyées au serveur MCP.

Les en-têtes personnalisés fournis par le rappel header_provider ne sont envoyés qu'aux serveurs MCP cibles. 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 les ADC.

Cet exemple montre comment fournir une clé API ou un jeton de support 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 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)