1. Hinweis
Willkommen zum ersten Teil der Reihe „KI-Agenten mit dem ADK erstellen“! In dieser praxisorientierten Codelab-Reihe erstellen Sie mit dem Agent Development Kit (ADK) von Google Ihren eigenen intelligenten KI-Agenten.
Wir beginnen mit den absoluten Grundlagen und führen Sie durch die Einrichtung Ihrer Entwicklungsumgebung und die Erstellung eines grundlegenden dialogorientierten Agents. Am Ende dieses Codelabs haben Sie Ihre erste interaktive KI erstellt, die in den nachfolgenden Teilen dieser Reihe erweitert wird, wenn wir sie in ein komplexes Multi-Agent System (MAS) umwandeln.
Sie können dieses Codelab entweder in Ihrer lokalen Umgebung oder in Google Cloud durcharbeiten. Für eine möglichst konsistente Umgebung empfehlen wir die Verwendung von Cloud Shell in der Google Cloud-Umgebung. Cloud Shell bietet außerdem 5 GB nichtflüchtigen Speicher im Verzeichnis $HOME. Das ist nützlich, um Skripts, Konfigurationsdateien oder geklonte Repositorys zu speichern.
Voraussetzungen
- Grundkenntnisse der Konzepte generativer KI
- Grundlegende Kenntnisse der Python-Programmierung
- Kenntnisse der Befehlszeile / des Terminals
Lerninhalte
- Python-Umgebung einrichten
- Einen einfachen persönlichen Assistenten-Agenten mit dem ADK erstellen
- Agent ausführen, testen und Fehler beheben
Voraussetzungen
- Ein funktionierender Computer und eine zuverlässige WLAN-Verbindung
- Ein Browser wie Chrome für den Zugriff auf die Google Cloud Console
- Ein Google Cloud-Projekt mit aktivierter Abrechnung
- Neugier und Lernbereitschaft
2. Einführung
Die Welt der generativen KI entwickelt sich rasant und KI-Agents sind derzeit ein heißes Thema. Ein KI-Agent ist ein intelligentes Computerprogramm, das in Ihrem Namen agiert, ähnlich wie ein persönlicher Assistent. Sie kann ihre digitale Umgebung wahrnehmen, Entscheidungen treffen und Maßnahmen ergreifen, um bestimmte Ziele zu erreichen, ohne dass der Mensch direkt eingreifen muss. Stellen Sie sich das als proaktive, autonome Einheit vor, die lernen und sich anpassen kann, um Aufgaben zu erledigen.
Im Grunde nutzt ein KI-Agent ein Large Language Model (LLM) als „Gehirn“, um zu verstehen und Schlussfolgerungen zu ziehen. So kann es Informationen aus verschiedenen Quellen verarbeiten, z. B. Text, Bilder und Töne. Der Agent nutzt dieses Wissen dann, um einen Plan zu erstellen und eine Reihe von Aufgaben auszuführen, um ein vordefiniertes Ziel zu erreichen.
Mit dem Agent Development Kit (ADK) und anderen gebrauchsfertigen Frameworks können Sie jetzt ganz einfach Ihre eigenen KI-Agenten erstellen, auch ohne fundiertes Fachwissen. Wir beginnen damit, einen persönlichen Assistenten-Agenten zu erstellen, der Sie bei Ihren Aufgaben unterstützt. Fangen wir an!
3. Google Cloud-Dienste einrichten
Google Cloud-Projekt erstellen
In diesem Codelab wird davon ausgegangen, dass Sie bereits ein Google Cloud-Projekt mit aktivierter Abrechnung erstellt haben. Wenn Sie noch kein Projekt haben, gehen Sie so vor:
Google Cloud-Projekt auswählen oder erstellen
- Öffnen Sie die Google Cloud Console.
- Klicken Sie oben auf das Drop-down-Menü für die Projektauswahl (neben dem Google Cloud-Logo).
- Wählen Sie ein vorhandenes Projekt aus oder erstellen Sie ein neues.
Abrechnung aktivieren
- Die Abrechnung für das ausgewählte Google Cloud-Projekt muss aktiviert sein.
- Eine Anleitung dazu, wie Sie prüfen können, ob die Abrechnung für ein Projekt aktiviert ist, finden Sie in der Dokumentation zur Abrechnung für Google Cloud.
Cloud Shell konfigurieren
Prüfen wir nun, ob Sie Cloud Shell richtig eingerichtet haben. Cloud Shell ist eine praktische Befehlszeilenschnittstelle direkt in der Google Cloud Console.
Cloud Shell starten
Rechts oben in der Google Cloud Console sehen Sie ein Symbol, das wie ein Terminal aussieht (>_). Klicken Sie darauf, um Cloud Shell zu aktivieren.
Zugriff gewähren
Wenn Sie dazu aufgefordert werden, klicken Sie auf Autorisieren, um Cloud Shell die erforderlichen Berechtigungen für die Interaktion mit Ihrem Google Cloud-Projekt zu erteilen.
Konto bestätigen:
Nachdem Cloud Shell geladen wurde, prüfen wir, ob Sie das richtige Google Cloud-Konto verwenden. Führen Sie dazu diesen Befehl aus:
gcloud auth list
Im Terminal sollte eine ähnliche Befehlsausgabe angezeigt werden:
Credentialed Accounts
ACTIVE: *
ACCOUNT: current_account@example.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
Bei Bedarf Konto wechseln:
Wenn das aktive Konto nicht das Konto ist, das Sie für dieses Codelab verwenden möchten, wechseln Sie mit diesem Befehl zum richtigen Konto. Ersetzen Sie dabei <your_desired_account@example.com> durch Ihre tatsächliche E-Mail-Adresse, die Sie für dieses Lab verwenden möchten:
gcloud config set account <your_desired_account@example.com
Projekt bestätigen
Prüfen Sie als Nächstes, ob Cloud Shell für die Verwendung des richtigen Google Cloud-Projekts konfiguriert ist. Ausführen:
gcloud config list project
Eine Konfigurationsliste wird angezeigt. Suchen Sie nach dem Abschnitt [core] und prüfen Sie, ob der Projektwert mit der ID des Google Cloud-Projekts übereinstimmt, das Sie für dieses Codelab verwenden möchten:
[core] project = <current-project-id>
Projekt festlegen (falls erforderlich)
Wenn der project ID-Wert falsch ist, legen Sie ihn mit dem folgenden Befehl auf das gewünschte Projekt fest:
gcloud config set project <your-desired-project-id>
Erforderliche APIs aktivieren
Wenn Sie Google Cloud-Dienste verwenden möchten, müssen Sie zuerst die entsprechenden APIs für Ihr Projekt aktivieren. Wenn Sie die folgenden Befehle im Cloud Shell-Terminal ausführen, werden alle Dienste aktiviert, die Sie für dieses Codelab benötigen:
gcloud services enable aiplatform.googleapis.com
Wenn der Vorgang erfolgreich war, wird Operation/... finished successfully im Terminal angezeigt.
4. Erstellen Sie eine virtuelle Python-Umgebung
Bevor Sie ein Python-Projekt starten, sollten Sie eine virtuelle Umgebung erstellen. Dadurch werden die Abhängigkeiten des Projekts isoliert und Konflikte mit anderen Projekten oder den globalen Python-Paketen des Systems verhindert. Da für das Agent Development Kit (ADK) Python 3.9 oder höher erforderlich ist, verwenden wir ein Tool wie uv, um sowohl die virtuelle Umgebung zu verwalten als auch dafür zu sorgen, dass die richtige Python-Version verwendet wird.
uv ist ein modernes, schnelles und effizientes Tool zum Verwalten von Python-Projekten und -Umgebungen, das Funktionen kombiniert, die traditionell in Tools wie pip, venv, pip-tools und pipx zu finden sind. Sie ist in Rust geschrieben, um eine hohe Geschwindigkeit zu erreichen.
uv ist bereits in Cloud Shell verfügbar, sodass wir sofort loslegen können.
Prüfen, ob uv korrekt installiert ist
uv --version
Neuen Projektordner für Ihren KI-Agenten erstellen
uv init ai-agents-adk
cd ai-agents-adk
Virtuelle Umgebung mit Python 3.12 erstellen
uv venv --python 3.12
Google ADK-Bibliothek in der virtuellen Umgebung installieren
uv add google-adk
Prüfen, ob das google-adk-Paket erfolgreich installiert wurde
uv pip list | grep google-adk
Wenn Sie eine Ausgaberzeile mit „google-adk“ und der zugehörigen Version sehen, können Sie mit dem nächsten Schritt fortfahren.
5. Agent erstellen
Nachdem Sie Ihre Entwicklungsumgebung eingerichtet haben, können Sie mit der Entwicklung Ihres KI-Agents beginnen. Das Agent Development Kit (ADK) vereinfacht diesen Prozess, da nur wenige wichtige Dateien erforderlich sind, um die Kernlogik und Konfiguration Ihres Agents zu definieren.
Diese drei Dateien sorgen dafür, dass Ihr Agent auffindbar, ausführbar und konfigurierbar ist:
agent.py: Das ist das Herzstück Ihres Agents. Sie enthält den primären Python-Code, der das Verhalten Ihres Agents definiert, einschließlich seines Namens, des Large Language Model (LLM), das er als „Gehirn“ verwendet, und der Kernanweisungen, die seine Antworten steuern.__init__.py: In Python kennzeichnet die Datei__init__.pyein Verzeichnis als Python-Paket. Für das ADK ist das wichtig, weil das Framework so Ihre Agent-Definition ausagent.pyerkennen und laden kann. In einfachen ADK-Projekten enthält sie oft eine einzelne Zeile zum Importieren desagent-Moduls, wodurch der Agent für den ADK-Runner zugänglich wird..env: In dieser Datei (kurz für „environment“) werden vertrauliche Informationen und Konfigurationsvariablen gespeichert, die Ihr Agent benötigt, z. B. API-Schlüssel, Projekt-IDs und geografische Standorte. Es hat sich bewährt, diese Details in einer separaten.env-Datei zu speichern, da so sensible Daten nicht direkt in den Code codiert werden müssen. Das erhöht die Sicherheit und Portabilität. Außerdem können Sie Konfigurationen einfach ändern, ohne die Hauptlogik des Agents anpassen zu müssen.
Verwenden Sie die folgenden Befehle, um diese Dateien in einem dedizierten Ordner für Ihren persönlichen Assistenten-Agent zu erstellen:
uv run adk create personal_assistant
Nachdem der Befehl ausgeführt wurde, werden Sie aufgefordert, einige Optionen zur Konfiguration Ihres Agents auszuwählen. Wählen Sie für den ersten Schritt Option 1 aus, um das gemini-2.5-flash-Modell zu verwenden. Es ist schnell und effizient und eignet sich perfekt für Konversationsaufgaben.
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
Wählen Sie für den zweiten Schritt Vertex AI (Option 2) als Backend-Dienstanbieter aus. Vertex AI ist die leistungsstarke, verwaltete KI-Plattform von Google Cloud.
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
Zum Schluss werden Sie aufgefordert, Ihre Google Cloud-Projekt-ID und -Region zu bestätigen. Wenn Sie die vorausgefüllten Werte (current-project-id und current-region) verwenden möchten, drücken Sie einfach für jede Frage die Eingabetaste.
Enter Google Cloud project ID [current-project-id]: Enter Google Cloud region [current-region]:
Im Terminal sollte eine ähnliche Ausgabe angezeigt werden.
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
Klicken Sie nun oben im Cloud Shell-Fenster auf die Schaltfläche Editor öffnen. Wenn Sie auf diese Schaltfläche klicken, gelangen Sie zum Editor-Fenster, in dem Sie die Inhalte Ihrer Dateien viel einfacher durchsuchen können. Das kann einen Moment dauern. Wenn du länger als ein paar Minuten auf einem Ladebildschirm hängen bleibst, aktualisiere den Browser.
Sobald das Editorfenster vollständig geladen ist, rufen Sie den Ordner personal-assistant auf. Sie sehen die oben genannten erforderlichen Dateien (agent.py, __init__.py und .env). Sehen wir uns den Inhalt an.
Wenn die .env-Datei nicht im Ordner angezeigt wird, klicken Sie oben in der Menüleiste auf „Ansicht“ und wählen Sie dann Verborgene Dateien ein-/ausblenden aus. Das ist eine gängige Einstellung, da .env-Dateien standardmäßig oft ausgeblendet werden, um eine versehentliche Offenlegung zu verhindern.
Sehen wir uns den Inhalt der einzelnen Dateien an.
agent.py
In dieser Datei wird Ihr Agent mit der Klasse Agent aus der Bibliothek google.adk.agents instanziiert.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
from google.adk.agents import Agent: In dieser Zeile wird die erforderlicheAgent-Klasse aus der ADK-Bibliothek importiert.root_agent = Agent(...): Hier erstellen Sie eine Instanz Ihres KI‑Agents.name="personal_assistant": Eine eindeutige Kennung für Ihren Agent. So erkennt und bezeichnet das ADK Ihren KI-Agenten.model="gemini-2.5-flash": Mit diesem wichtigen Parameter wird festgelegt, welches Large Language Model (LLM) Ihr Agent als zugrunde liegendes „Gehirn“ zum Verstehen, Schlussfolgern und Generieren von Antworten verwendet.gemini-2.5-flashist ein schnelles und effizientes Modell, das sich für Dialogaufgaben eignet.description="...": Hier finden Sie eine kurze Zusammenfassung des Zwecks oder der Funktionen des Agents. Die Beschreibung ist eher für das menschliche Verständnis oder für andere Agents in einem Multi-Agent-System gedacht, um zu verstehen, was dieser bestimmte Agent tut. Sie wird häufig für die Protokollierung, das Debugging oder die Anzeige von Informationen zum Agent verwendet.instruction="...": Dies ist der Systemprompt, der das Verhalten Ihres Agents steuert und seine Persönlichkeit definiert. Damit wird dem LLM mitgeteilt, wie es sich verhalten soll und was sein primärer Zweck ist. In diesem Fall wird der Agent als „hilfreicher Assistent“ definiert. Diese Anleitung ist entscheidend, um den Konversationsstil und die Fähigkeiten des Agenten zu beeinflussen.
init.py
Diese Datei ist erforderlich, damit Python personal-assistant als Paket erkennt und das ADK Ihre agent.py-Datei korrekt importieren kann.
from . import agent
from . import agent: In dieser Zeile wird ein relativer Import ausgeführt. Python wird angewiesen, im aktuellen Paket (personal-assistant) nach einem Modul namensagent(dasagent.pyentspricht) zu suchen. Diese einfache Zeile sorgt dafür, dass das ADK beim Laden Ihrespersonal-assistant-Agents die inagent.pydefinierteroot_agentfinden und initialisieren kann. Auch wenn sie leer ist, macht das Vorhandensein von__init__.pydas Verzeichnis zu einem Python-Paket.
.env
Diese Datei enthält umgebungsspezifische Konfigurationen und vertrauliche Anmeldedaten.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: Damit wird dem ADK mitgeteilt, dass Sie den Vertex AI-Dienst von Google für Ihre generativen KI-Vorgänge verwenden möchten. Dies ist wichtig, um die verwalteten Dienste und erweiterten Modelle von Google Cloud nutzen zu können.GOOGLE_CLOUD_PROJECT: Diese Variable enthält die eindeutige Kennung Ihres Google Cloud-Projekts. Das ADK benötigt diese Informationen, um Ihren Agenten korrekt mit Ihren Cloud-Ressourcen zu verknüpfen und die Abrechnung zu ermöglichen.GOOGLE_CLOUD_LOCATION: Gibt die Google Cloud-Region an, in der sich Ihre Vertex AI-Ressourcen befinden (z.B.us-central1). Wenn Sie den richtigen Standort verwenden, kann Ihr Agent effektiv mit den Vertex AI-Diensten in dieser Region kommunizieren.
6. Agent im Terminal ausführen
Wenn alle drei Dateien vorhanden sind, können Sie den Agenten direkt über das Terminal ausführen. Dazu müssen Sie das Terminalfenster öffnen. Klicken Sie in der Menüleiste auf Terminal und wählen Sie dann Neues Terminal aus.
Sobald das Terminal verfügbar ist, können Sie den Agenten mit dem Befehl adk run starten. Da es sich um ein neues Terminalfenster handelt und wir uv verwenden, müssen Sie zuerst in den Ordner ai-agent-adk wechseln und dem Befehl adk run dann uv run voranstellen.
Geben Sie diese Befehle in das Terminal ein:
cd ai-agents-adk
uv run adk run personal_assistant
Wenn alles richtig eingerichtet ist, sehen Sie eine ähnliche Ausgabe in Ihrem Terminal.
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
Chatten Sie mit dem Agent. Die Ausgabe ist manchmal mit Markdown formatiert, was im Terminal schwer zu lesen sein kann. Im nächsten Schritt verwenden wir die Entwickler-UI für eine viel umfangreichere, chatanwendungsähnliche Erfahrung.
7. Agent in der Entwickler-UI ausführen
Das Agent Development Kit bietet auch eine praktische Möglichkeit, Ihren Agenten über die Entwicklungsoberfläche als Chatanwendung zu starten. Verwenden Sie einfach den Befehl adk web anstelle von adk run..
Wenn Sie sich noch in der vorherigen Sitzung befinden, geben Sie einfach exit in das Terminal ein, um es zu schließen. Wenn die vorherige Sitzung geschlossen ist, geben Sie den folgenden Befehl in das Terminal ein:
uv run adk web
Im Terminal sollte eine ähnliche Ausgabe angezeigt werden:
... INFO: Started server process [4978] INFO: Waiting for application startup. +------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Sie haben zwei Möglichkeiten, auf die Entwickler-UI zuzugreifen:
- Über das Terminal öffnen
- Klicken Sie mit gedrückter Strg-Taste oder Befehlstaste auf die URLs (z.B.
http://localhost:8000) über das Terminal.
- Über die Webvorschau öffnen
- Klicken Sie auf die Schaltfläche Webvorschau.
- Wählen Sie Port ändern aus.
- Geben Sie die Portnummer ein (z.B. 8000)
- Klicken Sie auf Ändern und Vorschau.
Daraufhin wird die Chat-Anwendungsoberfläche in Ihrem Browser angezeigt. Über diese Benutzeroberfläche können Sie mit Ihrem persönlichen Assistenten chatten. Die Markdown-Formatierung wird jetzt korrekt angezeigt. Außerdem können Sie in dieser Benutzeroberfläche jedes Messaging-Ereignis, den Status des Kundenservicemitarbeiters, Nutzeranfragen und vieles mehr debuggen und untersuchen. Viele Grüße
8. Bereinigen
Da in diesem Codelab keine Produkte mit langer Laufzeit verwendet werden, reicht es aus, die aktiven Agentsitzungen (z.B. die adk web-Instanz in Ihrem Terminal) durch Drücken von Strg + C im Terminal zu beenden.
Ordner und Dateien des Agent-Projekts löschen
Wenn Sie den Code nur aus Ihrer Cloud Shell-Umgebung entfernen möchten, verwenden Sie die folgenden Befehle:
cd ~
rm -rf ai-agents-adk
Vertex AI API deaktivieren
Führen Sie den folgenden Befehl aus, um die zuvor aktivierte Vertex AI API zu deaktivieren:
gcloud services disable aiplatform.googleapis.com
Gesamtes Google Cloud-Projekt beenden
Wenn Sie Ihr Google Cloud-Projekt vollständig beenden möchten, finden Sie hier eine detaillierte Anleitung.
9. Fazit
Glückwunsch! Sie haben mit dem Agent Development Kit (ADK) erfolgreich einen einfachen persönlichen Assistenten-Agenten erstellt.
Wie Sie vielleicht schon bemerkt haben, ist dieser persönliche Assistent noch nicht sehr leistungsfähig. Er kann beispielsweise nicht auf das Internet zugreifen, um aktuelle Informationen zu erhalten. Im nächsten Codelab dieser Reihe zum Erstellen von KI-Assistenten mit dem ADK erfahren Sie, wie Sie Ihren persönlichen Assistenten-Agenten mit Funktionen und Tools ausstatten. Wir freuen uns auf Sie!