GSP1350

Übersicht

In diesem Lab geht es um die Implementierung und Bereitstellung eines Client-KI-Agentendienstes mit dem Agent Development Kit (ADK), um einen KI-Agenten zu erstellen, der Remote-Tools wie einen MCP-Server (Model Context Protocol) verwendet. Das wichtigste architektonische Prinzip, das in diesem Lab gezeigt wird, ist die Trennung von Zuständigkeiten. Eine separate Problemlösungsebene (der KI-Agent) kommuniziert über eine sichere API mit einer separaten Toolebene (dem MCP-Server).

In diesem Lab ist für Sie bereits ein MCP-Server bereitgestellt, der LLMs Daten zu den Tieren in einem fiktiven Zoo zur Verfügung stellt. Sie erstellen anschließend einen Tourguide-KI-Agenten, der aus einer Python-Anwendung besteht, für den fiktiven Zoo. Der KI-Agent nutzt den MCP-Server, um Details zu den Zootieren abzurufen, und Wikipedia, um die bestmögliche Führung zu bieten.

Zum Schluss stellen Sie den Zooführungs-KI-Agenten in Google Cloud Run bereit, damit alle Zoobesucherinnen und -besucher darauf zugreifen können und er nicht nur lokal ausgeführt wird.

Lerninhalte

Aufgaben in diesem Lab:

• Python-Projekt für die ADK-Bereitstellung strukturieren
• Mit google-adk einen KI-Agenten implementieren, der Tools verwendet
• KI-Agent mit einem Remote-MCP-Server verbinden, um das Toolset darauf zu verwenden
• Python-Anwendung als serverlosen Container in Cloud Run bereitstellen
• Sichere Dienst-zu-Dienst-Authentifizierung mit IAM-Rollen konfigurieren
• Cloud-Ressourcen löschen, um zukünftige Kosten zu vermeiden

Warum in Cloud Run bereitstellen?

Cloud Run ist eine hervorragende Wahl für das Hosting von ADK-KI-Agenten, da es sich um eine serverlose Plattform handelt. Sie können sich also auf Ihren Code konzentrieren und müssen sich nicht um die Verwaltung der zugrunde liegenden Infrastruktur kümmern. Cloud Run übernimmt die operative Arbeit für Sie.

Stellen Sie sich das wie einen Pop-up-Store vor: Er öffnet nur, wenn Kundinnen und Kunden (Anfragen) kommen, und nutzt dann Ressourcen. Wenn keine Kundinnen und Kunden da sind, schließt er komplett und Sie zahlen nicht für ein leeres Geschäft.

Wichtige Funktionen von Cloud Run

Container überall ausführen

• Sie stellen einen Container (Docker-Image) mit Ihrer Anwendung darin bereit.
• Cloud Run führt sie in der Infrastruktur von Google aus.
• Es sind kein Patching des Betriebssystems und keine VM-Einrichtung nötig und es gibt keine Skalierungsprobleme.

Autoscaling

• Wenn niemand Ihre Anwendung verwendet, werden 0 Instanzen ausgeführt (Sie zahlen 0 $, wenn sie inaktiv ist).
• Wenn 1.000 Anfragen eingehen, werden so viele Kopien wie nötig erstellt.

Standardmäßig zustandslos

• Jede Anfrage kann an eine andere Instanz gehen.
• Wenn Sie einen Zustand speichern müssen, verwenden Sie einen externen Dienst wie Cloud SQL, Firestore oder Redis.

Unterstützt jede Sprache und jedes Framework

• Solange die Anwendung in einem Linux-Container ausgeführt wird, ist es Cloud Run egal, ob sie in Python, Go, Node.js, Java oder .NET geschrieben ist.

Sie zahlen nur für die tatsächliche Nutzung

• Die Abrechnung erfolgt pro Anfrage und Rechenzeit (bis auf 100 ms genau).
• Sie zahlen nicht für inaktive Ressourcen wie bei einer herkömmlichen VM.

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 beginnt zu laufen, wenn Sie auf Lab starten klicken, und zeigt Ihnen, wie lange Google Cloud-Ressourcen für das Lab verfügbar sind.

In diesem praxisorientierten Lab können Sie die Lab-Aktivitäten 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 Google Cloud zugreifen können.

Für dieses Lab benötigen Sie Folgendes:

• Einen Standardbrowser (empfohlen wird Chrome)

Hinweis: Nutzen Sie den privaten oder Inkognitomodus (empfohlen), um dieses Lab durchzuführen. So wird verhindert, dass es zu Konflikten zwischen Ihrem persönlichen Konto und dem Teilnehmerkonto kommt und zusätzliche Gebühren für Ihr persönliches Konto erhoben werden.

• Zeit für die Durchführung des Labs – denken Sie daran, dass Sie ein begonnenes Lab nicht unterbrechen können.

Hinweis: Verwenden Sie für dieses Lab nur das Teilnehmerkonto. Wenn Sie ein anderes Google Cloud-Konto verwenden, fallen dafür möglicherweise Kosten an.

Cloud Shell aktivieren

Cloud Shell ist eine virtuelle Maschine, auf der Entwicklertools installiert sind. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft auf Google Cloud. Mit Cloud Shell erhalten Sie Befehlszeilenzugriff auf Ihre Google Cloud-Ressourcen.

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren .

2. Klicken Sie sich durch die folgenden Fenster:

   • Fahren Sie mit dem Informationsfenster zu Cloud Shell fort.
   • Autorisieren Sie Cloud Shell, Ihre Anmeldedaten für Google Cloud API-Aufrufe zu verwenden.

Wenn eine Verbindung besteht, sind Sie bereits authentifiziert und das Projekt ist auf Project_ID, eingestellt. Die Ausgabe enthält eine Zeile, in der die Project_ID für diese Sitzung angegeben ist:

Ihr Cloud-Projekt in dieser Sitzung ist festgelegt als {{{project_0.project_id | "PROJECT_ID"}}}

gcloud ist das Befehlszeilentool für Google Cloud. Das Tool ist in Cloud Shell vorinstalliert und unterstützt die Tab-Vervollständigung.

3. (Optional) Sie können den aktiven Kontonamen mit diesem Befehl auflisten:

gcloud auth list

4. Klicken Sie auf Autorisieren.

Ausgabe:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} Um das aktive Konto festzulegen, führen Sie diesen Befehl aus: $ gcloud config set account `ACCOUNT`

5. (Optional) Sie können die Projekt-ID mit diesem Befehl auflisten:

gcloud config list project

Ausgabe:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Hinweis: Die vollständige Dokumentation für gcloud finden Sie in Google Cloud in der Übersicht zur gcloud CLI.

Aufgabe 1: ADK herunterladen und installieren und Projektordner erstellen

Im Rahmen dieser Aufgabe aktivieren Sie die relevanten APIs und erstellen einen Projektordner, in dem der Quellcode für die Bereitstellung Ihres Python-Projekts gespeichert wird.

APIs aktivieren und Umgebungsvariablen festlegen

1. Klicken Sie in der Cloud Shell auf Editor öffnen, um den Cloud Shell-Editor in Ihrem Basisverzeichnis zu öffnen.
2. Klicken Sie in der Aktionsleiste des Cloud Shell-Editors auf Ansehen > Terminal.

Hinweis: Möglicherweise müssen Sie das Browserfenster verlängern, um die Menüoption „Ansehen“ anzuzeigen.

Verwenden Sie dieses Fenster als IDE mit dem Cloud Shell-Editor (oben) und dem Cloud Shell-Terminal (unten) für den Rest dieses Labs.

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.

3. Geben Sie im Terminal den folgenden Befehl ein, um Ihr Projekt einzurichten:

   gcloud config set project {{{project_0.project_id | filled in at lab start}}}

Erwartete Ausgabe: Sie sollten eine Ausgabemeldung erhalten, die das aktualisierte Attribut bestätigt.

Hinweis: Wenn die Cloud Shell ein Zeitlimit überschreitet oder neu gestartet wird, müssen Sie das Projekt neu einrichten.

4. Führen Sie zur Aktivierung aller erforderlichen Dienste den folgenden Befehl aus:

   gcloud services enable \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com

Erwartete Ausgabe: Sie sollten eine Meldung erhalten, die bestätigt, dass der Vorgang erfolgreich war.

Klicken Sie auf Fortschritt prüfen. APIs aktivieren

Projektverzeichnisse erstellen

1. Führen Sie den folgenden Befehl aus, um im Lab einen Hauptordner für den Quellcode des KI-Agenten zu erstellen:

   mkdir zoo_guide_agent && cd zoo_guide_agent

Jetzt können Sie die Datei requirements.txt erstellen. Darin sind die Python-Bibliotheken aufgeführt, die Ihr Zoo-KI-Agent benötigt.

2. Führen Sie den folgenden Befehl aus, um die Datei im Verzeichnis zoo_guide_agent zu erstellen und im Cloud Shell-Editor zu öffnen, damit Sie sie bearbeiten können:

   cloudshell edit requirements.txt

3. Fügen Sie der Datei requirements.txt Folgendes hinzu und drücken Sie Strg + S, um die Änderungen zu speichern:

   google-adk==1.28.0 langchain==1.2.14 langchain-community==0.4.1 wikipedia

4. Führen Sie den folgenden Befehl im Terminal aus, um die Python-Pakete zu installieren und den Pfad (PATH) zu aktualisieren:

   export PATH=$PATH:~/.local/bin pip3 install -r requirements.txt --user

5. Legen Sie mit diesen Befehlen Variablen für Ihr aktuelles Projekt, Ihre Region und Ihr Nutzerkonto fest:

   export PROJECT_ID=$(gcloud config get-value project) export REGION=$(gcloud compute project-info describe \ --format="value(commonInstanceMetadata.items[google-compute-default-region])") export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Hinweis: Wenn die Cloud Shell ein Zeitlimit überschreitet oder neu gestartet wird, müssen Sie die oben genannten Variablen neu initialisieren.

6. Erstellen und öffnen Sie mit dem folgenden Befehl eine .env-Datei, um den KI-Agenten im Verzeichnis zoo_guide_agent zu authentifizieren:

   cloudshell edit .env

Das Verzeichnis mit der .env-Datei wird im Cloud Shell-Editor geöffnet.

7. Fügen Sie der .env-Datei Folgendes hinzu und speichern Sie die Änderungen:

   MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}" SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" GOOGLE_GENAI_USE_ENTERPRISE=true GOOGLE_CLOUD_LOCATION=global

Verbindung zum sicheren MCP-Serverendpunkt herstellen

Im Rahmen dieses Abschnitts stellen Sie eine Verbindung zu Ihrem Remote-MCP-Server her.

1. Kehren Sie zum Cloud Shell-Terminal zurück und führen Sie den folgenden Befehl aus, um der Cloud Run-Dienstidentität die Berechtigung zum Aufrufen des Remote-MCP-Servers zu erteilen:

   gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/run.invoker"

2. Führen Sie den folgenden Befehl aus, um die MCP-Server-URL in einer Umgebungsvariablen zu speichern:

   echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env

3. Führen Sie als Nächstes den folgenden Befehl aus, um die Datei __init__.py zu erstellen. Diese teilt Python mit, dass das Verzeichnis zoo_guide_agent ein Paket ist:

   cloudshell edit __init__.py

4. Fügen Sie im Cloud Shell-Editor, der sich öffnet, den folgenden Code zu __init__.py hinzu und speichern Sie die Änderungen:

   from . import agent

Aufgabe 2: KI-Agentenworkflow erstellen

In dieser Aufgabe konfigurieren Sie den Workflow des Zooführungs-KI-Agenten. Zuerst importieren Sie die relevanten Bibliotheken für die anfängliche Einrichtung. Dann definieren Sie die Fähigkeiten des Zoo-KI-Agenten (welche Tools er verwendet) und die Spezial-KI-Agenten. Danach definieren Sie den Workflowagenten und stellen schließlich den Hauptworkflow zusammen.

Hauptdatei agent.py erstellen

• Kehren Sie zum Cloud Shell-Terminal zurück und führen Sie den folgenden Befehl aus, um die Hauptdatei agent.py zu erstellen. Dadurch wird sie im Cloud Shell-Editor geöffnet, sodass Sie in den folgenden Schritten den vollständigen Code für Ihr Multi-Agenten-System einfügen können:

  cloudshell edit agent.py

Bibliotheken importieren und erste Einrichtung vornehmen

Dieser erste Block ruft alle erforderlichen Bibliotheken aus dem ADK und Google Cloud ab. Außerdem wird das Logging eingerichtet und die Umgebungsvariablen werden aus der .env-Datei geladen, was für den Zugriff auf das Modell und die Server-URL entscheidend ist.

• Fügen Sie der Datei agent.py den folgenden Code hinzu:

  import os import sys import logging import google.cloud.logging from dotenv import load_dotenv # Add current directory for workspace utilities sys.path.append(os.path.dirname(os.path.abspath(__file__))) from google.adk import Agent from google.adk.agents import SequentialAgent from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams from google.adk.tools.tool_context import ToolContext from google.adk.tools.langchain_tool import LangchainTool from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper import google.auth import google.auth.transport.requests import google.oauth2.id_token # --- Setup Logging and Environment --- cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL")

Tools definieren

Ein KI-Agent ist nur so gut wie die Tools, die er nutzen kann. In diesem Abschnitt definieren Sie alle Fähigkeiten Ihres KI-Agenten, einschließlich einer benutzerdefinierten Funktion zum Speichern von Daten, eines MCP-Tools, das eine Verbindung zu Ihrem sicheren MCP-Server herstellt, sowie eines Wikipedia-Tools.

• Fügen Sie den folgenden Code am Ende von agent.py ein:

  # Greet user and save their prompt def add_prompt_to_state( tool_context: ToolContext, prompt: str ) -> dict[str, str]: """Saves the user's initial prompt to the state.""" tool_context.state["PROMPT"] = prompt logging.info(f"[State updated] Added to PROMPT: {prompt}") return {"status": "success"} # Configuring the MCP Tool to connect to the Zoo MCP server mcp_server_url = os.getenv("MCP_SERVER_URL") if not mcp_server_url: raise ValueError("The environment variable MCP_SERVER_URL is not set.") def get_id_token(): """Get an ID token to authenticate with the MCP server.""" target_url = os.getenv("MCP_SERVER_URL") audience = target_url.split('/mcp/')[0] request = google.auth.transport.requests.Request() id_token = google.oauth2.id_token.fetch_id_token(request, audience) return id_token """ ## Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url ) ) """ mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url, headers={ "Authorization": f"Bearer {get_id_token()}", }, ), ) # Configuring the Wikipedia Tool wikipedia_tool = LangchainTool( tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) )

Erläuterung der drei Tools

• add_prompt_to_state: 📝 Dieses Tool merkt sich die Fragen der Zoobesucherinnen und -besucher. Wenn eine Besucherin oder ein Besucher fragt: „Wo sind die Löwen?“, speichert dieses Tool die Frage im Gedächtnis des KI-Agenten, sodass die anderen KI-Agenten im Workflow wissen, wonach sie suchen müssen.

  Funktionsweise: Es handelt sich um eine Python-Funktion, die den Prompt der Besucherin beziehungsweise des Besuchers in das gemeinsame Wörterbuch tool_context.state schreibt. Dieser Toolkontext stellt das Kurzzeitgedächtnis des KI-Agenten für eine einzelne Unterhaltung dar. Daten, die von einem KI-Agenten im Zustand gespeichert wurden, können vom nächsten KI-Agenten im Workflow gelesen werden.

• MCPToolset: 🦁 Damit wird der Zooführungs-KI-Agent mit dem MCP-Server des Zoos verbunden, der in diesem Lab vorab bereitgestellt wurde. Dieser Server hat spezielle Tools, um bestimmte Informationen über Zootiere abzurufen, wie ihren Namen, ihr Alter und ihr Gehege.

  Funktionsweise: Es wird eine sichere Verbindung zur privaten Server-URL des Zoos hergestellt. get_id_token wird verwendet, um automatisch eine sichere „Schlüsselkarte“ (ein Dienstkonto-ID-Token) zu erhalten, mit der die Identität nachgewiesen und Zugriff erlangt werden kann.

• LangchainTool: 🌍 Damit erhält der Zooführungs-KI-Agent allgemeines Weltwissen. Wenn eine Besucherin oder ein Besucher eine Frage stellt, die nicht in der Datenbank des Zoos enthalten ist, wie „Was fressen Löwen in freier Wildbahn?“, kann der KI-Agent mit diesem Tool die Antwort bei Wikipedia nachschlagen.

  Funktionsweise: Das Tool fungiert als Adapter, sodass Ihr KI-Agent das vorhandene Tool „WikipediaQueryRun“ aus der LangChain-Bibliothek verwenden kann.

Ressourcen:

• MCP-Toolset
• Funktionstools
• Zustand

Spezial-KI-Agenten definieren

Im Rahmen dieses Abschnitts definieren Sie zwei Spezial-KI-Agenten: den Recherche-KI-Agenten und den Antwortformatierungs-KI-Agenten. Der Recherche-KI-Agent ist das „Gehirn“ Ihres Dienstes. Er nimmt den Prompt der Nutzerin beziehungsweise des Nutzers aus dem gemeinsamen Zustand, prüft seine leistungsfähigen Tools (das MCP-Servertool des Zoos und das Wikipedia-Tool) und entscheidet, welche verwendet werden sollen, um die Antwort zu finden.

Die Aufgabe des Antwortformatierungs-KI-Agenten ist die Präsentation. Er verwendet keine Tools, um neue Informationen zu finden. Stattdessen werden die vom Recherche-KI-Agenten gesammelten Rohdaten (über den Zustand übergeben) übernommen und mithilfe der Sprachkenntnisse des LLM in eine freundliche Antwort wie bei einer normalen Unterhaltung umgewandelt.

• Fügen Sie den folgenden Code am Ende von agent.py ein:

  # 1. Researcher Agent comprehensive_researcher = Agent( name="comprehensive_researcher", model=model_name, description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.", instruction=""" You are a helpful research assistant. Your goal is to fully answer the user's PROMPT. You have access to two tools: 1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations). 2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat). First, analyze the user's PROMPT. - If the prompt can be answered by only one tool, use that tool. - If the prompt is complex and requires information from both the zoo's database AND Wikipedia, you MUST use both tools to gather all necessary information. - Synthesize the results from the tool(s) you use into preliminary data outputs. PROMPT: {{ PROMPT }} """, tools=[ mcp_tools, wikipedia_tool ], output_key="research_data" # A key to store the combined findings ) # 2. Response Formatter Agent response_formatter = Agent( name="response_formatter", model=model_name, description="Synthesizes all information into a friendly, readable response.", instruction=""" You are the friendly voice of the Zoo Tour Guide. Your task is to take the RESEARCH_DATA and present it to the user in a complete and helpful answer. - First, present the specific information from the zoo (like names, ages, and where to find them). - Then, add the interesting general facts from the research. - If some information is missing, just present the information you have. - Be conversational and engaging. RESEARCH_DATA: {{ research_data }} """ )

Workflow-KI-Agent definieren

Der Workflow-KI-Agent fungiert als Koordinator für die Zootour. Er nimmt eine Rechercheanforderung entgegen und sorgt dafür, dass die beiden in Schritt 3 definierten KI-Agenten ihre Aufgaben in der richtigen Reihenfolge erledigen: zuerst die Recherche, dann die Formatierung. So entsteht ein vorhersehbarer, zuverlässiger Prozess, um die Fragen von Zoobesucherinnen und -besuchern zu beantworten.

Funktionsweise: Dies ist ein SequentialAgent, eine spezielle Art von KI-Agent, der nicht selbstständig denkt. Seine einzige Aufgabe ist es, eine Liste von sub_agents (für Recherche und Formatierung) in einer festen Reihenfolge auszuführen und die gemerkten Informationen automatisch von einem zum nächsten zu übergeben.

• Fügen Sie den folgenden Codeblock am Ende von agent.py ein:

  tour_guide_workflow = SequentialAgent( name="tour_guide_workflow", description="The main workflow for handling a user's request about an animal.", sub_agents=[ comprehensive_researcher, # Step 1: Gather all data response_formatter, # Step 2: Format the final response ] )

Hauptworkflow zusammenstellen

Der Hauptworkflow wird über den root_agent festgelegt, den das ADK-Framework als Ausgangspunkt für alle neuen Unterhaltungen verwendet. Die Hauptaufgabe dieses KI-Agenten ist die Orchestrierung des gesamten Prozesses. Er fungiert als anfänglicher Controller und verwaltet die erste Runde der Unterhaltung.

• Fügen Sie diesen letzten Codeblock am Ende von agent.py ein und speichern Sie die Änderungen:

  root_agent = Agent( name="greeter", model=model_name, description="The main entry point for the Zoo Tour Guide.", instruction=""" - Let the user know you will help them learn about the animals we have in the zoo. - When the user responds, use the 'add_prompt_to_state' tool to save their response. After using the tool, transfer control to the 'tour_guide_workflow' agent. """, tools=[add_prompt_to_state], sub_agents=[tour_guide_workflow] )

Die Datei agent.py ist jetzt fertig.

So können Sie sehen, wie jede Komponente – Tools, Worker-KI-Agenten und Manager-KI-Agenten – eine bestimmte Rolle bei der Erstellung des endgültigen, intelligenten Systems spielt. Als Nächstes erfolgt die Bereitstellung.

Aufgabe 3: Anwendung auf die Bereitstellung vorbereiten

Nachdem Sie Ihre lokale Umgebung eingerichtet haben, müssen Sie Ihr Google Cloud-Projekt für die Bereitstellung des Zooführungs-KI-Agenten vorbereiten.

Dabei wird die Dateistruktur des KI-Agenten noch einmal geprüft, um sicherzugehen, dass sie mit dem Bereitstellungsbefehl kompatibel ist. Noch wichtiger ist, dass Sie eine kritische IAM-Berechtigung konfigurieren, die es Ihrem bereitgestellten Cloud Run-Dienst ermöglicht, in Ihrem Namen zu handeln und die Agent Platform-Modelle aufzurufen. Wenn Sie diesen Schritt abgeschlossen haben, ist die Cloud-Umgebung bereit, Ihren KI-Agenten auszuführen.

1. Kehren Sie zum Cloud Shell-Terminal zurück und führen Sie den folgenden Befehl aus, um die Variablen in Ihre Shell-Sitzung zu laden:

   source .env

2. Führen Sie den folgenden Befehl aus, um dem Dienstkonto die Rolle „Agent Platform User“ zu gewähren. Damit hat es die Berechtigung, Vorhersagen zu treffen und Modelle von Google aufzurufen:

   # Grant the "Agent Platform User" role to your service account gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/aiplatform.user"

Aufgabe 4: KI-Agent mit der ADK-CLI bereitstellen

Ihr lokaler Code ist fertig und Ihr Google Cloud-Projekt ist vorbereitet. Jetzt können Sie den KI-Agenten bereitstellen.

In dieser Aufgabe verwenden Sie den Befehl adk deploy cloud_run. Dieses praktische Tool automatisiert den gesamten Bereitstellungsworkflow. Mit diesem einen Befehl wird Ihr Code verpackt, ein Container-Image erstellt und per Push in Artifact Registry übertragen und der Dienst in Cloud Run gestartet, sodass er im Web zugänglich ist.

KI-Agent bereitstellen

1. Führen Sie den folgenden Befehl aus, um den KI-Agenten bereitzustellen:

   # Run the deployment command adk deploy cloud_run \ --project=$PROJECT_ID \ --region=$REGION \ --service_name=zoo-tour-guide \ --with_ui \ .

2. Wenn Sie gefragt werden, ob Sie fortfahren möchten und/oder ob Sie nicht authentifizierte Aufrufe von [zoo-tour-guide] zulassen möchten, geben Sie jeweils Y ein und drücken Sie die Eingabetaste.

Hinweis: Die Ausführung dieses Befehls kann fünf bis zehn Minuten dauern.

3. Führen Sie den folgenden Befehl aus, um die Konfigurationseinstellungen des vorhandenen Cloud Run-Dienstes zu ändern:

   gcloud run services update zoo-tour-guide \ --region=$REGION \ --update-labels=dev-tutorial=codelab-adk \ --set-env-vars="MODEL=$MODEL,MCP_SERVER_URL=$MCP_SERVER_URL,GOOGLE_CLOUD_LOCATION=global"

Link zur Bereitstellung abrufen

• Nachdem der KI-Agent erfolgreich in Cloud Run bereitgestellt wurde, wird die Dienst-URL ausgegeben, die Sie in einem neuen Browsertab öffnen können.

  Sie sollte in etwa so aussehen: Dienst-URL-Ausgabe:

  https://zoo-tour-guide-{{{project_0.startup_script.project_number | filled in at lab start}}}.{{{project_0.default_region | filled in at lab start}}}.run.app

Da Sie beim Bereitstellen in Cloud Run das Flag --with_ui verwendet haben, sollte die ADK-Entwickler-UI angezeigt werden.

Hinweis: Wer die URL hat, kann auf diesen KI-Agenten zugreifen. Daher eignet sich dieser Ansatz am besten für Testzwecke. Hinweis: Es kann einige Minuten dauern, bis die Aktivitätsprüfung nach einer erfolgreichen Bereitstellung abgeschlossen ist.

Klicken Sie auf Fortschritt prüfen. KI-Agent bereitstellen

Aufgabe 5: Bereitgestellten KI-Agenten testen

Ihr KI-Agent ist jetzt in Cloud Run aktiv. Im Rahmen dieser Aufgabe führen Sie einen Test durch, um zu bestätigen, dass die Bereitstellung erfolgreich war und der KI-Agent wie erwartet funktioniert. Sie benötigen die öffentliche Dienst-URL, um auf die Weboberfläche des ADK zuzugreifen und mit dem KI-Agenten zu interagieren.

1. Rufen Sie die öffentliche Cloud Run-Dienst-URL, die in der vorherigen Aufgabe ausgegeben wurde, in Ihrem Webbrowser auf oder halten Sie die Strg-Taste gedrückt und klicken Sie auf die URL in der Ausgabe (sie sollte in einem neuen Browsertab geöffnet werden). Dadurch wird die ADK-Entwickler-UI geöffnet.

   Wenn Sie eine Benachrichtigung erhalten, in der Sie gefragt werden, ob die externe Website in der Cloud Shell geöffnet werden soll, klicken Sie auf Öffnen, um dies zu bestätigen.

2. Stellen Sie Tokenstreaming rechts oben in der ADK-Symbolleiste auf Ein.

Sie können jetzt mit dem Zoo-KI-Agenten interagieren.

3. Geben Sie den folgenden Prompt in das Prompt-Feld ein und drücken Sie die Eingabetaste, um eine neue Unterhaltung zu beginnen:

Hello

Sehen Sie sich das Ergebnis an. Der KI-Agent sollte schnell mit seiner Standardbegrüßung antworten:

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

4. Interagieren Sie jetzt mit dem Zooführungs-KI-Agenten. Geben Sie den folgenden Prompt ein, um die Unterhaltung fortzusetzen:

Where are the penguins located?

Sie sollten eine Antwort ähnlich der folgenden erhalten:

5. Probieren Sie diese weiteren Prompts aus, um zu sehen, wie der KI-Agent verschiedene Tools (MCP und Wikipedia) verwendet und Informationen kombiniert:

Test des Allgemeinwissens (nur Wikipedia):

What is the average lifespan of a penguin in the wild?

Kombination interner und externer Daten testen:

What species are the penguins in our zoo, and what do they typically eat in the wild?

Erneuter Test beider Tools mithilfe einer Frage zu Löwen:

Where are the lions and what do they eat in the wild?

Test mit Tieren, die möglicherweise nicht im Zoo sind (Eisbären):

Do we have polar bears in this zoo?

Der KI-Agentenablauf

Ihr System funktioniert wie ein intelligentes Multi-Agenten-Team. Der Prozess wird durch eine klare Abfolge gesteuert, um einen reibungslosen und effizienten Ablauf von der Frage einer Nutzerin oder eines Nutzers bis zur detaillierten Antwort zu ermöglichen.

1. Die Zoobegrüßung (der Empfangstresen)

Der gesamte Prozess beginnt mit dem Begrüßungs-KI-Agenten.

Aufgabe: Die Unterhaltung beginnen. Die Anweisung lautet, die Nutzerin beziehungsweise den Nutzer zu begrüßen und zu fragen, über welches Tier die Person mehr erfahren möchte.

Tool: Wenn die Nutzerin beziehungsweise der Nutzer antwortet, verwendet der Begrüßungs-KI-Agent das Tool add_prompt_to_state, um die genauen Worte der Person zu erfassen (zum Beispiel „Erzähl mir etwas über Löwen“) und sie im Arbeitsspeicher des Systems zu speichern.

Übergabe: Nachdem der Prompt gespeichert wurde, wird sofort an den Sub-Agenten tour_guide_workflow übergeben.

2. Der gründliche Rechercheur (der Superrechercheur)

Dies ist der erste Schritt im Hauptworkflow und das „Gehirn“ des Dienstes. Anstatt eines großen Teams haben Sie jetzt einen einzigen, hoch qualifizierten KI-Agenten, der auf alle verfügbaren Informationen zugreifen kann.

Aufgabe: Die Frage der Nutzerin beziehungsweise des Nutzers analysieren und einen intelligenten Plan erstellen. Der Recherche-KI-Agent nutzt die Fähigkeit des Sprachmodells zur Toolnutzung, um zu entscheiden, ob er Folgendes benötigt:

• Interne Daten aus den Aufzeichnungen des Zoos (über den MCP-Server)
• Allgemeinwissen aus dem Web (über die Wikipedia API)
• Beides im Fall komplexer Fragen

Aktion: Es werden die erforderlichen Tools ausgeführt, um alle benötigten Rohdaten zu erheben. Wenn beispielsweise gefragt wird: „Wie alt sind unsere Löwen und was fressen sie in freier Wildbahn?“, ruft der KI-Agent den MCP-Server für das Alter und das Wikipedia-Tool für die Informationen zur Nahrung auf.

3. Der Antwortformatierer (der Präsentator)

Nachdem der gründliche Rechercheur alle Fakten zusammengetragen hat, ist dies der letzte KI-Agent, der ausgeführt wird.

Aufgabe: Als freundliche Stimme der Zooführung fungieren. Dieser KI-Agent nimmt die Rohdaten (die aus einer oder aus beiden Quellen stammen können) und bereitet sie auf.

Aktion: Die Informationen werden in einer einzigen, zusammenhängenden und ansprechenden Antwort zusammengefasst. Gemäß den Anweisungen werden zuerst die spezifischen Zoo-Informationen und dann die interessanten allgemeinen Fakten präsentiert.

Endergebnis: Der von diesem KI-Agenten generierte Text ist die vollständige, detaillierte Antwort, die im Chatfenster zu sehen ist.

Aufgabe 6: Umgebung bereinigen

Im Rahmen dieser Aufgabe löschen Sie die Cloud-Ressourcen, die Sie in diesem Lab erstellt haben, um zukünftige Kosten zu vermeiden.

• Kehren Sie zum Cloud Shell-Terminaltab zurück und führen Sie den folgenden Befehl aus:

  gcloud run services delete zoo-tour-guide --region=$REGION --quiet gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet

Weitere Informationen

Wenn Sie mehr über das Erstellen von KI-Agenten erfahren möchten, finden Sie hier einige Ressourcen:

• ADK-Dokumentation
• Building Custom Tools for Agents

Das wars! Sie haben das Lab erfolgreich abgeschlossen.

Sie haben gelernt, wie Sie ein Python-Projekt für die Bereitstellung mit der ADK-Befehlszeile strukturieren, einen Workflow mit mehreren KI-Agenten implementieren, eine Verbindung zu einem Remote-MCP-Server herstellen, um dessen Tools zu nutzen, interne Daten durch die Einbindung externer Tools wie der Wikipedia API anreichern und den KI-Agenten als serverlosen Container in Cloud Run bereitstellen.

Anleitung zuletzt am 21. Juli 2026 aktualisiert

Lab zuletzt am 21. Juli 2026 getestet

© 2026 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.