Crear sistemas multiagente y llamar a agentes A2A

En los sistemas multiagente, un agente organizador delega tareas a agentes y herramientas de destino especializados. Esos agentes de destino se convierten en subagentes del sistema o la aplicación multiagente.

Con Agent Registry, tu agente de organización puede buscar endpoints de Agent2Agent (A2A) y del Protocolo de contexto del modelo (MCP) de forma dinámica en el entorno de ejecución sin codificar de forma fija las URLs de servicio en el código de la aplicación. Puedes recuperar agentes registrados y servidores de MCP para crear agentes de organización con el cliente AgentRegistry en el Kit de desarrollo de agentes (ADK) o las bibliotecas estándar HTTP y google-auth.

Cuando un agente de organización llama al extremo de un agente de destino, envía la solicitud directamente al Agent Runtime del agente de destino o al servidor de MCP. Para aplicar políticas de seguridad, realizar la mediación de protocolos y aplicar el filtrado de contenido en los extremos de los agentes de destino, puedes enrutar las llamadas de los agentes a través de Agent Gateway.

Antes de comenzar

Antes de buscar las URLs de los extremos de los agentes de destino o llamar a los agentes A2A a través del Registro de agentes, completa los siguientes pasos:

  1. Configura el Registro de agentes.
  2. Para una configuración de un solo proyecto, obtén el ID del proyecto del proyecto de administración en el que está habilitado el Registro de agentes. Si configuraste un límite de administración para varios proyectos, usa el ID de tu proyecto de administración para el descubrimiento y el registro en todo el límite, o especifica un ID del proyecto miembro para las operaciones de un solo proyecto.

  3. Instala las dependencias del cliente para tu framework:

    ADK (pip)

    pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
    

    Debes instalar al menos google-adk>=1.29.0.

    ADK (uv)

    uv add "google-adk[a2a,agent-identity,mcp]"
    

    Debes instalar al menos google-adk>=1.29.0.

    Python sin ADK

    pip install --upgrade google-auth requests httpx
    
  4. Configura las credenciales predeterminadas de la aplicación (ADC) para el desarrollo local. De lo contrario, adjunta una cuenta de servicio o un archivo de configuración de credenciales de la federación de identidades para cargas de trabajo en entornos externos:

    gcloud auth application-default login
    
  5. Configura las siguientes variables de entorno:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=LOCATION
    

    Reemplaza lo siguiente:

Roles obligatorios

Puedes usar tu cuenta de usuario para el desarrollo local, o bien una cuenta de servicio o un principal del agente para que tu agente de organización descubra los componentes registrados y llame a los agentes A2A de destino. La cuenta de usuario, la cuenta de servicio o el principal del agente deben tener los roles adecuados para descubrir componentes y llamar a los agentes A2A de destino.

Para asegurarte de que tu cuenta de usuario, cuenta de servicio o principal del agente tenga los permisos necesarios para descubrir componentes registrados y llamar a agentes A2A de destino, pídele a tu administrador que otorgue los siguientes roles de IAM a tu cuenta de usuario, cuenta de servicio o principal del agente en el proyecto de administración en el que está habilitado el Registro de agentes:

  • Para descubrir agentes y servidores de MCP registrados: Visualizador de la API de Agent Registry (roles/agentregistry.viewer)
  • Para llamar a un agente A2A de destino en el entorno de ejecución: El rol de entorno de ejecución o de puerta de enlace para el servicio que aloja al agente de destino, necesario para llamar a ese agente. Por ejemplo, si el agente de destino se ejecuta en Cloud Run, la cuenta o el principal deben tener el rol de Invocador de Cloud Run (roles/run.invoker).

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a tu cuenta de usuario, cuenta de servicio o principal del agente los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Elige las credenciales para los extremos de los agentes A2A de destino

Buscar un componente en el registro de agentes y llamar a su extremo de agente A2A de destino requiere tokens de autenticación independientes. Cuando tu agente de organización llama a un extremo de agente A2A de destino, debe adjuntar el tipo de token del portador que espera ese extremo:

Extremo del agente A2A de destino Token del portador obligatorio Fuente de credenciales y guías
Extremos de agentes de la API deGoogle Cloud (https://*.googleapis.com) Token de acceso de OAuth 2.0 con el permiso https://www.googleapis.com/auth/cloud-platform o un permiso de servicio más restringido. Cuando uses las credenciales predeterminadas de la aplicación (ADC) que no tengan configurado un proyecto de cuota predeterminado, incluye el encabezado X-Goog-User-Project para especificar el proyecto que se facturará por la cuota de la API. Para obtener más detalles, consulta Configura el proyecto de cuota con una solicitud de REST. google.auth.default() con las credenciales predeterminadas de la aplicación (ADC), una cuenta de servicio adjunta o una configuración de credenciales de la federación de identidades para cargas de trabajo. Para restringir los permisos por llamada, consulta Usa la identidad temporal como cuenta de servicio.
Extremos de agentes HTTPS de Cloud Run o Identity-Aware Proxy (IAP) (https://*.run.app o dominios personalizados) Token de ID cuya reclamación aud coincide con la URL del servicio de destino o el ID de cliente de OAuth 2.0 de IAP. google.oauth2.id_token.fetch_id_token() con una cuenta de servicio o el servidor de metadatos de Compute. Para obtener instrucciones de configuración, consulta Obtén un token de ID, Autenticación de servicio a servicio en Cloud Run y Autenticación programática para IAP.
Agentes externos o de SaaS vinculados a OAuth Token de OAuth 2.0 de 2 segmentos, token de OAuth 2.0 de 3 segmentos o clave de API. Se administra automáticamente en ADK cuando se adjunta una vinculación del administrador de autenticación de Agent Identity al agente. Para obtener instrucciones de configuración, consulta Autentica en herramientas y recursos.

Inicializa el cliente de AgentRegistry en el ADK

Para interactuar con el Registro de agentes a través del ADK, inicializa el cliente AgentRegistry en tu código de Python con el ID del proyecto de administración y la ubicación del Registro de agentes:

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

Después de inicializar el cliente AgentRegistry del ADK, puedes recuperar agentes A2A remotos y herramientas de MCP remotas de Agent Registry. En el ADK, los agentes A2A registrados se unen como instancias de RemoteA2aAgent. Estas instancias se denominan agentes remotos porque el ADK les delega tareas a través de la red en lugar de ejecutarlas en el proceso local. De manera similar, los servidores de MCP remotos registrados se unen como instancias de McpToolset.

Compón un sistema multiagente con el ADK

Para recuperar subagentes de A2A remotos y conjuntos de herramientas de MCP remotos de Agent Registry y, luego, incluirlos en una definición de agente de organización de LlmAgent, usa el cliente AgentRegistry inicializado:

  • Para recuperar un agente A2A remoto, llama a registry.get_remote_a2a_agent() con el nombre de recurso relativo del subagente. Este nombre de recurso puede ser un nombre de recurso relativo en el formato agents/AGENT_ID, que usa el ID del proyecto y la ubicación configurada en el cliente de AgentRegistry, o el nombre de recurso completo en el formato projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Cuando existe un administrador de autenticación Binding para el agente, get_remote_a2a_agent() configura las credenciales de la solicitud automáticamente. Cuando no exista ningún Binding, pasa un httpx_client personalizado configurado con un controlador httpx.Auth.
  • Para recuperar un conjunto de herramientas de MCP remoto, llama a registry.get_mcp_toolset() con el nombre de recurso relativo del servidor de MCP (mcpServers/SERVER_ID) o el nombre de recurso completo (projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID).

En el siguiente ejemplo, se muestra cómo definir un agente de organización en un archivo agent.py de ADK. En este ejemplo, ten en cuenta lo siguiente:

  • La clase GoogleApiAuth implementa un controlador httpx.Auth para llamar a un subagente de A2A de la API deGoogle Cloud (https://*.googleapis.com). Usa google.auth.default() para cargar tus credenciales predeterminadas de la aplicación, la cuenta de servicio adjunta o las credenciales de la federación de identidades para cargas de trabajo, y establece los encabezados Authorization y X-Goog-User-Project en cada solicitud.

  • El cliente registry recupera el agente secundario de A2A remoto y el conjunto de herramientas de MCP remoto de Agent Registry, y los pasa a LlmAgent a través de los parámetros sub_agents y 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],
)

Reemplaza lo siguiente:

  • QUOTA_PROJECT_ID: Es el ID del proyecto que se usa para la atribución de cuotas y facturación en las solicitudes a los extremos del agente de la API deGoogle Cloud .
  • AGENT_ID: Es el ID del agente secundario de A2A registrado al que deseas que llame tu agente de organización, por ejemplo, agentregistry-01234456-7890-abcd-1234-567890abcdef.
  • SERVER_ID: Es el ID del servidor de MCP registrado que deseas que use tu agente de organización.
  • MODEL_ID: Es el ID del modelo para tu agente orquestador, por ejemplo, gemini-2.5-flash.

Después de guardar root_agent en el archivo agent.py de tu proyecto del ADK, puedes probar y ejecutar tu agente de organización de forma local con los comandos de la CLI de adk run o adk web, o implementarlo en Agent Runtime en Gemini Enterprise Agent Platform. Para obtener instrucciones completas sobre la estructura y la ejecución del proyecto, consulta la guía de inicio rápido de ADK para Python y el ejemplo de registro de agentes de ADK en GitHub.

Llama a un agente A2A desde un cliente que no sea del ADK

Si compilas un agente o cliente de Orchestrator personalizado sin ADK, tu aplicación realiza dos pasos autenticados:

  1. Detección: Autentícate en la API de Agent Registry con un token de acceso de OAuth 2.0 para recuperar el recurso Agent del agente secundario de destino y, luego, inspeccionar su tarjeta de agente.
  2. Llamada de entorno de ejecución: Adjunta el token del portador que requiere el extremo del agente de destino, que es un token de acceso de OAuth 2.0 para los extremos del agente de *.googleapis.com o un token de ID de OIDC para los extremos del agente de Cloud Run y de IAP. Luego, envía una solicitud de A2A SendMessage. El resultado devuelve un objeto JSON SendMessageResponse, que contiene un campo task o message en el formato {"task": ...} o {"message": ...}. Este campo contiene la respuesta del agente secundario, que tu agente de organización puede analizar y usar en su flujo de trabajo.

Para buscar y llamar a un subagente de A2A registrado con google-auth y httpx, completa los siguientes pasos:

  1. Autentícate en Agent Registry con un token de acceso de OAuth 2.0 y recupera el recurso Agent del agente secundario desde la API de 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()
    

    Reemplaza AGENT_ID por el ID del agente secundario de A2A registrado al que deseas llamar, por ejemplo, agentregistry-01234456-7890-abcd-1234-567890abcdef.

  2. Extrae la interfaz de A2A basada en HTTP de la tarjeta de agente en el recurso 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. Prepara los encabezados de la solicitud con un token de acceso de OAuth 2.0 para los extremos del agente de *.googleapis.com o un token de ID de OIDC para los extremos del agente de Cloud Run o 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. Dar formato a la solicitud SendMessage de A2A y enviarla con la vinculación de protocolo de la tarjeta de agente, y analizar la respuesta del agente secundario:

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

    Este paso formatea una solicitud de SendMessage para la versión 1.0 de A2A. Si necesitas negociar entre las versiones 1.0 y 0.3 del protocolo A2A automáticamente, usa el ADK o el cliente de Python a2a-sdk.

Reutiliza agentes remotos en agentes de organización en el ADK

Para minimizar la latencia de red, recupera tus agentes remotos y conjuntos de herramientas del registro de agentes una vez al inicio de la aplicación, en lugar de llamar a get_remote_a2a_agent() en cada solicitud.

En ADK, una instancia de RemoteA2aAgent solo puede tener un agente de organización superior a la vez. Continuando desde la configuración de inicialización, llama a .clone() para crear una copia independiente para cada agente de organización superior:

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

Reemplaza AGENT_ID por el ID del agente secundario de A2A registrado al que quieres que llamen tus agentes de organización.

¿Qué sigue?