GENAI124

Übersicht

In diesem Lab lernen Sie das Model Context Protocol (MCP) kennen, einen offenen Standard, der die nahtlose Einbindung externer Dienste, Datenquellen, Tools und Anwendungen ermöglicht. Sie erfahren, wie Sie das MCP in Ihre ADK-Agenten integrieren und die von vorhandenen MCP-Servern bereitgestellten Tools verwenden, um Ihre ADK-Workflows zu optimieren. Außerdem lernen Sie, wie Sie ADK-Tools wie load_web_page über einen benutzerdefinierten MCP-Server verfügbar machen, um eine umfassendere Einbindung von MCP-Clients zu ermöglichen.

Was ist das Model Context Protocol (MCP)?

Das Model Context Protocol (MCP) ist ein offener Standard, der die Kommunikation von Large Language Models (LLMs) wie Gemini und Claude mit externen Anwendungen, Datenquellen und Tools standardisieren soll. Es ist ein universeller Verbindungsmechanismus, der vereinfacht, wie LLMs Kontext abrufen, Aktionen ausführen und mit verschiedenen Systemen interagieren.

Das MCP entspricht einer Client-Server-Architektur, die definiert, wie Daten (Ressourcen), interaktive Vorlagen (Prompts) und ausführbare Funktionen (Tools) von einem MCP-Server bereitgestellt und von einem MCP-Client (einer LLM-Hostanwendung oder einem KI-Agenten) genutzt werden.

In diesem Lab werden zwei primäre Integrationsmuster behandelt:

• Vorhandene MCP-Server im ADK verwenden: Ein ADK-Agent fungiert als MCP-Client und nutzt Tools, die von externen MCP-Servern bereitgestellt werden.
• ADK-Tools über einen MCP-Server bereitstellen: Dabei wird ein MCP-Server erstellt, der ADK-Tools einbindet und sie so für jeden MCP-Client zugänglich macht.

Ziele

Aufgaben in diesem Lab:

• ADK-Agent als MCP-Client einsetzen, um mit Tools von vorhandenen MCP-Servern zu interagieren
• Eigenen MCP-Server konfigurieren und bereitstellen, um ADK-Tools für andere Clients verfügbar zu machen
• ADK-Agenten über standardisierte MCP-Kommunikation mit externen Tools verbinden
• Nahtlose Interaktion zwischen LLMs und Tools über das Model Context Protocol ermöglichen

Einrichtung und Anforderungen

Vor dem Klick auf "Start Lab" (Lab starten)

Lesen Sie diese Anleitung. Labs sind zeitlich begrenzt und können nicht pausiert werden. Der Timer, der mit dem Klick auf "Start Lab" (Lab starten) gestartet wird, gibt an, wie lange die Ressourcen für das Lab verfügbar sind.

In diesem praxisorientierten Qwiklabs-Lab können Sie die Lab-Aktivitäten selbst in einer echten Cloud-Umgebung durchführen, nicht in einer Simulations- oder Demo-Umgebung. Dazu erhalten Sie neue, temporäre Anmeldedaten, mit denen Sie für die Dauer des Labs auf die Google Cloud Platform zugreifen können.

Voraussetzungen

Für dieses Lab benötigen Sie Folgendes:

• Einen Standardbrowser (empfohlen wird Chrome)
• Genügend Zeit, um das Lab abzuschließen

Hinweis: Auch wenn Sie bereits ein eigenes GCP-Konto oder -Projekt haben, sollten Sie es nicht für das Lab verwenden.

Lab starten und bei der Google Cloud Console anmelden

1. Klicken Sie auf Lab starten. Wenn Sie für das Lab bezahlen müssen, wird ein Dialogfeld geöffnet, in dem Sie Ihre Zahlungsmethode auswählen können. Auf der linken Seite befindet sich der Bereich „Details zum Lab“ mit diesen Informationen:

   • Schaltfläche „Google Cloud Console öffnen“
   • Restzeit
   • Temporäre Anmeldedaten für das Lab
   • Ggf. weitere Informationen für dieses Lab

2. Klicken Sie auf Google Cloud Console öffnen (oder klicken Sie mit der rechten Maustaste und wählen Sie Link in Inkognitofenster öffnen aus, wenn Sie Chrome verwenden).

   Im Lab werden Ressourcen aktiviert. Anschließend wird ein weiterer Tab mit der Seite „Anmelden“ geöffnet.

   Tipp: Ordnen Sie die Tabs nebeneinander in separaten Fenstern an.

   Hinweis: Wird das Dialogfeld Konto auswählen angezeigt, klicken Sie auf Anderes Konto verwenden.

3. Kopieren Sie bei Bedarf den folgenden Nutzernamen und fügen Sie ihn in das Dialogfeld Anmelden ein.

   {{{user_0.username | "Username"}}}

   Sie finden den Nutzernamen auch im Bereich „Details zum Lab“.

4. Klicken Sie auf Weiter.

5. Kopieren Sie das folgende Passwort und fügen Sie es in das Dialogfeld Willkommen ein.

   {{{user_0.password | "Password"}}}

   Sie finden das Passwort auch im Bereich „Details zum Lab“.

6. Klicken Sie auf Weiter.

   Wichtig: Sie müssen die für das Lab bereitgestellten Anmeldedaten verwenden. Nutzen Sie nicht die Anmeldedaten Ihres Google Cloud-Kontos. Hinweis: Wenn Sie Ihr eigenes Google Cloud-Konto für dieses Lab nutzen, können zusätzliche Kosten anfallen.

7. Klicken Sie sich durch die nachfolgenden Seiten:

   • Akzeptieren Sie die Nutzungsbedingungen.
   • Fügen Sie keine Wiederherstellungsoptionen oder Zwei-Faktor-Authentifizierung hinzu (da dies nur ein temporäres Konto ist).
   • Melden Sie sich nicht für kostenlose Testversionen an.

Nach wenigen Augenblicken wird die Google Cloud Console in diesem Tab geöffnet.

Hinweis: Wenn Sie auf Google Cloud-Produkte und ‑Dienste zugreifen möchten, klicken Sie auf das Navigationsmenü oder geben Sie den Namen des Produkts oder Dienstes in das Feld Suchen ein.

Aufgabe 1: ADK installieren und Umgebung einrichten

In dieser Lab-Umgebung wurden die Vertex AI API, die Routes API und die Directions API für Sie aktiviert.

Cloud Shell-Editor-Tab vorbereiten

1. Wählen Sie das Google Cloud Console-Fenster aus und öffnen Sie die Cloud Shell, indem Sie auf der Tastatur die Taste G und dann die Taste S drücken. Alternativ können Sie rechts oben in der Cloud Console auf „Cloud Shell aktivieren“ () klicken.

2. Klicken Sie auf Weiter.

3. Wenn Sie zur Autorisierung der Cloud Shell aufgefordert werden, klicken Sie auf Autorisieren.

4. Klicken Sie oben rechts im Cloud Shell-Terminalbereich auf In neuem Fenster öffnen .

5. Geben Sie im Cloud Shell-Terminal Folgendes ein, um den Cloud Shell-Editor in Ihrem Basisverzeichnis zu öffnen:

   cloudshell workspace ~

6. Schließen Sie alle zusätzlichen Tutorials oder Gemini-Felder, die auf der rechten Seite des Bildschirms angezeigt werden, damit mehr Platz für den Code-Editor bleibt.

7. Im weiteren Verlauf dieses Labs dient dieses Fenster als IDE für das Arbeiten im Cloud Shell-Editor und Cloud Shell-Terminal.

ADK und Codebeispiele für dieses Lab herunterladen und installieren

1. Installieren Sie das ADK, indem Sie den folgenden Befehl im Cloud Shell-Terminal ausführen.

   Hinweis: Sie geben die Version an, damit die von Ihnen installierte ADK-Version der in diesem Lab verwendeten Version entspricht. Die aktuelle Versionsnummer und die Versionshinweise finden Sie im ADK-Python-Repository. sudo python3 -m pip install google-adk==1.5.0

2. Fügen Sie die folgenden Befehle in das Cloud Shell-Terminal ein, um eine Datei aus einem Cloud Storage-Bucket zu kopieren und zu entpacken. Dadurch wird ein Projektverzeichnis mit Code für dieses Lab erstellt:

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. Installieren Sie zusätzliche Lab-Voraussetzungen mit:

   python3 -m pip install -r adk_mcp_tools/requirements.txt

Klicken Sie auf Fortschritt prüfen. ADK installieren und Umgebung einrichten

Aufgabe 2: Google Maps-MCP-Server mit ADK-Agenten (ADK als MCP-Client) in adk web verwenden

In diesem Abschnitt wird gezeigt, wie Sie Tools von einem externen Google Maps-MCP-Server in Ihre ADK-Agenten einbinden. Dies ist das gängigste Integrationsmuster, wenn Ihr ADK-Agent Funktionen eines vorhandenen Dienstes nutzen soll, der eine MCP-Schnittstelle bereitstellt. Sie erfahren, wie die Klasse MCPToolset direkt zur Liste tools Ihres KI-Agenten hinzugefügt werden kann. So wird eine nahtlose Verbindung zu einem MCP-Server ermöglicht, seine Tools können erkannt und für Ihren KI-Agenten verfügbar gemacht werden. In diesen Beispielen liegt der Schwerpunkt hauptsächlich auf Interaktionen in der Entwicklungsumgebung adk web.

MCPToolset

Die Klasse MCPToolset ist der primäre Mechanismus des ADK zum Einbinden von Tools von einem MCP-Server. Wenn Sie eine Instanz von MCPToolset in die Liste tools Ihres KI-Agenten aufnehmen, übernimmt diese automatisch die Interaktion mit dem angegebenen MCP-Server. Das geht so:

• Verbindungsverwaltung: Bei der Initialisierung stellt MCPToolset die Verbindung zum MCP-Server her und verwaltet sie. Das kann ein lokaler Serverprozess (mit StdioServerParameters für die Kommunikation über die Standardeingabe/‑ausgabe) oder ein Remote-Server (mit SseServerParams für vom Server gesendete Ereignisse) sein. Das Toolset übernimmt auch das ordnungsgemäße Herunterfahren dieser Verbindung, wenn der KI-Agent oder die Anwendung beendet wird.
• Toolerkennung und ‑anpassung: Nach der Verbindung fragt MCPToolset den MCP-Server nach den verfügbaren Tools ab (über die MCP-Methode list_tools). Anschließend werden die Schemas dieser erkannten MCP-Tools in ADK-kompatible Instanzen von BaseTool konvertiert.
• Zugriff des Agenten: Diese angepassten Tools werden dann Ihrem LlmAgent wie native Tools zur Verfügung gestellt.
• Weiterleitung von Toolaufrufen per Proxy: Wenn Ihr LlmAgent beschließt, eines dieser Tools zu verwenden, leitet MCPToolset den Aufruf transparent über die MCP-Methode call_tool an den MCP-Server weiter, sendet die erforderlichen Argumente und gibt die Antwort des Servers an den KI-Agenten zurück.
• Filtern (optional): Sie können beim Erstellen eines MCPToolset den Parameter tool_filter verwenden, um eine bestimmte Teilmenge von Tools vom MCP-Server auszuwählen, anstatt alle Tools für Ihren KI-Agenten verfügbar zu machen.

API-Schlüssel abrufen und APIs aktivieren

In diesem Unterabschnitt generieren Sie einen neuen API-Schlüssel mit dem Namen GOOGLE_MAPS_API_KEY.

1. Öffnen Sie den Browsertab mit der Google Cloud Console (nicht den Cloud Shell-Editor).

2. Sie können den Cloud Shell-Terminalbereich auf diesem Browsertab schließen, um mehr Platz zu haben.

3. Suchen Sie oben auf der Seite in der Suchleiste nach Anmeldedaten. Wählen Sie dies in den Ergebnissen aus.

4. Klicken Sie auf der Seite Anmeldedaten oben auf + Anmeldedaten erstellen und wählen Sie dann API-Schlüssel aus.

   Im Dialogfeld API-Schlüssel erstellt wird der neu erstellte API-Schlüssel angezeigt. Speichern Sie diesen Schlüssel lokal, da Sie ihn später im Lab noch brauchen.

5. Klicken Sie im Dialogfeld auf Schließen.

   Der neu erstellte Schlüssel heißt standardmäßig API-Schlüssel 1. Wählen Sie den Schlüssel aus, benennen Sie ihn in GOOGLE_MAPS_API_KEY um und klicken Sie auf Speichern.

   

KI-Agent mit einem MCPToolset für Google Maps definieren

In diesem Unterabschnitt konfigurieren Sie Ihren KI-Agenten so, dass er das MCPToolset für Google Maps verwendet. So kann er nahtlos Wegbeschreibungen und standortbezogene Informationen bereitstellen.

1. Suchen Sie im Datei-Explorer des Cloud Shell-Editors nach dem Ordner adk_mcp_tools. Klicken Sie darauf, um ihn zu öffnen.

2. Wechseln Sie in das Verzeichnis adk_mcp_tools/google_maps_mcp_agent.

3. Fügen Sie den folgenden Befehl in eine Nur-Text-Datei ein und ersetzen Sie den Wert YOUR_ACTUAL_API_KEY durch den Google Maps-API-Schlüssel, den Sie in einem vorherigen Schritt generiert und gespeichert haben:

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. Kopieren Sie den aktualisierten Befehl und fügen Sie ihn in das Cloud Shell-Terminal ein, um ihn auszuführen und eine .env-Datei zu schreiben, die Authentifizierungsdetails für dieses Agentenverzeichnis enthält.

5. Kopieren Sie die .env-Datei in das andere Agentenverzeichnis, das Sie in diesem Lab verwenden, indem Sie den folgenden Befehl ausführen:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. Fügen Sie als Nächstes den folgenden Code an der entsprechenden Stelle in der Datei agent.py ein, um Ihrem KI-Agenten das Google Maps-Tool hinzuzufügen. So kann der KI-Agent das MCPToolset für Google Maps verwenden, um Wegbeschreibungen oder standortbezogene Informationen bereitzustellen.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. Starten Sie die Agent Development Kit-Entwicklungsoberfläche über das Projektverzeichnis adk_mcp_tools mit dem folgenden Befehl:

   adk web

   Ausgabe:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. Klicken Sie in der Terminalausgabe auf den Link http://127.0.0.1:8000, um die Weboberfläche in einem neuen Tab aufzurufen.

9. Ein neuer Browsertab mit der ADK-Entwicklungsoberfläche wird geöffnet. Wählen Sie im Drop-down-Menü KI-Agent auswählen links google_maps_mcp_agent aus.

10. Starten Sie eine Unterhaltung mit dem KI-Agenten und führen Sie die folgenden Prompts aus:

    Get directions from GooglePlex to SFO. Hinweis: Falls bei Ihrem API-Aufruf beim ersten Mal eine Zeitüberschreitung auftritt, klicken Sie rechts oben in der ADK-Entwicklungsoberfläche auf + Neue Sitzung und versuchen Sie es noch einmal. Wie verläuft die Route von Paris nach Berlin?

    Ausgabe:

    

11. Klicken Sie auf das KI-Agentensymbol neben der Chat-Bubble des KI-Agenten mit dem Blitzsymbol. Dieses zeigt einen Funktionsaufruf an. Dadurch wird der Ereignis-Inspector für dieses Ereignis geöffnet:

    

12. Im Agentengraphen sind verschiedene Tools zu sehen, die durch das Schraubenschlüssel-Emoji (🔧) gekennzeichnet sind. Sie haben zwar nur ein MCPToolset importiert, dieses enthält aber die verschiedenen Tools, die hier aufgeführt sind, zum Beispiel maps_place_details und maps_directions.

    

13. Auf dem Tab Anfrage sehen Sie die Struktur der Anfrage. Mit den Pfeilen oben im Ereignis-Inspector können Sie die Überlegungen, Funktionsaufrufe und Antworten des KI-Agenten durchgehen.

14. Wenn Sie keine Fragen mehr an diesen KI-Agenten haben, schließen Sie den Browsertab mit der Entwicklungsoberfläche.

15. Kehren Sie zum Cloud Shell-Terminalbereich zurück und drücken Sie STRG + C, um den Server zu beenden.

Klicken Sie auf Fortschritt prüfen. API-Schlüssel erstellen und ADK-Agent bereitstellen

Aufgabe 3: MCP-Server mit ADK-Tools erstellen (MCP-Server stellt ADK bereit)

In diesem Abschnitt erfahren Sie, wie Sie das ADK-Tool load_web_page über einen benutzerdefinierten MCP-Server verfügbar machen. Mit diesem Muster können Sie vorhandene ADK-Tools einbinden und für jede Standard-MCP-Clientanwendung zugänglich machen.

MCP-Serverscript erstellen und Serverlogik implementieren

1. Kehren Sie zum Tab mit dem Cloud Shell-Editor zurück und wählen Sie das Verzeichnis adk_mcp_tools/adk_mcp_server aus.

2. Eine Python-Datei namens adk_server.py wurde für Sie vorbereitet und kommentiert. Nehmen Sie sich etwas Zeit, um die Datei zu prüfen. Lesen Sie die Kommentare, um zu verstehen, wie der Code ein Tool einbindet und als MCP-Server bereitstellt. MCP-Clients können damit verfügbare Tools auflisten und das ADK-Tool asynchron aufrufen. Anfragen und Antworten werden in einem MCP-kompatiblen Format verarbeitet.

Benutzerdefinierten MCP-Server mit einem ADK-Agenten testen

3. Klicken Sie im Verzeichnis adk_mcp_server auf die Datei agent.py.

4. Aktualisieren Sie den Pfad zu Ihrer Datei adk_server.py.

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

5. Fügen Sie dann den folgenden Code an der entsprechenden Stelle in der Datei agent.py ein, um Ihrem KI-Agenten das MCPToolset hinzuzufügen. Ein ADK-Agent fungiert als Client für den MCP-Server. Dieser ADK-Agent verwendet MCPToolset, um eine Verbindung zu Ihrem adk_server.py-Script herzustellen.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

6. Starten Sie das Script adk_server.py, um den MCP-Server auszuführen. Führen Sie dazu den folgenden Befehl im Cloud Shell-Terminal aus:

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Ausgabe:

   

7. Öffnen Sie einen neuen Cloud Shell-Terminal-Tab, indem Sie oben im Cloud Shell-Terminalfenster auf den Button  klicken.

8. Starten Sie im Cloud Shell-Terminal im Projektverzeichnis adk_mcp_tools die Agent Development Kit-Entwicklungsoberfläche mit dem folgenden Befehl:

   cd ~/adk_mcp_tools adk web

9. Klicken Sie in der Terminalausgabe auf den Link http://127.0.0.1:8000, um die Weboberfläche in einem neuen Tab aufzurufen.

10. Wählen Sie im Drop-down-Menü KI-Agent auswählen links adk_mcp_server aus.

11. Senden Sie den folgenden Prompt an den KI-Agenten:

    Load the content from https://example.com.

    Ausgabe:

    

    Das passiert:

    • Der ADK-Agent (web_reader_mcp_client_agent) verwendet das MCPToolset, um eine Verbindung zu adk_server.py herzustellen.
    • Der MCP-Server empfängt die Anfrage call_tool, führt das ADK-Tool load_web_page aus und gibt das Ergebnis zurück.
    • Der ADK-Agent leitet diese Informationen dann weiter. Sie sollten Logs sowohl aus der ADK-Webbenutzeroberfläche (und dem zugehörigen Terminal) als auch aus dem Terminal für adk_server.py im Cloud Shell-Terminal-Tab sehen, in dem es ausgeführt wird.

    Dies zeigt, dass ADK-Tools in einem MCP-Server gekapselt werden können, wodurch sie für eine Vielzahl MCP-kompatibler Clients, einschließlich ADK-Agenten, zugänglich sind.

Das wars! Sie haben das Lab erfolgreich abgeschlossen.

In diesem Lab haben Sie gelernt, wie Sie externe MCP-Tools (Model Context Protocol) mithilfe der Klasse MCPToolset in Ihre ADK-Agenten einbinden. Sie haben erfahren, wie Sie eine Verbindung zu einem MCP-Server herstellen, seine Tools in Ihrem KI-Agenten verwenden und ADK-Tools wie load_web_page über einen benutzerdefinierten MCP-Server verfügbar machen. Dank dieser Kompetenzen können Sie Ihre ADK-Agenten durch leistungsstarke externe Dienste erweitern und so Ihre Webentwicklungs-Workflows optimieren.

Anleitung zuletzt am 6. Oktober 2025 aktualisiert

Lab zuletzt am 6. Oktober 2025 getestet

© 2023 Google LLC. Alle Rechte vorbehalten. Google und das Google-Logo sind Marken von Google LLC. Alle anderen Unternehmens- und Produktnamen können Marken der jeweils mit ihnen verbundenen Unternehmen sein.