Créer des systèmes multi-agents et appeler des agents A2A

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 :

  1. Configurer le registre d'agents.
  2. 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.

  3. 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 httpx
    
  4. Configurez 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 login
    
  5. Configurez les variables d'environnement suivantes :

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=LOCATION
    

    Remplacez les éléments suivants :

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 format agents/AGENT_ID, qui utilise l'ID du projet et l'emplacement configurés sur le client AgentRegistry, ou le nom complet de la ressource au format projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Lorsqu'un gestionnaire d'authentification Binding existe pour l'agent, get_remote_a2a_agent() configure automatiquement les identifiants de requête. Lorsqu'aucun Binding n'existe, transmettez un httpx_client personnalisé configuré avec un gestionnaire httpx.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 GoogleApiAuth implémente un gestionnaire httpx.Auth pour appeler un sous-agent A2A de l'APIGoogle Cloud (https://*.googleapis.com). Il utilise google.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êtes Authorization et X-Goog-User-Project sur chaque requête.

  • Le client registry récupère le sous-agent A2A distant et l'ensemble d'outils MCP distant depuis Agent Registry, puis les transmet à LlmAgent via les paramètres sub_agents et tools.

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 exemple agentregistry-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 exemple gemini-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 :

  1. 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 Agent du sous-agent cible et inspecter sa fiche d'agent.
  2. 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.com ou un jeton d'ID OIDC pour les points de terminaison de l'agent Cloud Run et IAP. Ensuite, envoyez une requête A2A SendMessage. La sortie renvoie un objet JSON SendMessageResponse, qui contient un champ task ou message au 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 :

  1. Authentifiez-vous auprès d'Agent Registry avec un jeton d'accès OAuth 2.0 et récupérez la ressource Agent du 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_ID par l'ID du sous-agent A2A enregistré que vous souhaitez appeler, par exemple agentregistry-01234456-7890-abcd-1234-567890abcdef.

  2. 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", "")
    
  3. 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.com ou 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}"
    
  4. 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 SendMessage pour la version 1.0 d'A2A. Si vous devez négocier automatiquement entre les versions 1.0 et 0.3 du protocole A2A, utilisez l'ADK ou le client Python a2a-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