ADK Agentic Pattern mit Memory & MCP

1. Lerninhalte

Willkommen zur ADK Master Class – Ihre Reise in die Welt der Multi-Agent-Systeme

Sie betreten die aufregende Welt der KI-Agenten. Vergessen Sie einfache Chatbots, die nur Fragen beantworten. Wir tauchen tief in das Agent Development Kit (ADK) ein, um hochentwickelte, autonome Systeme zu erstellen, die argumentieren, planen und Tools verwenden können, um komplexe Aufgaben zu erledigen.

Dieses Codelab ist eine praktische Reise. Dieses GitHub-Repository enthält den gesamten Code und alle Beispiele für unsere Sitzungen. github repo

Am Ende dieser Anleitung können Sie:

• Ihren ersten KI-Agenten erstellen: Sie beginnen bei null und entwickeln einen voll funktionsfähigen Agenten, der die Bedürfnisse eines Nutzers verstehen, Tools wie die Google Suche verwenden und detaillierte, hilfreiche Antworten generieren kann.
• Multi-Agent-Systeme erstellen: Sie lernen das Muster „Agent als Tool“ kennen, ein revolutionäres Konzept, bei dem Agenten Aufgaben an andere spezialisierte Agenten delegieren und so ein Team von KI-Experten bilden, die zusammenarbeiten.
• Komplexe Workflows orchestrieren: Sie gehen über die einfache Delegierung hinaus und beherrschen erweiterte Muster wie Router, Sequenzielle Ketten, Schleifen und Parallele Ausführung, um robuste, effiziente und intelligente Anwendungen zu erstellen, die fast alle Anfragen verarbeiten können.
• Ihren Agenten ein Gedächtnis geben: Sie verstehen die entscheidende Rolle des Konversationsgedächtnisses, mit dem Ihre Agenten Folgefragen beantworten, aus Feedback lernen und mehrstufige Aufgaben nahtlos verwalten können.
• Verbindung mit MCP herstellen: Verbindung mit der MCP Toolbox herstellen.

Los geht's! 🚀

2. Einrichtung: API-Schlüssel abrufen

API-Schlüssel für Google AI Studio einrichten

Dieses Codelab wird vollständig mit einem kostenlosen API-Schlüssel von Google AI Studio ausgeführt. Es sind kein Google Cloud-Projekt, kein Rechnungskonto und keine Guthaben erforderlich. Jede Sitzung, einschließlich „Memory“ (Sitzung 6) und MCP (Sitzung 7), wird lokal mit Ihrem Schlüssel ausgeführt. Jeder Lernende verwendet seinen eigenen Schlüssel. Das API-Kontingent gilt also pro Person und wird nicht geteilt.

Voraussetzungen:

• Python 3.9 oder höher (python3 --version zum Prüfen)
• Ein Google-Konto (zum Erstellen des AI Studio-Schlüssels)
• Ein Terminal – sowohl Ihr lokaler Computer als auch Cloud Shell funktionieren
• ~10 Minuten

Um unsere KI-Agenten zu nutzen, benötigen wir einen Gemini API-Schlüssel von Google AI Studio. Das ist der schnellste Weg, um loszulegen.

Schritt 1: Gemini API-Schlüssel von AI Studio abrufen (1 Minute)

1. Öffnen Sie https://aistudio.google.com/app/apikey in einem neuen Browsertab.
2. Melde dich mit deinem Google-Konto an.
3. Klicken Sie oben rechts auf „API-Schlüssel erstellen“.
4. Ein Dialogfeld mit einem Drop-down-Menü für das Projekt wird geöffnet:

• Wenn Sie bereits ein Google-Projekt erstellt haben: Wählen Sie es aus und klicken Sie auf "API-Schlüssel in vorhandenem Projekt erstellen"
• Wenn es nicht in der Liste ist: Klicken Sie auf "Projekt erstellen".

5. Kopieren Sie den angezeigten API-Schlüssel. Er beginnt mit AIza... und ist etwa 40 Zeichen lang.

✏️ Fügen Sie ihn an einem sicheren Ort ein – Sie benötigen ihn in Schritt 4 unten.

Behandeln Sie den API-Schlüssel wie ein Passwort. Fügen Sie ihn nicht in öffentlichen Chats oder Screenshots ein und übertragen Sie ihn nicht in ein öffentliches GitHub-Repository.

Schritt 2: Repository klonen (1 Minute)

👉💻 Öffnen Sie Ihr Terminal (oder Cloud Shell) und klonen Sie das Repository für die Anleitung:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Schritt 3: Virtuelle Umgebung erstellen und Abhängigkeiten installieren

👉💻 Erstellen und aktivieren Sie eine virtuelle Umgebung mit dem Namen .adk_env und installieren Sie dann die Abhängigkeiten:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Am Anfang der Terminaleingabeaufforderung sollte (.adk_env) angezeigt werden.

Schritt 4: 🔥 WICHTIG: API-Schlüssel hinzufügen

⚠️ Überspringen Sie diesen Schritt nicht! Erstellen Sie im Stammverzeichnis des Ordners adk_tutorial eine Datei .env. Diese eine Datei unterstützt jede Sitzung in diesem Codelab. Die ADK Web-Sitzungen (1–5) und die Befehlszeilensitzungen „Memory“ und MCP (6–7) lesen sie automatisch.

👉💻 Erstellen Sie die Datei .env mit Ihrem Schlüssel (ersetzen Sie your_actual_api_key_here durch den Schlüssel aus Schritt 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Ihre Datei ~/adk_tutorial/.env sollte jetzt Folgendes enthalten:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 WICHTIG: Ersetzen Sie your_actual_api_key_here durch Ihren tatsächlichen API-Schlüssel aus Schritt 1 (er beginnt mit AIza...).

⚠️ Achten Sie darauf, dass GOOGLE_GENAI_USE_VERTEXAI auf FALSE gesetzt ist. Dadurch wird das ADK angewiesen, sich mit Ihrem Google AI Studio API-Schlüssel anstelle von Vertex AI zu authentifizieren.

✅ Checkpoint: Sie haben eine Datei .env unter ~/adk_tutorial/.env mit Ihrem Schlüssel AIza... und in der Terminaleingabeaufforderung wird (.adk_env) angezeigt. Sie können jetzt Agenten erstellen!

3. Sitzung 1: Ihr erster Agent in ADK Web

Öffnen Sie ADK Web, indem Sie Folgendes ausführen:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Nach dem Ausführen der Befehle sollte in Ihrem Terminal eine Ausgabe angezeigt werden, die darauf hinweist, dass der ADK Web-Server gestartet wurde. Sie sieht in etwa so aus:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Öffnen Sie als Nächstes Ihren Browser unter http://localhost:8000, um auf die ADK-Entwicklungsoberfläche zuzugreifen.

Wird in Cloud Shell anstelle von lokal ausgeführt? Klicken Sie in der Cloud Shell-Symbolleiste (normalerweise oben rechts) auf das Symbol Webvorschau, wählen Sie Port ändern aus, legen Sie den Port auf 8000 fest und klicken Sie auf "Ändern und Vorschau". Cloud Shell öffnet die ADK-Entwicklungsoberfläche in einem neuen Browsertab.

👉 Ihr Beschwörungsritual ist abgeschlossen und der Agent wird jetzt ausgeführt. Die ADK-Entwicklungsoberfläche in Ihrem Browser ist Ihre direkte Verbindung zum Familiar.

Ersten Agenten auswählen Wählen Sie im Drop-down-Menü oben auf der Benutzeroberfläche a_single_agent aus.

Sie können a_single_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

👉 Test-Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sitzung 2: Workflow-Agent: Sequenzieller Agent, paralleler Agent, Schleifen-Agent

Öffnen Sie die ADK Web-Benutzeroberfläche gemäß den Schritten in Sitzung 1.

Paralleler Agent

Parallelen Workflow-Agenten auswählen Wählen Sie im Drop-down-Menü oben auf der Benutzeroberfläche b2_parallel_agent aus.

👉 Test-Prompt:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Sie können b2_parallel_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

Sequenzieller Agent

Sequenziellen Workflow-Agenten auswählen Wählen Sie im Drop-down-Menü oben auf der Benutzeroberfläche b1_sequential_agent aus.

👉 Test-Prompt:

Find a good sushi near Standford and tell me how to get there.

Sie können b1_sequential_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

Schleifen-Agent

Schleifen-Workflow-Agenten auswählen Wählen Sie im Drop-down-Menü oben auf der Benutzeroberfläche b3_loop_agent aus.

👉 Test-Prompt:

Plan a trip from Sunnyvale to San Francisco today.

Sie können b3_loop_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

5. Sitzung 3: Benutzerdefinierter Agent

Öffnen Sie die ADK Web-Benutzeroberfläche gemäß den Schritten in Sitzung 1.

Wenn die ADK Web-Benutzeroberfläche geöffnet ist, wählen Sie im Drop-down-Menü c_custom_agent aus.

👉 Test-Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Sie können c_custom_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

6. Sitzung 4: Orchestrator-Muster – Routing-Agent

Öffnen Sie die ADK Web-Benutzeroberfläche gemäß den Schritten in Sitzung 1.

Wenn die ADK Web-Benutzeroberfläche geöffnet ist, wählen Sie im Drop-down-Menü d_routing_agent aus.

👉 Test-Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Sie können d_routing_agent hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

7. Sitzung 5: Agent als Tool

Öffnen Sie die ADK Web-Benutzeroberfläche gemäß den Schritten in Sitzung 1.

Wenn die ADK Web-Benutzeroberfläche geöffnet ist, wählen Sie im Drop-down-Menü e_agent_as_tool aus.

👉 Test-Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Sie können e_agent_as_tool hier auswählen:

Die Ablaufverfolgung sehen Sie hier:

8. Sitzung 6: Agent mit Langzeitgedächtnis

Wird vollständig lokal ausgeführt. In dieser Sitzung wird das Konversationsgedächtnis in einer lokalen SQLite-Datenbank (unter ~/.adk/) gespeichert, sodass Ihre Einstellungen auch nach Neustarts beibehalten werden. Google Cloud, Rechnungskonto oder Guthaben sind nicht erforderlich. Der Agent liest Ihren AI Studio-Schlüssel aus der Datei ~/adk_tutorial/.env, die Sie bei der Einrichtung erstellt haben.

👉💻 Testen Sie Ihr Langzeitgedächtnis, indem Sie zum Ordner wechseln und den Runner verwenden, um den Agenten zu starten:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test-Prompt:

I like Art and Italian food.

Beenden Sie dann die Sitzung, indem Sie Strg+C drücken. Starten Sie die Sitzung neu:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test-Prompt:

Plan a trip to San Francisco based on my preference.

✅ Der Agent sollte sich an „Art and Italian food“ aus der vorherigen Ausführung erinnern. Das ist das Langzeitgedächtnis, das über Sitzungen hinweg funktioniert.

9. Sitzung 7: Agent mit MCP unterstützen

Wird vollständig lokal ausgeführt. In dieser Sitzung wird ein lokaler MCP Toolbox-Server gestartet, der eine lokale SQLite-Datenbank (destinations.db) liest. Google Cloud, Rechnungskonto oder Guthaben sind nicht erforderlich. Der einzige externe Download ist die Open-Source-Binärdatei der MCP Toolbox.

Schritt 1: Lokale Datenbank vorbereiten

👉💻 Erstellen Sie im Stammverzeichnis des Repositorys die Beispieldatenbank:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Dadurch wird destinations.db in ~/adk_tutorial/ erstellt.

⚠️ Die Beispieldatenbank enthält nur vier Städte: Paris, Rom, New York und Tokio (Attraktionstypen: Wahrzeichen, Museum, Park). Prompts, die auf andere Städte verweisen (z.B. San Francisco oder Sunnyvale), geben korrekterweise keine Ergebnisse zurück, da diese Zeilen nicht vorhanden sind. Verwenden Sie beim Testen dieser Sitzung die vier oben genannten Städte.

Schritt 2: MCP Toolbox-Server installieren und ausführen

👉💻 Laden Sie die Binärdatei der MCP Toolbox für Ihr Betriebssystem herunter:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

Sobald der Download abgeschlossen ist, führen Sie Folgendes aus:

chmod +x toolbox

Sie sind nicht sicher, welchen Mac Sie haben? Führen Sie uname -m aus. arm64 = Apple Silicon, x86_64 = Intel. Laden Sie unter Windows .../windows/amd64/toolbox.exe herunter und führen Sie sie über PowerShell aus.

Schritt 3

Führen Sie in einem Terminal den folgenden Befehl aus (lassen Sie ihn ausgeführt – der Agent stellt unter http://127.0.0.1:7001 eine Verbindung her):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Führen Sie in einem anderen Terminal den folgenden Befehl aus:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Test-Prompts (verwenden Sie die Städte, die in der Beispieldatenbank vorhanden sind: Paris, Rom, New York oder Tokio):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Fehlerbehebung für Sitzung 7

• „Verbindung abgelehnt“ / Der Agent findet keine Tools: Der Toolbox-Server im ersten Terminal wird nicht ausgeführt. Starten Sie ihn neu und prüfen Sie, ob er auf Port 7001 wartet.
• Jede Abfrage gibt leere Ergebnisse zurück:Prüfen Sie, ob Sie Schritt 1 ausgeführt haben, sodass ~/adk_tutorial/destinations.db vorhanden ist, und ob Ihr Prompt eine der vier Städte (Paris, Rom, New York, Tokio) verwendet.
• toolbox: cannot execute binary file unter macOS:Sie haben die Linux-Version heruntergeladen. Führen Sie Schritt 2 noch einmal mit OS=darwin/arm64 (Apple Silicon) oder OS=darwin/amd64 (Intel) aus.