Endpunkte auflösen und Orchestratoren erstellen

Das Agent Development Kit (ADK) bietet einen dedizierten AgentRegistry-Client, mit dem Sie programmatisch KI-Agenten und MCP-Server (Model Context Protocol) finden, suchen und eine Verbindung zu ihnen herstellen können, die in der Agent Registry registriert sind. Anstatt Endpunkt-URLs in Ihrer Anwendung hartzucodieren, können Sie das ADK verwenden, um diese Endpunkte zur Laufzeit aufzulösen und in einem übergeordneten Orchestrator-Agenten zusammenzufassen.

Die Agent Registry stellt die zugrunde liegenden Endpunkte bereit. Für Produktionsbereitstellungen können Sie Aufrufe über Agent Gateway weiterleiten, um Sicherheitsrichtlinien durchzusetzen, Protokollvermittlung durchzuführen und Inhaltsfilter anzuwenden.

Hinweis

Bevor Sie das ADK in die Agent Registry einbinden, müssen Sie Folgendes tun:

  1. Agent Registry einrichten

  2. Rufen Sie die Projekt-ID für das Governance-Projekt ab, in dem die Agent Registry aktiviert ist.

  3. Installieren oder führen Sie ein Upgrade auf die aktuelle Version des ADK mit den A2A-, Agent Identity- und MCP-Abhängigkeiten durch:

    pip 

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

    uv 

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

    Sie müssen ein Upgrade auf mindestens google-adk>=1.29.0 durchführen.

  4. Konfigurieren Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC):

    gcloud auth application-default login

Ihre Anmeldedaten müssen die erforderlichen IAM-Berechtigungen (Identity and Access Management) für die zugrunde liegenden Dienste haben, mit denen die Agenten oder Tools interagieren. Optional können Sie auch benutzerdefinierte Header für externe Toolsets verwenden. Weitere Informationen finden Sie unter Bei Tools und Ressourcen authentifizieren.

Umgebungsvariablen festlegen

Richten Sie die folgenden Umgebungsvariablen ein:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID Ihres Governance-Projekts.
  • LOCATION: die Registry-Region oder der Registry-Standort, z. B. us-central1.

Registry-Client initialisieren

Wenn Sie programmatisch mit Ihrer Registry interagieren möchten, initialisieren Sie den AgentRegistry-Client mit Ihrem Governance-Projekt und -Standort:

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

Multi-Agenten-System zusammenstellen

Das ADK abstrahiert die zugrunde liegenden Verbindungsmechanismen, sodass Sie skalierbare Anwendungen erstellen können, indem Sie mehrere spezialisierte Agenten in flexiblen Hierarchien zusammenfassen.

Mit dem Registry-Client können Sie bestimmte Ressourcen abrufen und direkt an die Definition eines neuen LlmAgent-Agenten übergeben. Ihr Orchestrator kann Remote-Agenten als Sub-Agenten aufrufen und MCP-Tools so ausführen, als wären sie lokale Python-Funktionen.

Wenn Sie einen Remote-Agenten oder ein MCP-Toolset abrufen möchten, rufen Sie die folgenden AgentRegistry-Clientmethoden in Ihrem Python-Agenten-Code auf:

  • Remote-Agent abrufen: Verwenden Sie get_remote_a2a_agent().
  • MCP-Toolset abrufen: Verwenden Sie get_mcp_toolset().

Im folgenden Beispiel wird gezeigt, wie Sie ein Multi-Agenten-System erstellen, indem Sie einen Orchestrator-Agenten erstellen, der einen registrierten Reise-Agenten und einen registrierten Compute Engine-MCP-Server verwendet. In diesem Beispiel wird die Authentifizierung über die eigene Identität des KI-Agenten abgewickelt. Sie können aber auch andere Methoden wie API-Schlüssel und OAuth 2.0 verwenden. Weitere Informationen finden Sie unter Bei Tools und Ressourcen authentifizieren.

Wenn Sie KI-Agenten über eine visuelle Low-Code-Oberfläche entwerfen und orchestrieren möchten, konfigurieren Sie registrierte Sub-Agenten direkt im Agent Studio auf dem Canvas der Gemini Enterprise Agent Platform. Weitere Informationen finden Sie unter Agenten in Agent Studio entwerfen.

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

Ersetzen Sie Folgendes:

  • AGENT_ID: die ID Ihres registrierten KI-Agenten.
  • SERVER_ID: die ID Ihres registrierten MCP-Servers.
  • MODEL_ID: die Modell-ID für Ihren Orchestrator-Agenten, z. B. gemini-1.5-flash.

Best Practices für die Wiederverwendung von Agenten

Um die Netzwerklatenz zu minimieren, rufen Sie Ihre Agenten und Toolsets beim Start der Anwendung einmal aus der Registry ab, anstatt bei jedem Aufruf get_remote_a2a_agent() aufzurufen.

Ein Agent kann jeweils nur einen übergeordneten Agenten haben. Wenn Sie versuchen, dieselbe abgerufene Agenteninstanz mehreren Orchestratoren zuzuweisen, gibt das ADK möglicherweise einen Fehler aus, der darauf hinweist, dass der Agent bereits einen übergeordneten Agenten hat.

Wenn Sie einen erkannten Agenten für mehrere übergeordnete Agenten wiederverwenden möchten, verwenden Sie die Methode .clone(), um eine neue Instanz des Agentenobjekts zu erstellen.

Im folgenden Beispiel wird gezeigt, wie Sie einen Agent einmal abrufen und für die Verwendung in verschiedenen Orchestratoren klonen:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID Ihres Governance-Projekts.
  • LOCATION: die Registry-Region oder der Registry-Standort, z. B. us-central1.
  • AGENT_ID: die ID Ihres registrierten KI-Agenten.

Nächste Schritte