Resuelve extremos y compila orquestadores

El Kit de desarrollo de agentes (ADK) proporciona un cliente de 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) registrados 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 entorno de ejecución y componerlos en un agente de organización superior.

Agent Registry proporciona los extremos subyacentes. Para las implementaciones de producción, puedes enrutar las invocaciones a través de Agent Gateway para aplicar políticas de seguridad, realizar mediaciones de protocolos y aplicar filtros de contenido.

Antes de comenzar

Antes de integrar el ADK con Agent Registry, completa lo siguiente:

  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 o actualiza a la versión más reciente del ADK con las dependencias de A2A, Agent Identity y MCP:

    pip 

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

    uv 

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

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

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

    gcloud auth application-default login

Tus credenciales deben tener los permisos de Identity and Access Management (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 conjuntos de herramientas externos. Para obtener más información, consulta Autentica en herramientas y recursos.

Configura las variables de entorno

Configura las siguientes variables de entorno:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION

Reemplaza lo siguiente:

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

Inicializa el cliente de registro

Para interactuar con tu registro de forma programática, inicializa el cliente de AgentRegistry con tu proyecto y ubicación de administració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,
)

Crea un sistema multiagente

El ADK abstrae la mecánica de conexión subyacente, lo que te permite diseñar aplicaciones escalables organizando varios agentes especializados en jerarquías flexibles.

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

Para recuperar un agente remoto o un conjunto de herramientas de MCP, llama a los siguientes métodos de cliente de AgentRegistry en el código de tu agente de Python:

  • Para recuperar un agente remoto, usa get_remote_a2a_agent().
  • Para recuperar un conjunto de herramientas de MCP, usa get_mcp_toolset().

En el siguiente ejemplo, se muestra cómo componer un sistema multiagente creando un agente de organizació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 propia identidad del agente, pero puedes usar otros métodos, como las claves de API y OAuth 2.0. Para obtener más información, consulta Autentica en herramientas y recursos.

Para diseñar y organizar agentes con una interfaz visual con poco código, configura los agentes secundarios registrados directamente en el lienzo de Agent Studio en Gemini Enterprise Agent Platform. Para obtener más información, consulta Diseña 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.')

Reemplaza lo siguiente:

  • AGENT_ID: Es el ID de tu agente registrado.
  • SERVER_ID: Es el ID de tu servidor de MCP registrado.
  • MODEL_ID: Es el ID del modelo de tu agente de orquestador, por ejemplo, gemini-1.5-flash.

Prácticas recomendadas para reutilizar agentes

Para minimizar la latencia de 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 de agente recuperada a varios coordinadores, el ADK podría arrojar un error que indique que el agente ya tiene un superior.

Para volver a usar un agente descubierto en varios agentes superiores, 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 coordinadores:

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

Reemplaza lo siguiente:

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

¿Qué sigue?