Personalisierte Agents mit ADK, MCP und Memory Bank erstellen

1. Einführung

Der moderne Agent-Stack

Für die Entwicklung eines KI-Agents, der in der Produktion eingesetzt werden kann, ist mehr als nur ein Large Language Model (LLM) erforderlich. Während ein LLM die Reasoning-Funktionen bereitstellt, muss ein robuster Agent mit der Außenwelt interagieren, den Unterhaltungsstatus verwalten und sich die Nutzerpräferenzen im Laufe der Zeit merken.

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

1. Konnektivität (MCP): Damit Ihr Agent auf lokale Tools und Daten zugreifen kann.
2. Orchestrierung (ADK): Zum Verwalten des Schlussfolgerungszyklus und des Status des Agents.
3. Arbeitsspeicher (Memory Bank): Um langfristigen, personalisierten Kontext bereitzustellen.

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 Agents bereitstellt und die Ereignisschleife, Statusübergänge und die Ausführung von Tools verwaltet.
Session Service	Verarbeitet das Kurzzeitgedächtnis. Der unmittelbare Kontext der Unterhaltung wird beibehalten (z.B. „Was hat der Nutzer gerade gefragt?“), wird aber gelöscht, wenn die Sitzung endet.
Vertex AI Memory Bank	Verwaltet das Langzeitgedächtnis. Sie speichert nutzerspezifische Fakten und Einstellungen (z.B. „User prefers Python“ (Nutzer bevorzugt Python) auf unbestimmte Zeit gespeichert, damit der Agent zukünftige Interaktionen personalisieren kann.
Vertex AI Agent Engine	Der verwaltete Infrastrukturdienst, der Ihre Agentenlogik und Speicherkonfigurationen in großem Umfang hostet.

Umfang

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

Sie durchlaufen drei Phasen:

1. Tooling Layer: Erstellen Sie einen MCP-Server, um lokale Python-Funktionen für die KI verfügbar zu machen.
2. Agent Layer: 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 Agent die Stilvorlieben der Nutzer lernen und sich merken kann.

2. Erstelle ein

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

Teil 1: Rechnungskonto aktivieren

• Sie müssen Ihr Rechnungskonto mit einem Guthaben von 5 $ in Anspruch nehmen, da Sie es für die Bereitstellung benötigen. Melden Sie sich in Ihrem Gmail-Konto an.

Keine Kreditkarte oder Zahlung erforderlich: Sie erhalten 5 $Guthaben. Das dauert weniger als zwei Minuten. Geben Sie einfach Ihren Namen ein und akzeptieren Sie die Credits.

Teil 2: Offene Umgebung

1. 👉 Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
2. 👉 Wenn Sie heute an irgendeinem Punkt 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 das Projekt auf Ihre Projekt-ID festgelegt ist:

   gcloud auth list
   

5. 👉💻 Bootstrap-Projekt von GitHub klonen:

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

6. 👉💻 Führen Sie das Setup-Skript im Projektverzeichnis aus.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Hinweis zur Projekt-ID:Im Skript wird eine zufällig generierte Standardprojekt-ID vorgeschlagen. Sie können die Eingabetaste drücken, um diesen Standardwert zu übernehmen.

   Wenn Sie jedoch lieber ein bestimmtes neues Projekt erstellen möchten, können Sie die gewünschte Projekt-ID eingeben, wenn Sie vom Skript 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: Berechtigung 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. Dort werden Ihre Projektinformationen angezeigt.

3. MCP-Funktionen nutzen

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. So sah es bis vor Kurzem mit KI‑Tools aus. Entwickler mussten benutzerdefinierten „Glue-Code“ schreiben, um LLMs mit Datenbanken, Dateisystemen oder APIs zu verbinden.

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

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

Umfang

In diesem Codelab erstellen Sie einen Holiday Design Assistant, der:

1. Verbindung zur lokalen Umgebung (Studio-Tools) über MCP
2. Verwaltet den Unterhaltungskontext zuverlässig mit dem Agent Development Kit (ADK).
3. Speichert Ihre Einstellungen (z.B. „Ich bevorzuge Python-Code“), über verschiedene Sitzungen hinweg mit Vertex AI Memory Bank.

Warnung: Achten Sie darauf, dass Sie Ihre Google Cloud CLI (gcloud auth login) authentifiziert haben, bevor Sie die Codebeispiele ausführen.

Serverlogik erstellen

Wir haben die Umgebung vorbereitet, aber die Serverlogik ist unvollständig. Wir müssen die vier Tools implementieren, die unser Agent später zum Erstellen unserer Feiertagskarte verwenden wird.

Teil 1: Serverskelett ö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, Verarbeiten von Verbindungen und Initialisieren des Vertex AI-Clients) ist bereits vorhanden. Die vier Kernfunktionen sind jedoch derzeit leere Platzhalter.

Teil 2: Holiday Scene Generator implementieren

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

Suchen Sie in der Funktion generate_holiday_scene nach dem Kommentar #REPLACE_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

Schließlich soll 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 Rendern auszufü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 eingefügt wurde, 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 unseres Projekts hinzuzufügen:

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

Ihrer ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml-Datei wird eine neue Abhängigkeit fastmcp>=2.13.3 hinzugefügt.

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

Nachdem wir den Servercode fertiggestellt haben, stellt sich die Frage, wie wir ihn testen können.

Normalerweise erfordert das Testen eines Back-End-Servers das Erstellen einer Front-End-Benutzeroberfläche oder das Schreiben komplexer curl-Anfragen. Hier können wir jedoch die Gemini CLI verwenden.

Was ist die Gemini CLI?

Gemini CLI ist ein Befehlszeilentool, mit dem Sie direkt in Ihrem Terminal mit einem Gemini-Modell chatten können. Es hat jedoch eine besondere Funktion: Es kann automatisch die Tools erkennen und verwenden, die auf Ihrem lokalen MCP-Server ausgeführt werden.

Das ist für die Entwicklung sehr nützlich, da die Logik isoliert wird. Sie können überprüfen, ob das Modell Ihre Tools versteht und sie richtig aufruft, bevor Sie sich Gedanken über die Entwicklung einer Weboberfläche oder eines Agent-Frameworks machen.

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 gegeben („holidays“).
• uv run ...: Wir haben den expliziten Befehl zum Starten des gerade geänderten Python-Servers angegeben.

Bereit für Magie?

So starten Sie die Chatsitzung:

gemini

Probieren Sie den folgenden Prompt aus, um zu testen, ob Gemini Ihre neuen Tools „sehen“ kann. Hinweis: Möglicherweise müssen Sie der Gemini CLI die Verwendung unseres Feiertagstools 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, konnte die KI genau nachvollziehen, welche Python-Funktion aufgerufen werden muss, um Ihre Anfrage zu erfüllen.

Bild ansehen

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

Sie können Ihr Foto hier 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 generieren, Bilder zusammenfügen und Szenen optimieren können.

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

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, benötigen wir mehr Kontrolle. Wir möchten ein System, das in der Lage ist, seine eigene Arbeit zu planen und zu kritisieren und den Status unserer Weihnachtskarte zu verwalten, ohne dass wir es bei jedem Schritt an die Hand nehmen müssen.

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

5. ADK-Agent per Vibe Coding erstellen

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

In diesem Abschnitt erstellen wir einen KI-Agenten: ein System, das mehrstufige Aufgaben autonom ausführen, planen und begründen kann. Dazu verwenden wir das Agent Development Kit (ADK).

Was ist ein 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 Feiertagskarte für mich“), zerlegt 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 diese Agenten ganz einfach erstellen lassen. Es übernimmt die komplexe „Infrastruktur“, z. B. die Verwaltung des Chatverlaufs, die Verbindung zu Tools und das Umschalten zwischen verschiedenen Modellen, sodass Sie sich auf die Persönlichkeit und Logik Ihrer App konzentrieren können.

Kontextbasiertes Vibe-Coding

Es ist ein gängiges Muster, einen einzelnen, umfangreichen Prompt zu verwenden, um Code zu generieren. Beim Erstellen komplexer Anwendungen ist es jedoch oft besser, die KI als Partner zu betrachten, der im Laufe der Zeit Kontext beibehält.

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

1. Umgebung vorbereiten

Öffnen Sie Ihr Terminal und wechseln Sie zum Starter-Verzeichnis:

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

Gemini CLI starten:

gemini

2. Kontext und Speicherkapazität 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: Damit können Sie grundlegendes Wissen einfügen, das sich die KI während der gesamten Unterhaltung merken soll.

Beginnen wir mit der Definition der Persona unseres Coding-Partners. 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 kennt jetzt seine Rolle. Dieser Kontext beeinflusst jede nachfolgende Antwort und sorgt für hochwertigen, ADK-konformen Code.

3. Schritt 1: Grundlegenden Agenten mit Vibe-Code versehen

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

Geben Sie den folgenden Prompt in die 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 generiert die Dateistruktur und den ersten Python-Code. Prüfen Sie die Änderungen und übernehmen bzw. akzeptieren Sie sie dann.

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

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

Geben Sie den folgenden Prompt in die 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 Ihren vorhandenen agent.py, um die Tool-Definitionen und die Verbindungslogik einzuschließen.

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 unter ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution vergleichen.

6. Agent-Weboberfläche ausführen

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

1. Wenn Sie GeminiCLI noch geöffnet haben, drücken Sie control+C, um es zu schließen. Führen Sie nun in Ihrem Terminal(im Ordner solution) Folgendes aus: Sie können starter aufrufen, um Ihren Code zu 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 weist Sie darauf hin, dass ein Dienst auf Port 8000 ausgeführt wird. Klicken Sie auf Webvorschau > Vorschau auf Port 8000.

Agent testen

Jetzt sollte eine Chatoberfläche angezeigt werden. Sehen wir uns an, ob unser KI-Agent die neuen Anweisungen befolgt und korrekt auf die MCP-Tools zugreift.

Probieren Sie diese Prompts aus:

• „Hallo! Wer bist du?“
  • (Erwarte eine festliche, enthusiastische Antwort).
• „Ich brauche einen Hintergrund für meine Weihnachtskarte. Mach daraus ein verschneites Dorf.“
  • Der Kundenservicemitarbeiter sollte generate_holiday_scene anrufen. Beachten Sie, dass automatisch der in den Systemanweisungen definierte Stil „niedlich/Cartoon“ angewendet wird.
• „Erstelle ein Strickmuster für einen Pullover 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 festlegen:Wir haben /memory add verwendet, um eine Experten-Persona zu definieren.
• Wir haben iterativ entwickelt:Wir haben zuerst das Grundgerüst erstellt und dann die Tool-Verbindungen hinzugefügt.

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

Wenn Sie während des Workshops auf Unexpected response from metadata server: service account info is missing 'email' field gestoßen sind, müssen Sie 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 Agent-Definition haben, müssen wir sie ausführen. Hier kommen der Runner und der Sitzungsdienst ins Spiel.

Implementierung

1. 👉 Geben Sie Folgendes in den 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 Sitzungsservice ist der „Arbeitsspeicher“ Ihres Agenten.

   • Rolle: Hier wird der unmittelbare, unaufgeräumte Verlauf der aktuellen Unterhaltung gespeichert (z.B. „Was habe ich gerade gefragt?“).
   • Zwei Varianten:
   • InMemorySessionService: Schnell, einfach, aber amnestisch. Wenn Sie den Server neu starten, vergisst der Agent alles. Ideal zum Testen.
   • VertexAiSessionService: Robust, datenbankbasiert. Der Status wird in Google Cloud gespeichert, sodass die Unterhaltung auch Wochen später oder nach Serverneustarts 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“. Es hält den Blutfluss aufrecht. Der Runner ist für Folgendes verantwortlich:

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

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

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

Die Ereignisschleife: ADK-Agents antworten nicht einfach. Sie denken in einem Kreislauf. Wenn Sie runner.run_async() anrufen:

1. User Input (Nutzereingabe) wird in die Schleife eingegeben.
2. Planen: Der Agent berücksichtigt seine Tools und Ziele.
3. Aktion: Falls zutreffend, wird ein Tool aufgerufen (z.B. list_files).
4. Beobachten: Die Tool-Ausgabe wird gelesen.
5. Reflect (Überlegen): Das Modell entscheidet, ob weitere Informationen erforderlich sind oder ob es die Frage beantworten kann.
6. Schleife: Die Schritte 2 bis 5 werden wiederholt, bis das Ergebnis zufriedenstellend ist.
7. Antworten: Hier wird die endgültige Antwort an den Nutzer gesendet.

Im Detail: Architektur und Bereitstellung

Wir verwenden FastAPI, um diesen Agent bereitzustellen.

• Warum FastAPI?: Agents sind oft E/A-gebunden (warten auf LLMs). FastAPI ist asynchron und kann das problemlos bewältigen.
• Zustandslosigkeit: Unser API-Endpunkt ist zustandslos. Variablen werden nicht im globalen Bereich gespeichert. Wir verwenden session_id und SessionService, um den Status für jede einzelne Anfrage zu rekonstruieren. Sie können die Anwendung also in Cloud Run (serverlos) bereitstellen und auf null skalieren.

8. Anwendung mit Agent-Funktionen testen

1. 👉💻 Geben Sie Folgendes in den 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 sollte so aussehen:👉👉 Klicken Sie auf http://localhost:5173/ oder öffnen Sie ein neues Fenster und geben Sie http://localhost:5173/ ein.

   ACHTUNG: Dies ist NICHT der Link des Backend-Servers: Uvicorn running on http://0.0.0.0:8000

3. Sie werden dann zur Website mit der Chatoberfläche weitergeleitet:
4. Testen Sie die Funktion, indem Sie ein Bild hochladen(z. B. von sich selbst oder Ihrem Haustier). 
5. 👉 Dann fragen

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

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

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

9. Vertex AI Memory Bank

Kurzzeit- und Langzeitgedächtnis

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

Vertex AI Memory Bank bietet diese langfristige Speicherung. So kann der Agent personalisierte Informationen über den Nutzer speichern und abrufen.

Sitzungen im Vergleich zu Memory Bank

• Sitzungen (VertexAiSessionService): Dies ist das Log. Darin wird die chronologische Rohfolge aller Nachrichten, Tool-Aufrufe und Ereignisse (AppendEvent, ListEvents) gespeichert. Sie enthält die Grundlage für die Frage Was ist passiert?.
• Memory Bank (VertexAiMemoryBankService): Dies ist das Wissen. Darin werden synthetisierte, langfristige Fakten gespeichert (GenerateMemories, RetrieveMemories). Der Umfang ist auf eine bestimmte user_id beschränkt, um Datenschutz und Isolation zu gewährleisten.

1. 👉💻 Geben Sie Folgendes in den 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 den 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 Extraction (Speicherextraktion): Das System verwendet ein LLM, um die Unterhaltung zu lesen und aussagekräftige Fakten basierend auf den von uns definierten CustomMemoryTopic-Schemas zu extrahieren (z.B. „Sweater Preferences“). Es ignoriert Smalltalk und speichert das Signal.
• Memory Consolidation: 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 Memory-Eintrag in Memory Bank aktualisiert, anstatt widersprüchliche Duplikate zu erstellen.
• Asynchrone Generierung: Erinnerungen werden im Hintergrund generiert. Ihr Agent hält nicht an, während die Memory Bank über das Gespräch „nachdenkt“.

5. 👉 In der gleichen 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 „Brain-Hardware“ in der Cloud. Folgendes wird 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 Grunde bereit.

Warum nicht einfach den Prompt verwenden?

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

• Größenbeschränkungen: Kontextfenster sind groß, aber nicht unendlich. Sie können nicht 5 Jahre Verlauf anzeigen.
• Kosten: Die Verarbeitung von 1 Million Token für jedes „Hallo“ ist unerschwinglich teuer.
• Fokus: Die Speicherbank fungiert als Suchmaschine für Ihren Agenten. Es werden nur die relevanten Fakten abgerufen.

7. 👉💻 Geben Sie Folgendes in den 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 # TODO: Add PreloadMemoryTool durch Folgendes:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool und add_session_to_memory

Im Verzeichnis agent.py werden zwei wichtige Komponenten angezeigt:

• PreloadMemoryTool: Mit diesem Tool kann der Agent „sich selbst googeln“. Wenn der Nutzer etwas vages fragt, z. B. „Bring mir meinen üblichen Kaffee“, kann der Agent mit diesem Tool die Memory Bank nach „Kaffeevorlieben“ durchsuchen, bevor er antwortet.
• add_session_to_memory: Dies ist ein Hintergrund-Callback.
  • Warum asynchron? Das Speichern von Erinnerungen dauert eine Weile, da der Chat zusammengefasst und Fakten extrahiert werden müssen. Wir möchten nicht, dass der Nutzer darauf warten muss. Wir führen sie im Hintergrund (add_session_to_memory) mit after_agent_callback aus.

10. Memory Bank in Aktion

1. 👉💻 Geben Sie Folgendes in den 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-Skript wird zuerst die Datei 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py verwendet, um die Agent Engine an Ihren Agenten anzuhängen, damit Ihr Agent 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 Ihre ~/holiday_workshop/.env-Datei. Dort wird (keine Maßnahmen erforderlich) angezeigt.

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Testen Sie den Speicher mit der Benutzeroberfläche der Anwendung. Geben Sie Folgendes in Ihren 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 tatsächliche Link, auf den wir klicken möchten. Die Chatoberfläche auf der Website ist jetzt Ihr personalisierter Agent.
3. 👉 Arbeitsspeicher testen Wenn Sie in der Benutzeroberfläche tippen:

   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 Präferenz und speichert sie im Memory Bank.

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

what is my preference on sweater pattern?

Der Agent fragt die Memory Bank ab, sieht sich Ihre Präferenz an und generiert ein Pullovermuster, ohne dass Sie dazu aufgefordert werden.

Personalisierung: Dies ist entscheidend für die Entwicklung nützlicher Agents. Indem sich der Agent die Nutzerpräferenzen (Strickmuster, persönlicher Kontext) merkt, wird er mit der Zeit effizienter und hilfreicher.

4. Prüfen Sie in Vertex AI Agent Engine, indem Sie Google Cloud Console Agent Engine
   aufrufen.
   • Achten Sie darauf, dass Sie das Projekt oben links in der Projektauswahl auswählen:
   • 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 in diesem bereitgestellten KI-Agenten auf den Tab Memories, um alle gemerkten Informationen anzusehen.

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

11. Fazit

Zusammenfassung

Sie haben erfolgreich ein vollständiges Agentensystem konzipiert und erstellt.

• Verbindung: Sie haben MCP verwendet, um den Zugriff Ihres KI-Agenten auf lokale Tools zu standardisieren.
• Orchestrierung: Sie haben das ADK verwendet, um den komplexen Reasoning-Loop zu verwalten, der 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: In der ADK-Dokumentation finden Sie Informationen zu „Reasoning Loops“ und „Orchestration“.
• Bereitstellen: Stellen Sie Ihren Agent als Produktionsdienst in Cloud Run bereit.

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.