Personalisierte Agents mit ADK, MCP und Memory Bank erstellen

1. Einführung

Der moderne Agenten-Stack

Die Entwicklung eines KI-Agenten in Produktionsqualität erfordert mehr als nur ein Large Language Model (LLM). Ein LLM bietet zwar die Reasoning-Funktionen, aber ein robuster Agent muss auch mit der Außenwelt interagieren, den Unterhaltungsstatus verwalten und sich die Präferenzen der Nutzer im Laufe der Zeit merken können.

In diesem Workshop erfahren Sie, wie Sie ein umfassendes agentisches System mit drei grundlegenden Technologien entwerfen und erstellen:

1. Konnektivität (MCP): Damit Ihr Agent Zugriff auf lokale Tools und Daten hat.
2. Orchestrierung (ADK): Zum Verwalten der Reasoning Loop und des Zustands des KI-Agenten.
3. Memory (Memory Bank): Für langfristigen, personalisierten Kontext.

Wichtige Konzepte

Komponente	Funktion
Model Context Protocol (MCP)	Ein universeller Standard, der KI-Modelle ohne benutzerdefinierte Integrationen mit externen Systemen (Datenbanken, Dateisystemen, APIs) verbindet.
Agent Development Kit (ADK)	Ein Framework, das die Laufzeitumgebung für KI-Agenten bereitstellt und die Ereignisschleife, Zustandsübergänge und die Ausführung von Tools verwaltet.
Sitzungsdienst	Verarbeitet den Kurzzeitspeicher. Der unmittelbare Kontext der Unterhaltung (z.B. „Was hat der Nutzer gerade gefragt?“) wird beibehalten, aber am Ende der Sitzung gelöscht.
Vertex AI Memory Bank	Verarbeitet das Langzeitgedächtnis. Sie speichert nutzerspezifische Fakten und Einstellungen (z.B. „Nutzer bevorzugt Python“) unbegrenzt, sodass der Agent zukünftige Interaktionen personalisieren kann.
Vertex AI Agent Engine	Der verwaltete Infrastrukturdienst, der die Logik und die Speicherkomponenten Ihrer KI-Agenten in großem Umfang hostet.

Umfang

Zur Veranschaulichung dieser Konzepte erstellen Sie einen Holiday Design Assistant. Dieser KI-Agent kann allgemeine Nutzeranfragen entgegennehmen und autonom lokale Python-Tools orchestrieren, um personalisierten Code und Bilder zu generieren.

Sie durchlaufen drei Phasen:

1. Tooling-Ebene: Erstellen Sie einen MCP-Server, um lokale Python-Funktionen für die KI bereitzustellen.
2. Agentenebene: Mit dem ADK können Sie einen Agenten erstellen, der mehrstufige Workflows plant und ausführt.
3. Memory Layer: Integrieren Sie Memory Bank, damit der KI-Agent die Stilpräferenzen der Nutzer lernen und sich merken kann.

2. Erstelle ein

Für unsere KI-Agenten benötigen wir zwei Dinge: ein Google Cloud-Projekt als Grundlage

Teil 1: Rechnungskonto aktivieren

Für dieses Codelab benötigen Sie ein Rechnungskonto mit Guthaben. Verwenden Sie das Guthaben aus dem Banner oben in diesem Codelab, um loszulegen. Wenn Sie bereits mit einem Rechnungskonto verbunden sind, können Sie diesen Schritt überspringen.

Teil 2: Umgebung öffnen

1. 👉 Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
2. 👉 Wenn Sie heute zu irgendeinem Zeitpunkt zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.
3. 👉 Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
   • Klicken Sie auf Ansehen.
   • Klicken Sie auf Terminal.
4. 👉💻 Prüfen Sie im Terminal mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und ob das Projekt auf Ihre Projekt-ID festgelegt ist:

   gcloud auth list
   

5. 👉💻 Klonen Sie das Bootstrap-Projekt von GitHub:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Führen Sie das Setupscript im Projektverzeichnis aus.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Hinweis zur Projekt-ID: Das Script schlägt eine zufällig generierte Standard-Projekt-ID vor. Sie können die Eingabetaste drücken, um diesen Standardwert zu übernehmen.

   Wenn Sie jedoch ein bestimmtes neues Projekt erstellen möchten, können Sie die gewünschte Projekt-ID eingeben, wenn Sie vom Script dazu aufgefordert werden.

   Das Skript übernimmt den Rest des Einrichtungsvorgangs automatisch.
7. 👉💻 Legen Sie die erforderliche Projekt-ID fest:

   gcloud config set project $(cat ~/project_id.txt) --quiet
   

Teil 3: Berechtigungen einrichten

1. 👉💻 Aktivieren Sie die erforderlichen APIs mit dem folgenden Befehl. Dies kann einige Minuten dauern.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Erteilen Sie die erforderlichen Berechtigungen, indem Sie die folgenden Befehle im Terminal ausführen:

   . ~/holiday_workshop/set_env.sh
   

Beachten Sie, dass eine .env-Datei für Sie erstellt wird. Daraufhin werden Ihre Projektinformationen angezeigt.

3. Mehr Leistung mit MCP

Der „USB-C“-Moment für KI

Stellen Sie sich vor, Sie müssten jedes Mal, wenn Sie eine neue Maus kaufen, diese an Ihr Motherboard löten. Das war bis vor Kurzem der Stand der KI-Tools. Entwickler mussten benutzerdefinierten „Glue Code“ schreiben, um LLMs mit Datenbanken, Dateisystemen oder APIs zu verbinden.

Geben Sie das Model Context Protocol (MCP) ein. Man kann sich das MCP als USB‑C-Anschluss für KI-Anwendungen vorstellen. Es bietet eine standardisierte Möglichkeit, KI-Modelle mit Datenquellen und Tools zu verbinden.

Wenn Sie einmal einen MCP-Server für Ihre Tools erstellen, können Sie ihn in die Gemini CLI, eine IDE oder einen anderen MCP-kompatiblen Client einbinden, ohne eine einzige Zeile Code ändern zu müssen.

Umfang

In diesem Codelab erstellen Sie einen Designassistenten für die Feiertage, der Folgendes kann:

1. Verbindet sich über MCP mit Ihrer lokalen Umgebung (Studio-Tools).
2. Verwaltet den Kontext von Unterhaltungen zuverlässig mit dem Agent Development Kit (ADK).
3. Merkt sich Ihre Einstellungen (z.B. „Ich bevorzuge Python-Code“) über verschiedene Sitzungen hinweg mithilfe von Vertex AI Memory Bank.

Warnung: Authentifizieren Sie Ihre Google Cloud CLI (gcloud auth login), bevor Sie die Codebeispiele ausführen.

Serverlogik erstellen

Wir haben die Umgebung vorbereitet, aber die Serverlogik ist unvollständig. Wir müssen die vier spezifischen Tools implementieren, die unser KI-Agent letztendlich zum Erstellen der Weihnachtskarte verwenden wird.

Teil 1: Server-Skeleton öffnen

Wir arbeiten im Verzeichnis 01-MCP-Files-Testing/01-starter.

1. Prüfen Sie im Cloud Shell-Terminal, ob Sie sich im richtigen Verzeichnis befinden:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Öffnen Sie die Datei im Cloud Shell-Editor, indem Sie Folgendes ausführen:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Der Boilerplate-Code (Einrichten des MCP-Servers, Verwalten von Verbindungen und Initialisieren des Vertex AI-Clients) ist bereits vorhanden. Die vier Hauptfunktionen sind jedoch derzeit leere Platzhalter.

Teil 2: Holiday Scene Generator implementieren

Zuerst benötigen wir ein Tool, das das Interesse eines Nutzers (z.B. „Vögel“) in einen umfangreichen, detaillierten Prompt umwandelt, der für die Bildgenerierung optimiert ist.

Suchen Sie den Kommentar #REPLACE_GENERATE_HOLIDAY_SCENE in der Funktion generate_holiday_scene.

Ersetzen Sie diese gesamte Zeile durch den folgenden Code:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Teil 3: Das endgültige Fotoergebnis implementieren

Außerdem möchten wir sicherstellen, dass die Beleuchtung und der Stil fotorealistisch und festlich wirken.

Suchen Sie den Kommentar #REPLACE_GENERATE_FINAL_PHOTO.

Ersetzen Sie diese gesamte Zeile durch den folgenden Code, um die endgültige Stilübertragung und das Rendering durchzuführen:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Umgebung einrichten

Nachdem der Code nun vorhanden ist, müssen wir dafür sorgen, dass unsere Abhängigkeiten installiert sind. Wir verwenden uv, einen schnellen Python-Paket- und Projektmanager.

👉💻 Führen Sie im Terminal den folgenden Befehl aus, um FastMCP als Abhängigkeit des Projekts hinzuzufügen:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Sie sehen, dass der Datei ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml eine neue Abhängigkeit fastmcp>=2.13.3 hinzugefügt wurde.

4. Mit der Gemini CLI für den MCP-Server testen

Nachdem der Servercode fertig ist, wie testen wir ihn?

Normalerweise müssen Sie zum Testen eines Backend-Servers eine Frontend-UI erstellen oder komplexe curl-Anfragen schreiben. Hier können wir jedoch die Gemini CLI verwenden.

Was ist die Gemini CLI?

Die Gemini CLI ist ein Befehlszeilentool, mit dem Sie direkt in Ihrem Terminal mit einem Gemini-Modell chatten können. Das Besondere daran: Es kann die auf Ihrem lokalen MCP-Server ausgeführten Tools automatisch erkennen und verwenden.

Das ist für die Entwicklung unglaublich nützlich, da die Logik isoliert wird. Sie können prüfen, ob das Modell Ihre Tools versteht und sie korrekt aufruft, bevor Sie sich Gedanken über die Erstellung einer Weboberfläche oder eines Agenten-Frameworks machen müssen.

Verbinden und ausführen

Wir weisen die Gemini CLI mit dem Befehl mcp add an, unseren Server zu verwalten.

Führen Sie im Terminal folgenden Befehl aus:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: Wir haben unserem Server einen Alias („holidays“) gegeben.
• uv run ...: Wir haben den expliziten Befehl zum Starten des gerade geänderten Python-Servers angegeben.

Los gehts!

Starten Sie jetzt die Chatsitzung:

gemini

Testen Sie mit dem folgenden Prompt, ob Gemini Ihre neuen Tools „sehen“ kann. Möglicherweise müssen Sie der Gemini CLI die Verwendung des Feiertags-Tools erlauben.

• 👉 Nutzer:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Nutzer:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Da Sie MCP verwendet haben, hat die KI genau verstanden, welche Python-Funktion aufgerufen werden muss, um Ihre Anfrage zu erfüllen.

Bild überprüfen

• Beenden Sie die Gemini CLI, indem Sie Control+C drücken.
• Sehen Sie sich das generierte Bild in Ihrem Ordner an: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Hier kannst du dir dein Foto ansehen:

Fazit und nächste Schritte

Glückwunsch! Sie haben einen funktionierenden MCP-Server erstellt. Sie haben jetzt eine Reihe von KI-Tools, mit denen Sie Muster und zusammengesetzte Bilder generieren und Szenen optimieren können.

Ist Ihnen im obigen Test etwas aufgefallen? Sie mussten den Prozess vorantreiben. Sie mussten nach der Szene fragen, dann nach dem Muster und dann nach der Kombination.

Gemini ist zwar intelligent, aber für einen komplexen Produktionsworkflow, bei dem wir ein Muster generieren müssen, bevor wir es auf einen Pullover drucken können, und Fehler behandeln müssen, wenn die Bildgenerierung fehlschlägt, möchten wir mehr Kontrolle haben. Wir möchten ein dediziertes System, das die Planung übernehmen, die eigene Arbeit kritisieren und den Status unserer Weihnachtskarte verwalten kann, ohne dass wir es bei jedem Schritt anleiten müssen.

Im nächsten Abschnitt bringen wir Ordnung in dieses kreative Chaos. Wir implementieren das Agent Development Kit (ADK), um einen strukturierten KI-Agenten zu erstellen, der diese MCP-Tools in einer perfekten Produktionspipeline orchestriert.

5. ADK-Agent per Vibe Coding erstellen

Wir haben eine Reihe von Tools (unseren MCP-Server), aber derzeit müssen wir die ganze Arbeit erledigen und Gemini genau sagen, welches Tool wann aufgerufen werden soll.

In diesem Abschnitt erstellen wir einen KI-Agenten: ein System, das selbstständig Schlussfolgerungen ziehen, planen und mehrstufige Aufgaben ausführen kann. Dazu verwenden wir das Agent Development Kit (ADK).

Was ist ein KI-Agent?

Wenn die MCP-Tools die „Hände“ sind (die die Arbeit erledigen), ist der Agent das „Gehirn“. Ein Agent verwendet ein LLM, um die Absicht eines Nutzers zu verstehen („Erstelle eine Urlaubskarte“), unterteilt sie in Schritte („Zuerst brauche ich eine Szene, dann ein Muster…“) und entscheidet, welche Tools verwendet werden sollen, um das Ziel zu erreichen.

Was ist das ADK?

Das Agent Development Kit (ADK) ist ein Framework von Google, mit dem sich solche Agenten ganz einfach erstellen lassen. Sie übernimmt die komplexe „Infrastruktur“, z. B. die Verwaltung des Chatverlaufs, die Verbindung zu Tools und den Wechsel zwischen verschiedenen Modellen. So können Sie sich auf die Persönlichkeit und Logik Ihrer App konzentrieren.

Kontextbasiertes Vibe Coding

Es ist üblich, einen einzigen, sehr umfangreichen Prompt zu verwenden, um Code zu generieren. Beim Erstellen komplexer Anwendungen ist es jedoch oft besser, die KI als Partner zu betrachten, der den Kontext im Laufe der Zeit beibehält.

Wir verwenden die Memory-Funktionen der Gemini CLI, um die Grundlagen zu schaffen, bevor wir eine einzige Zeile Code schreiben.

1. Umgebung vorbereiten

Öffnen Sie Ihr Terminal und rufen Sie das Starterverzeichnis auf:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Starten Sie die Gemini CLI:

gemini

2. Kontext und gemerkte Informationen verwalten

Beim Vibe-Coding muss die KI wissen, wer sie ist und was sie weiß. Mit der Gemini CLI können wir das explizit verwalten.

• /memory show: Geben Sie dies ein, um zu sehen, was die KI derzeit über Ihr Projekt und Ihre Sitzung weiß.
• /memory add: Verwenden Sie diese Option, um grundlegendes Wissen einzufügen, das sich die KI während der gesamten Unterhaltung merken soll.

Lassen Sie uns zuerst die Persona unseres Coding-Assistenten definieren. Führen Sie den folgenden Befehl in der Gemini CLI aus:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini versteht jetzt seine Rolle. Dieser Kontext beeinflusst jede nachfolgende Antwort und sorgt für hochwertigen, ADK-konformen Code.

3. Schritt 1: Basis-Agenten per Vibe-Coding erstellen

Anstatt das gesamte System auf einmal zu generieren, beginnen wir mit dem Grundgerüst. Wir möchten die Dateistruktur und die grundlegende Persönlichkeit des KI-Agenten festlegen.

Geben Sie den folgenden Prompt in der Gemini CLI ein:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini erstellt die Dateistruktur und den ersten Python-Code. Prüfen Sie, ob alles korrekt ist, und übernehmen/akzeptieren Sie die Änderungen.

4. Schritt 2: MCP-Server (die Tools) hinzufügen

Nachdem wir einen einfachen KI-Agenten erstellt haben, müssen wir ihm „Hände“ geben. Wir müssen den Agenten mit dem MCP-Server verbinden, den wir im vorherigen Lab erstellt haben.

Geben Sie den folgenden Prompt in der Gemini CLI ein:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini refaktoriert jetzt Ihre vorhandene agent.py, um die Tooldefinitionen und die Verbindungslogik einzufügen.

Hinweis: Wenn Sie Ihre Arbeit überprüfen möchten oder der generierte Code nicht wie erwartet funktioniert, können Sie Ihre Dateien mit der Referenzlösung vergleichen, die sich hier befindet: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Weboberfläche des KI-Agenten ausführen

Das ADK enthält eine integrierte Testoberfläche namens adk web. Dadurch wird eine einfache Chat-Benutzeroberfläche geöffnet, über die wir sofort mit unserem KI-Agenten sprechen können.

1. Wenn GeminiCLI noch geöffnet ist, drücken Sie control+C, um es zu schließen. Führen Sie jetzt im Terminal (im Ordner solution) den folgenden Befehl aus. Sie können den Code im Ordner starter testen, indem Sie uv run adk web im Ordner starter ausführen:

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell benachrichtigt Sie, dass ein Dienst auf Port 8000 ausgeführt wird. Klicken Sie auf Webvorschau > Vorschau auf Port 8000.

KI-Agenten testen

Sie sollten jetzt eine Chatoberfläche sehen. Sehen wir uns an, ob unser KI-Agent die neuen Anweisungen befolgt und korrekt auf die MCP-Tools zugreift.

Mögliche Prompts:

• „Hallo, Wer bist du?"
  • (Erwarte eine festliche, begeisterte Antwort).
• „Ich brauche einen Hintergrund für meine Weihnachtskarte. Mach daraus ein verschneites Dorf.“
  • (Der KI-Agent sollte generate_holiday_scene aufrufen. Beachten Sie, dass der in den Systemanweisungen definierte Stil „cute/cartoon“ automatisch angewendet wird.
• „Erstelle ein Pullovermuster mit kleinen Pizzastücken.“
  • (Der Kundenservicemitarbeiter sollte generate_sweater_pattern anrufen).

Hier können Sie sich das generierte Bild ansehen:

Drücken Sie Control+C, um den Test zu beenden.

Fazit und nächste Schritte

Sie haben jetzt erfolgreich einen Google ADK-Agenten mit einem kontextsensitiven Ansatz „Vibe-Coded“.

• Kontext herstellen: Wir haben /memory add verwendet, um eine Experten-Persona zu definieren.
• Wir haben iterativ gearbeitet: Wir haben zuerst das Grundgerüst erstellt und dann die Toolverbindungen hinzugefügt.

Die integrierte ADK-Webvorschau eignet sich hervorragend zum Testen, aber für unser Endprodukt möchten wir eine benutzerdefinierte, markenspezifische Oberfläche. Im nächsten Abschnitt binden wir diesen KI-Agenten in ein benutzerdefiniertes Web-Frontend ein.

Wenn Sie während des Workshops auf Unexpected response from metadata server: service account info is missing 'email' field stoßen, müssen Sie Ihre Cloud Shell aktualisieren und gcloud config set project $(cat ~/project_id.txt) --quiet noch einmal ausführen, um project id festzulegen, bevor Sie fortfahren.

7. ADK mit der Benutzeroberfläche verbinden

Nachdem wir eine Agentendefinition haben, müssen wir sie ausführen. Hier kommen der Runner und der Sitzungsdienst ins Spiel.

Implementierung

1. 👉 Geben Sie Folgendes in Ihren Befehl ein:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Dadurch wird ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py im Editor geöffnet.
2. Ersetzen Sie # TODO: Create Session Service durch Folgendes:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Der Sitzungsdienst ist der „Arbeitsspeicher“ Ihres KI-Agenten.

   • Rolle: Speichert den unstrukturierten, unmittelbaren Verlauf der aktuellen Unterhaltung (z.B. „Was habe ich gerade gefragt?“).
   • Zwei Varianten:
   • InMemorySessionService: Schnell, einfach, aber amnesisch. Wenn Sie den Server neu starten, vergisst der Agent alles. Ideal zum Testen.
   • VertexAiSessionService: Robust, datenbankgestützt. Der Status wird in Google Cloud gespeichert, sodass die Unterhaltung Wochen später oder nach einem Serverneustart fortgesetzt werden kann.
3. Ersetzen Sie # TODO: Initialize Runner durch Folgendes:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Der Runner: Wenn der Agent das „Gehirn“ ist, ist der Runner das „Herz“. Das hält den Blutkreislauf in Schwung. Der Runner ist für Folgendes verantwortlich:

• Agent an einen Nutzer und eine Sitzung binden.
• Ausführen der Ereignisschleife.
• Zustandsübergänge verwalten

4. Sehen Sie sich Zeile 158 in diesem ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py an (keine Aktion erforderlich): Wenn Sie sich fragen, wie die Anwendung die endgültige Antwort erhält? Unten sehen Sie eine Ereignisschleife, die vom Runner unterstützt wird:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Die Ereignisschleife: ADK-Agenten antworten nicht einfach nur. Sie denken in einer Schleife. Wenn Sie runner.run_async() anrufen:

1. Die Nutzereingabe wird in die Schleife aufgenommen.
2. Planen: Der Agent berücksichtigt seine Tools und Ziele.
3. Handeln: Bei Bedarf wird ein Tool aufgerufen (z.B. list_files).
4. Beobachtung: Der Agent liest die Ausgabe des Tools.
5. Reflektieren: Es entscheidet, ob es mehr Informationen benötigt oder ob es antworten kann.
6. Schleife: Die Schritte 2 bis 5 werden wiederholt, bis das Ergebnis zufriedenstellend ist.
7. Antworten: Die endgültige Antwort wird an den Nutzer ausgegeben.

Die App im Detail: Architektur und Bereitstellung

Wir verwenden FastAPI, um diesen Agent bereitzustellen.

• Warum FastAPI?: KI-Agenten sind oft E/A-gebunden (warten auf LLMs). Die asynchrone Natur von FastAPI ist dafür perfekt geeignet.
• Zustandslosigkeit: Unser API-Endpunkt ist zustandslos. Wir speichern keine Variablen im globalen Bereich. Wir verwenden session_id und die SessionService, um den Status für jede einzelne Anfrage zu rekonstruieren. Sie können sie also in Cloud Run (serverlos) bereitstellen und auf null skalieren.

8. Anwendung mit dem Agenten-Zauber testen

1. 👉💻 Geben Sie Folgendes in Ihren Befehl ein:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Dadurch wird ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py im Editor geöffnet.
2. Das Ergebnis sieht so aus:👉👉 Klicken Sie auf http://localhost:5173/ oder öffnen Sie ein neues Fenster und geben Sie http://localhost:5173/ ein.

   Beachten Sie, dass es sich NICHT um den Link des Backend-Servers handelt: Uvicorn running on http://0.0.0.0:8000

3. Anschließend wird die Website mit der Chat-Oberfläche angezeigt:
4. Lade ein Bild hoch, um die Funktion zu testen (z. B. von dir selbst oder deinem Haustier)
5. 👉 Fragen Sie dann:

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   Das KI-generierte Bild wird hier angezeigt:
6. 👉💻 Wenn Sie mit dem Testen fertig sind, drücken Sie im Terminal control+C, um den Vorgang zu beenden.

Wenn die Dinge nicht wie erwartet funktionieren, können Sie zu ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution gehen, ./start_app.sh ausführen und dann die oben genannten Schritte ausführen.

9. Vertex AI Memory Bank

Kurzzeit- und Langzeitgedächtnis

• Kurzzeitkontext: „Was habe ich gerade gesagt?“ (Sitzungsverlauf). Diese Informationen gehen verloren, wenn das Chatfenster geschlossen wird.
• Langzeitgedächtnis: „Was ist meine Lieblingsprogrammiersprache?“ (Nutzereinstellungen). Diese sollte dauerhaft beibehalten werden.

Die Vertex AI Memory Bank bietet diesen langfristigen Speicher. Der Agent kann personalisierte Informationen über den Nutzer speichern und abrufen.

Sitzungen und Memory Bank im Vergleich

• Sitzungen (VertexAiSessionService): Das ist das Protokoll. Darin wird die chronologische Abfolge aller Nachrichten, Toolaufrufe und Ereignisse (AppendEvent, ListEvents) im Rohformat gespeichert. Sie liefert die Grundwahrheit dafür, was passiert ist.
• Memory Bank (VertexAiMemoryBankService): Das ist das Wissen. Darin werden zusammengefasste, langfristige Fakten (GenerateMemories, RetrieveMemories) gespeichert. Er ist auf eine bestimmte user_id beschränkt, um Datenschutz und Isolation zu gewährleisten.

1. 👉💻 Geben Sie Folgendes in Ihren Befehl ein:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Dadurch wird ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py im Editor geöffnet.
2. Suchen Sie nach # TODO: Create Vertex AI Session Service & Memory Bank Service und ersetzen Sie die gesamte Zeile durch Folgendes:

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉💻 Geben Sie Folgendes in Ihren Befehl ein:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Dadurch wird ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py im Editor geöffnet.
4. Ersetzen Sie # TODO: Set Up Configuration durch Folgendes:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Hauptfunktionen

Vertex AI Memory Bank ist nicht nur eine Datenbank, sondern ein aktiver kognitiver Dienst.

• Memory-Extraktion: Das System verwendet ein LLM, um die Unterhaltung zu lesen und relevante Fakten basierend auf den von uns definierten CustomMemoryTopic-Schemas (z.B. „Sweater Preferences“) zu extrahieren. Smalltalk wird ignoriert und das Signal wird gespeichert.
• Zusammenfassung gemerkter Informationen: Neue Fakten werden automatisch mit alten zusammengeführt. Wenn ein Nutzer sagt „Ich mag Rot“ und später „Eigentlich mag ich Blau lieber“, wird der Datensatz in Memory Bank aktualisiert, anstatt dass widersprüchliche Duplikate erstellt werden.
• Asynchrone Generierung: Gemerkte Informationen werden im Hintergrund generiert. Ihr KI-Agent gerät nicht ins Stocken, während die Memory Bank über die Unterhaltung „nachdenkt“.

5. 👉 In derselben Datei: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Suchen Sie nach # TODO: Set up topic und ersetzen Sie die gesamte Zeile durch Folgendes:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 In derselben Datei: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Suchen Sie nach # TODO: Create Agent Engine und ersetzen Sie die gesamte Zeile durch Folgendes:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Agent Engine

Die Agent Engine ist die „Gehirnhardware“ in der Cloud. Verwaltet:

• Vektordatenbank: Zum Speichern von Erinnerungen.
• Indexierung: Damit Erinnerungen durchsuchbar sind.
• API: Damit der Agent sie abfragen kann. Wenn Sie deploy_agent.py ausführen, stellen Sie diese Hardware im Wesentlichen bereit.

Warum nicht einfach den Prompt verwenden?

Sie fragen sich vielleicht: „Warum fügen wir den Verlauf des Nutzers nicht einfach in den Prompt ein?“

• Größenbeschränkungen: Kontextfenster sind groß, aber nicht unendlich. Du kannst nicht 5 Jahre Geschichte in einen Film packen.
• Kosten: Die Verarbeitung von 1 Million Tokens für jedes „Hallo“ ist unerschwinglich.
• Fokus: Die Memory Bank fungiert als Suchmaschine für Ihren Agenten. Es ruft nur die relevanten Fakten ab.

7. 👉💻 Geben Sie Folgendes in Ihren Befehl ein:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Dadurch wird ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py im Editor geöffnet.
8. Ersetzen Sie in der Datei ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py den Wert # TODO: Add PreloadMemoryTool durch Folgendes:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool und add_session_to_memory

In agent.py sehen Sie zwei wichtige Komponenten:

• PreloadMemoryTool: Mit diesem Tool kann der Agent „sich selbst googeln“. Wenn der Nutzer etwas Vages fragt, z. B. „Bestell mir meinen üblichen Kaffee“, kann der Agent dieses Tool verwenden, um die Memory Bank nach „Kaffeepräferenzen“ abzufragen, bevor er antwortet.
• add_session_to_memory: Dies ist ein Hintergrund-Callback.
  • Warum asynchron? Das Speichern von gemerkten Informationen dauert etwas (Zusammenfassen des Chats, Extrahieren von Fakten). Wir möchten nicht, dass der Nutzer darauf warten muss. Wir führen ihn im Hintergrund (add_session_to_memory) mit after_agent_callback aus.

10. Memory Bank in Aktion

1. 👉💻 Geben Sie Folgendes in Ihren Befehl ein:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Das Ergebnis sieht so aus:

   In diesem use_memory_bank.sh-Script wird zuerst die Datei 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py verwendet, um die Agent Engine an Ihren KI-Agenten anzuhängen, damit dieser die Vertex AI Memory Bank verwenden kann. Anschließend wird die Datei .env aktualisiert, sodass die Agent Engine-ID als environmental variable gespeichert wird.

   Prüfen Sie die Datei ~/holiday_workshop/.env. Sie sehen dann (Keine Maßnahmen erforderlich).

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Testen Sie die gemerkten Informationen über die Benutzeroberfläche der Anwendung. Geben Sie den folgenden Befehl ein:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Klicken Sie auf http://localhost:5173/ oder öffnen Sie ein neues Fenster und geben Sie http://localhost:5173/ ein. Beachten Sie, dass Uvicorn running on http://0.0.0.0:8000 nur der Backend-Server ist, nicht der eigentliche Link, auf den wir klicken möchten. Die Chat-Oberfläche auf der Website ist jetzt Ihr personalisierter Agent.
3. 👉 Testen Sie die gemerkten Informationen. Wenn Sie in der Benutzeroberfläche Folgendes eingeben:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

Der Agent erkennt dies als Einstellung und speichert sie in der Memory Bank.

Wenn Sie nächste Woche (oder jederzeit, wenn Sie die Anwendung mit Control+C und ./start_app.sh neu starten) Folgendes fragen:

what is my preference on sweater pattern?

Der KI-Agent fragt die Memory Bank ab, sieht Ihre Einstellung und generiert ein Pullovermuster, ohne dass Sie danach fragen müssen.

Personalisierung: Dies ist entscheidend für die Entwicklung nützlicher KI-Agenten. Durch das Speichern von Nutzerpräferenzen (Pullovermuster, persönlicher Kontext) wird der KI-Agent im Laufe der Zeit immer effizienter und hilfreicher.

4. Prüfen Sie dies in der Vertex AI Agent Engine, indem Sie die Google Cloud Console Agent Engine aufrufen.
   • Wählen Sie das Projekt oben links in der Projektauswahl aus:
   • Prüfen Sie die Agent-Engine, die Sie gerade mit dem vorherigen Befehl bereitgestellt haben: use_memory_bank.shKlicken Sie auf die Agent-Engine, die Sie gerade erstellt haben.
5. Klicken Sie bei diesem bereitgestellten KI-Agenten auf den Tab Memories. Hier können Sie alle gemerkten Informationen ansehen.

Glückwunsch! Sie haben die Memory Bank gerade an Ihren Agenten angehängt.

11. Fazit

Zusammenfassung

Sie haben erfolgreich ein vollständiges agentisches System entworfen und erstellt.

• Konnektivität: Sie haben das MCP verwendet, um den Zugriff Ihres KI-Agenten auf lokale Tools zu standardisieren.
• Orchestrierung: Sie haben das ADK verwendet, um die komplexe Reasoning Loop zu verwalten, die für mehrstufige Aufgaben erforderlich ist.
• Personalisierung: Sie haben Memory Bank verwendet, um eine persistente, lernende Ebene zu erstellen, die sich den Nutzerkontext merkt.

Nächste Schritte

• Eigenen MCP-Server erstellen: Erstellen Sie einen Server für Ihre interne API oder Datenbank.
• ADK-Muster kennenlernen: Hier finden Sie Informationen zu „Reasoning Loops“ und „Orchestrierung“ in der ADK-Dokumentation.
• Bereitstellen: Bringen Sie Ihren KI-Agenten von einem lokalen Skript zu einem Produktionsdienst in Cloud Run.

Weiterentwickeln: Die Kombination aus MCP für die Konnektivität und Memory Bank für die Personalisierung bildet die Grundlage für die nächste Generation intelligenter Anwendungen.