Dans les systèmes multi-agents, un agent orchestrateur délègue des tâches à des agents et des outils cibles spécialisés. Ces agents cibles deviennent des sous-agents du système ou de l'application multi-agent.
Avec Agent Registry, votre agent orchestrateur peut rechercher des points de terminaison Agent2Agent (A2A) et MCP (Model Context Protocol) de manière dynamique au moment de l'exécution, sans coder en dur les URL de service dans le code de votre application. Vous pouvez récupérer des agents enregistrés et des serveurs MCP pour créer des agents d'orchestration à l'aide du client AgentRegistry dans l'Agent Development Kit (ADK) ou des bibliothèques HTTP et google-auth standards.
Lorsqu'un agent orchestrateur appelle le point de terminaison d'un agent cible, il envoie la requête directement à l'environnement d'exécution de l'agent cible ou au serveur MCP. Pour appliquer des règles de sécurité, effectuer une médiation de protocole et appliquer un filtrage de contenu sur vos points de terminaison d'agent cibles, vous pouvez acheminer les appels d'agent via Agent Gateway.
Avant de commencer
Avant de rechercher les URL des points de terminaison des agents cibles ou d'appeler des agents A2A via Agent Registry, procédez comme suit :
- Configurer le registre d'agents.
Pour une configuration à projet unique, obtenez l'ID de projet du projet de gouvernance où le registre d'agents est activé. Si vous avez configuré une limite de gestion pour plusieurs projets, utilisez l'ID de votre projet de gestion pour la découverte et l'enregistrement à l'échelle de la limite, ou spécifiez l'ID d'un projet membre pour les opérations sur un seul projet.
Installez les dépendances client pour votre framework :
ADK (pip)
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"Vous devez installer au moins
google-adk>=1.29.0.ADK (uv)
uv add "google-adk[a2a,agent-identity,mcp]"Vous devez installer au moins
google-adk>=1.29.0.Python non ADK
pip install --upgrade google-auth requests httpxConfigurez les identifiants par défaut de l'application (ADC) pour le développement local. Sinon, associez un compte de service ou une configuration d'identifiants de fédération d'identité de charge de travail dans des environnements externes :
gcloud auth application-default loginConfigurez les variables d'environnement suivantes :
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATIONRemplacez les éléments suivants :
PROJECT_ID: ID de votre projet de gouvernance.LOCATION: emplacement Agent Registry où vos agents et serveurs MCP sont enregistrés, par exempleglobalouus-central1.
Rôles requis
Vous pouvez utiliser votre compte utilisateur pour le développement local, ou un compte de service ou un principal d'agent pour que votre agent orchestrateur découvre les composants enregistrés et appelle les agents A2A cibles. Le compte utilisateur, le compte de service ou le principal d'agent doit disposer des rôles appropriés pour détecter les composants et appeler les agents A2A cibles.
Pour vous assurer que votre compte utilisateur, votre compte de service ou votre principal d'agent dispose des autorisations nécessaires pour découvrir les composants enregistrés et appeler les agents A2A cibles, demandez à votre administrateur d'accorder les rôles IAM suivants à votre compte utilisateur, votre compte de service ou votre principal d'agent sur le projet de gouvernance où Agent Registry est activé :
-
Pour découvrir les agents et les serveurs MCP enregistrés : Lecteur de l'API Agent Registry (
roles/agentregistry.viewer) -
Pour appeler un agent A2A cible au moment de l'exécution : rôle d'exécution ou de passerelle pour le service qui héberge l'agent cible, requis pour appeler cet agent. Par exemple, si l'agent cible s'exécute sur Cloud Run, le compte ou le compte principal doit disposer du rôle Demandeur Cloud Run (
roles/run.invoker).
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Votre administrateur peut également attribuer à votre compte utilisateur, à votre compte de service ou à votre principal d'agent les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Choisir les identifiants des points de terminaison de l'agent A2A cible
La recherche d'un composant dans le registre d'agents et l'appel de son point de terminaison d'agent A2A cible nécessitent des jetons d'authentification distincts. Lorsque votre agent orchestrateur appelle un point de terminaison d'agent A2A cible, il doit joindre le type de jeton de support attendu par ce point de terminaison :
| Point de terminaison de l'agent A2A cible | Jeton de support requis | Source des identifiants et guides |
|---|---|---|
Google Cloud Points de terminaison d'agent d'API (https://*.googleapis.com) |
Jeton d'accès OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/cloud-platform ou un champ d'application de service plus restreint. Lorsque vous utilisez des Identifiants par défaut de l'application (ADC) pour lesquels aucun projet de quota par défaut n'est configuré, incluez l'en-tête X-Goog-User-Project pour spécifier le projet facturé pour le quota d'API. Pour en savoir plus, consultez la section Définir le projet de quota avec une requête REST. |
google.auth.default() à l'aide des identifiants par défaut de l'application (ADC), d'un compte de service associé ou d'une configuration d'identifiants de fédération d'identité de charge de travail. Pour limiter les autorisations par appel, consultez Utiliser l'emprunt d'identité d'un compte de service. |
Points de terminaison d'agent HTTPS Cloud Run ou Identity-Aware Proxy (IAP) (https://*.run.app ou domaines personnalisés) |
Jeton d'ID dont la revendication aud correspond à l'URL du service cible ou à l'ID client OAuth 2.0 d'IAP. |
google.oauth2.id_token.fetch_id_token() à l'aide d'un compte de service ou du serveur de métadonnées Compute. Pour obtenir des instructions de configuration, consultez Obtenir un jeton d'ID, Authentification de service à service sur Cloud Run et Authentification programmatique pour IAP. |
| Agents externes ou SaaS liés à OAuth | Jeton OAuth 2.0 à deux branches, jeton OAuth 2.0 à trois branches ou clé API. | Géré automatiquement dans l'ADK lorsqu'une liaison de gestionnaire d'authentification Agent Identity est associée à l'agent. Pour obtenir des instructions de configuration, consultez S'authentifier auprès des outils et des ressources. |
Initialiser le client AgentRegistry dans ADK
Pour interagir avec Agent Registry via l'ADK, initialisez le client AgentRegistry dans votre code Python avec l'ID de votre projet de gouvernance et l'emplacement d'Agent Registry :
import os
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.")
registry = AgentRegistry(
project_id=project_id,
location=location,
)
Après avoir initialisé le client ADK AgentRegistry, vous pouvez récupérer des agents A2A distants et des outils MCP distants à partir d'Agent Registry. Dans ADK, les agents A2A enregistrés sont encapsulés en tant qu'instances RemoteA2aAgent. Ces instances sont appelées agents distants, car l'ADK leur délègue des tâches sur le réseau au lieu de les exécuter dans le processus local. De même, les serveurs MCP distants enregistrés sont encapsulés en tant qu'instances McpToolset.
Composer un système multi-agent avec ADK
Pour récupérer des sous-agents A2A distants et des ensembles d'outils MCP distants à partir d'Agent Registry et les inclure dans une définition d'agent orchestrateur LlmAgent, utilisez le client AgentRegistry initialisé :
- Pour récupérer un agent A2A distant : appelez
registry.get_remote_a2a_agent()avec le nom de ressource relatif du sous-agent. Ce nom de ressource peut être un nom de ressource relatif au formatagents/AGENT_ID, qui utilise l'ID du projet et l'emplacement configurés sur le clientAgentRegistry, ou le nom complet de la ressource au formatprojects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Lorsqu'un gestionnaire d'authentificationBindingexiste pour l'agent,get_remote_a2a_agent()configure automatiquement les identifiants de requête. Lorsqu'aucunBindingn'existe, transmettez unhttpx_clientpersonnalisé configuré avec un gestionnairehttpx.Auth. - Pour récupérer un ensemble d'outils MCP distant : appelez
registry.get_mcp_toolset()avec le nom de ressource relatif du serveur MCP (mcpServers/SERVER_ID) ou son nom de ressource complet (projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID).
L'exemple suivant montre comment définir un agent orchestrateur dans un fichier ADK agent.py. Dans cet exemple, tenez compte des points suivants :
La classe
GoogleApiAuthimplémente un gestionnairehttpx.Authpour appeler un sous-agent A2A de l'APIGoogle Cloud (https://*.googleapis.com). Il utilisegoogle.auth.default()pour charger vos Identifiants par défaut de l'application, votre compte de service associé ou vos identifiants de fédération d'identité de charge de travail, et définit les en-têtesAuthorizationetX-Goog-User-Projectsur chaque requête.Le client
registryrécupère le sous-agent A2A distant et l'ensemble d'outils MCP distant depuis Agent Registry, puis les transmet àLlmAgentvia les paramètressub_agentsettools.
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
class GoogleApiAuth(httpx.Auth):
def __init__(self, user_project_id: str):
self.user_project_id = user_project_id
self.creds, _ = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
def auth_flow(self, request):
if not self.creds.valid:
self.creds.refresh(Request())
request.headers["Authorization"] = f"Bearer {self.creds.token}"
request.headers["X-Goog-User-Project"] = self.user_project_id
yield request
quota_project_id = "QUOTA_PROJECT_ID"
agent_name = "agents/AGENT_ID"
httpx_client = httpx.AsyncClient(
auth=GoogleApiAuth(quota_project_id),
timeout=httpx.Timeout(60.0),
)
my_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_name,
httpx_client=httpx_client,
)
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
root_agent = LlmAgent(
model="MODEL_ID",
name="travel_orchestrator",
instruction=(
"You are a travel coordinator. Use your subagents to book travel "
"and your tools to query historical travel data."
),
tools=[my_mcp_toolset],
sub_agents=[my_remote_agent],
)
Remplacez les éléments suivants :
QUOTA_PROJECT_ID: ID du projet utilisé pour l'attribution des quotas et de la facturation sur les requêtes adressées aux points de terminaison de l'agent de l'APIGoogle Cloud .AGENT_ID: ID du sous-agent A2A enregistré que vous souhaitez que votre agent orchestrateur appelle, par exempleagentregistry-01234456-7890-abcd-1234-567890abcdef.SERVER_ID: ID du serveur MCP enregistré que vous souhaitez que votre agent orchestrateur utilise.MODEL_ID: ID de modèle de votre agent orchestrateur, par exemplegemini-2.5-flash.
Après avoir enregistré root_agent dans le fichier agent.py de votre projet ADK, vous pouvez tester et exécuter votre agent orchestrateur localement à l'aide des commandes CLI adk run ou adk web, ou le déployer sur Agent Runtime sur Gemini Enterprise Agent Platform. Pour obtenir la structure complète du projet et les instructions d'exécution, consultez le guide de démarrage rapide Python pour ADK et l'exemple de registre d'agents ADK sur GitHub.
Appeler un agent A2A depuis un client non ADK
Si vous créez un agent ou un client d'orchestrateur personnalisé sans ADK, votre application effectue deux étapes authentifiées :
- Découverte : authentifiez-vous auprès de l'API Agent Registry avec un jeton d'accès OAuth 2.0 pour récupérer la ressource
Agentdu sous-agent cible et inspecter sa fiche d'agent. - Appel d'exécution : associez le jeton de support requis par le point de terminaison de l'agent cible, qui est un jeton d'accès OAuth 2.0 pour les points de terminaison de l'agent
*.googleapis.comou un jeton d'ID OIDC pour les points de terminaison de l'agent Cloud Run et IAP. Ensuite, envoyez une requête A2ASendMessage. La sortie renvoie un objet JSONSendMessageResponse, qui contient un champtaskoumessageau format{"task": ...}ou{"message": ...}. Ce champ contient la réponse du sous-agent, que votre agent orchestrateur peut analyser et utiliser dans son workflow.
Pour rechercher et appeler un sous-agent A2A enregistré à l'aide de google-auth et httpx, procédez comme suit :
Authentifiez-vous auprès d'Agent Registry avec un jeton d'accès OAuth 2.0 et récupérez la ressource
Agentdu sous-agent à partir de l'API Agent Registry :import os import uuid from urllib.parse import urlparse import google.auth from google.auth.transport.requests import Request from google.oauth2 import id_token import httpx project_id = os.environ["GOOGLE_CLOUD_PROJECT"] location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global") agent_id = "AGENT_ID" creds, _ = google.auth.default( scopes=["https://www.googleapis.com/auth/cloud-platform"] ) creds.refresh(Request()) registry_url = ( f"https://agentregistry.googleapis.com/v1/projects/{project_id}" f"/locations/{location}/agents/{agent_id}" ) client = httpx.Client(timeout=60.0) reg_response = client.get( registry_url, headers={ "Authorization": f"Bearer {creds.token}", "X-Goog-User-Project": project_id, }, ) reg_response.raise_for_status() agent_resource = reg_response.json()Remplacez
AGENT_IDpar l'ID du sous-agent A2A enregistré que vous souhaitez appeler, par exempleagentregistry-01234456-7890-abcd-1234-567890abcdef.Extrayez l'interface A2A basée sur HTTP de la fiche d'agent dans la ressource
Agent:card = agent_resource.get("card", {}).get("content", {}) interfaces = card.get("supportedInterfaces") or ( (agent_resource.get("protocols") or [{}])[0].get("interfaces", []) ) iface = next( i for i in interfaces if i.get("protocolBinding", "HTTP+JSON") in ("HTTP+JSON", "HTTP_JSON", "JSONRPC") ) endpoint_url = iface["url"] binding = iface.get("protocolBinding", "HTTP+JSON") tenant = iface.get("tenant", "")Préparez les en-têtes de requête avec un jeton d'accès OAuth 2.0 pour les points de terminaison d'agent
*.googleapis.comou un jeton d'ID OIDC pour les points de terminaison d'agent Cloud Run ou IAP :host = urlparse(endpoint_url).hostname or "" headers = {"Content-Type": "application/json", "A2A-Version": "1.0"} if host == "googleapis.com" or host.endswith(".googleapis.com"): headers["Authorization"] = f"Bearer {creds.token}" headers["X-Goog-User-Project"] = project_id else: oidc_audience = f"https://{host}" oidc_jwt = id_token.fetch_id_token(Request(), oidc_audience) headers["Authorization"] = f"Bearer {oidc_jwt}"Formatez et envoyez la requête A2A
SendMessageà l'aide de la liaison de protocole de la carte d'agent, puis analysez la réponse du sous-agent :message = { "messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"text": "Summarize recent deployment status."}], } if binding == "JSONRPC": params = {"message": message} if tenant: params["tenant"] = tenant payload = { "jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": "SendMessage", "params": params, } target_url = endpoint_url else: payload = {"message": message} prefix = f"/{tenant.strip('/')}" if tenant else "" target_url = f"{endpoint_url.rstrip('/')}{prefix}/message:send" response = client.post(target_url, headers=headers, json=payload) response.raise_for_status() body = response.json() if binding == "JSONRPC": if "error" in body: raise RuntimeError(f"JSON-RPC error: {body['error']}") send_message_response = body["result"] else: send_message_response = body print(send_message_response) client.close()Cette étape formate une requête
SendMessagepour la version1.0d'A2A. Si vous devez négocier automatiquement entre les versions1.0et0.3du protocole A2A, utilisez l'ADK ou le client Pythona2a-sdk.
Réutiliser des agents distants dans des agents d'orchestration dans ADK
Pour minimiser la latence du réseau, récupérez vos agents et ensembles d'outils distants à partir du registre d'agents une seule fois au démarrage de l'application, au lieu d'appeler get_remote_a2a_agent() à chaque requête.
Dans ADK, une instance RemoteA2aAgent ne peut avoir qu'un seul agent orchestrateur parent à la fois. En continuant à partir de la configuration de l'initialisation, appelez .clone() pour créer une copie indépendante pour chaque agent d'orchestration parent :
agent_path = (
f"projects/{project_id}/locations/{location}"
"/agents/AGENT_ID"
)
base_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_path,
httpx_client=httpx_client,
)
flight_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="flight_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
hotel_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="hotel_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
Remplacez AGENT_ID par l'ID du sous-agent A2A enregistré que vos agents d'orchestration doivent appeler.
Étapes suivantes
- Consultez la section Protocole A2A pour en savoir plus sur les liaisons de transport et les états du cycle de vie des tâches.
- Découvrez comment configurer Agent Gateway pour acheminer et gérer le trafic vers vos points de terminaison d'agent cibles.
- Découvrez comment vous authentifier auprès des outils et des ressources et définir le champ d'application des identifiants pour les appels d'agent.
- Découvrez comment enregistrer des compétences et gérer des compétences dans Agent Registry.