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:
- Configura el Registro de agentes.
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.
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 httpxConfigura 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 loginConfigura las siguientes variables de entorno:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATIONReemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de tu proyecto de administración.LOCATION: Es la ubicación de Agent Registry en la que se registran tus agentes y servidores de MCP, comoglobalous-central1.
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 formatoagents/AGENT_ID, que usa el ID del proyecto y la ubicación configurada en el cliente deAgentRegistry, o el nombre de recurso completo en el formatoprojects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Cuando existe un administrador de autenticaciónBindingpara el agente,get_remote_a2a_agent()configura las credenciales de la solicitud automáticamente. Cuando no exista ningúnBinding, pasa unhttpx_clientpersonalizado configurado con un controladorhttpx.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
GoogleApiAuthimplementa un controladorhttpx.Authpara llamar a un subagente de A2A de la API deGoogle Cloud (https://*.googleapis.com). Usagoogle.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 encabezadosAuthorizationyX-Goog-User-Projecten cada solicitud.El cliente
registryrecupera el agente secundario de A2A remoto y el conjunto de herramientas de MCP remoto de Agent Registry, y los pasa aLlmAgenta través de los parámetrossub_agentsytools.
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:
- Detección: Autentícate en la API de Agent Registry con un token de acceso de OAuth 2.0
para recuperar el recurso
Agentdel agente secundario de destino y, luego, inspeccionar su tarjeta de agente. - 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.como un token de ID de OIDC para los extremos del agente de Cloud Run y de IAP. Luego, envía una solicitud de A2ASendMessage. El resultado devuelve un objeto JSONSendMessageResponse, que contiene un campotaskomessageen 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:
Autentícate en Agent Registry con un token de acceso de OAuth 2.0 y recupera el recurso
Agentdel 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_IDpor el ID del agente secundario de A2A registrado al que deseas llamar, por ejemplo,agentregistry-01234456-7890-abcd-1234-567890abcdef.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", "")Prepara los encabezados de la solicitud con un token de acceso de OAuth 2.0 para los extremos del agente de
*.googleapis.como 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}"Dar formato a la solicitud
SendMessagede 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
SendMessagepara la versión1.0de A2A. Si necesitas negociar entre las versiones1.0y0.3del protocolo A2A automáticamente, usa el ADK o el cliente de Pythona2a-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?
- Revisa el protocolo A2A para conocer las vinculaciones de transporte y los estados del ciclo de vida de las tareas.
- Obtén más información para configurar Agent Gateway y enrutar y administrar el tráfico de tus extremos de agentes de destino.
- Obtén información para autenticarte en herramientas y recursos y definir el alcance de las credenciales en las llamadas de agentes.
- Obtén más información para registrar habilidades y administrarlas en Agent Registry.