Resuelve extremos y compila orquestadores

El Kit de desarrollo de agentes (ADK) proporciona un cliente AgentRegistry dedicado que te permite descubrir, buscar y conectarte de forma programática a agentes de IA y servidores del Protocolo de contexto del modelo (MCP) catalogados en Agent Registry.

En lugar de codificar las URLs de los extremos en tu aplicación, puedes usar el ADK para resolver estos extremos en el tiempo de ejecución.

Agent Registry proporciona los endpoints subyacentes, pero las implementaciones de producción suelen enrutar estas invocaciones a través de Agent Gateway. Agent Gateway te ayuda a aplicar políticas de seguridad, realizar la mediación de protocolos y aplicar el filtrado de contenido a las herramientas que descubres.

En este documento, se describe cómo recuperar agentes remotos y conjuntos de herramientas de MCP desde Agent Registry, y cómo incluirlos en un agente orquestador principal.

Antes de comenzar

Antes de integrar el ADK con el Registro de agentes, completa los siguientes pasos:

  1. Configura Agent Registry en tu proyecto.

  2. Instala el ADK o actualízalo a la versión más reciente con las dependencias de A2A necesarias:

    pip 

    pip install --upgrade "google-adk[a2a]"

    uv 

    uv add "google-adk[a2a]"

    Debes actualizar a la versión google-adk>=1.29.0, como mínimo.

  3. Configura las credenciales predeterminadas de la aplicación (ADC):

    gcloud auth application-default login

Las credenciales del ADC deben tener los permisos de IAM necesarios para los servicios subyacentes con los que interactúan los agentes o las herramientas. De manera opcional, también puedes usar encabezados personalizados para los conjuntos de herramientas externos. Para obtener más información, consulta Cómo autenticarse en herramientas y recursos.

Configura las variables de entorno

Para seguir esta guía, configura las siguientes variables de entorno:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • LOCATION: Es la región o ubicación del registro, como us-central1.

Inicializa el cliente del registro

Para interactuar con tu registro de forma programática, inicializa el cliente de AgentRegistry con tu proyecto y ubicación:

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

# Initialize the client
registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

Cómo componer un sistema multiagente

El ADK abstrae los mecanismos de conexión subyacentes, lo que te permite diseñar aplicaciones escalables componiendo varios agentes especializados en jerarquías flexibles.

Puedes usar el cliente del registro para recuperar recursos específicos y pasarlos directamente a la definición de un nuevo agente LlmAgent. Tu orquestador puede invocar agentes remotos como subagentes y ejecutar herramientas del MCP como si fueran funciones de Python locales.

Usa los siguientes métodos:

  • Para recuperar un agente remoto: Usa get_remote_a2a_agent()
  • Para recuperar un conjunto de herramientas del MCP: Usa get_mcp_toolset()

En el siguiente ejemplo, se muestra cómo componer un sistema multiagente creando un agente de orquestación que aprovecha un agente de viajes registrado y un servidor de MCP de Compute Engine registrado. En este ejemplo, la autenticación se controla con la identidad propia del agente, pero puedes usar otros métodos, como claves de API y OAuth. Para obtener más información, consulta Cómo autenticarse en herramientas y recursos.

Para diseñar y coordinar agentes con una interfaz visual que requiere poco código, configura los subagentes registrados directamente en el lienzo de Agent Studio. Para obtener más información, consulta Cómo diseñar agentes en Agent Studio.

import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent

# Define the GoogleAuth class for the HTTP client
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

# 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"

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client
)

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

# Compose the orchestrator agent
main_agent = LlmAgent(
    model="MODEL_ID", # Replace with a model such as gemini-1.5-flash
    name="travel_orchestrator",
    instruction="""You are a travel coordinator. You can use your
                   subagents to book travel and your tools to query
                   historical travel data.""",
    tools=[my_mcp_toolset],
    sub_agents=[my_remote_agent],
)

# You can now run your orchestrator agent
# response = await main_agent.run('Book a flight to Paris and check my past trips.')

Prácticas recomendadas para reutilizar agentes

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

Un agente solo puede tener un agente superior a la vez. Si intentas asignar la misma instancia del agente recuperado a varios orquestadores, es posible que el ADK arroje un error que indique que el agente ya tiene un elemento superior.

Para reutilizar un agente descubierto en varios agentes principales, usa el método .clone() para crear una instancia nueva del objeto del agente.

En el siguiente ejemplo, se muestra cómo recuperar un agente una vez y clonarlo para usarlo en diferentes orquestadores:

import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent

# Define the GoogleAuth class for the HTTP client
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

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))

# Fetch the remote agent once during startup
# Use the 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 = f"projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID"
base_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client
)

# Use .clone() to assign the agent to different parent orchestrators
flight_orchestrator = LlmAgent(
    model="gemini-1.5-flash",
    name="flight_orchestrator",
    sub_agents=[base_remote_agent.clone()]
)

hotel_orchestrator = LlmAgent(
    model="gemini-1.5-flash",
    name="hotel_orchestrator",
    sub_agents=[base_remote_agent.clone()]
)

¿Qué sigue?