Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

KI‑Agents mit dem ADK erstellen: Die Grundlagen

1. Hinweis

Willkommen zum ersten Teil der Reihe „KI-Agenten mit ADK erstellen“! In dieser Codelab-Reihe mit Übungen erfahren Sie, wie Sie mit dem Agent Development Kit (ADK) von Google Ihren eigenen intelligenten KI-Agenten erstellen.

Wir beginnen mit den absoluten Grundlagen und zeigen Ihnen, wie Sie Ihre Entwicklungsumgebung einrichten und einen grundlegenden Konversations-Agenten erstellen. Am Ende dieses Codelabs haben Sie Ihre erste interaktive KI erstellt, die in den folgenden Teilen dieser Reihe zu einem komplexen Multi-Agenten-System (MAS) erweitert wird.

Sie können dieses Codelab entweder in Ihrer lokalen Umgebung oder in Google Cloud durcharbeiten. Für eine möglichst konsistente Nutzung 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. Dies ist nützlich, um Skripts, Konfigurationsdateien oder geklonte Repositories zu speichern.

Sie können auch über die verkürzte URL goo.gle/adk-foundation auf dieses Codelab zugreifen.

Voraussetzungen

Grundkenntnisse zu Konzepten der generativen KI
Grundlegende Kenntnisse der Python-Programmierung
Vertrautheit mit der Befehlszeile / dem Terminal und der gcloud-Befehlszeile
Grundlegende Kenntnisse von Python-Tools wie uv

Lerninhalte

Python-Umgebung einrichten
Einen einfachen persönlichen Assistenten-Agenten mit dem ADK erstellen
KI-Agenten ausführen, testen und Fehler beheben

Voraussetzungen

Einen funktionierenden Computer und eine zuverlässige WLAN-Verbindung
Ein Browser wie Chrome für den Zugriff auf die Google Cloud Console
Neugier und Lernbereitschaft

2. Einführung

Die Welt der generativen KI (GenAI) 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. Es kann seine digitale Umgebung wahrnehmen, Entscheidungen treffen und Maßnahmen ergreifen, um bestimmte Ziele ohne direkte menschliche Kontrolle zu erreichen. 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 sie Informationen aus verschiedenen Quellen wie Text, Bildern und Tönen verarbeiten. Der Agent nutzt dieses Verständnis dann, um einen Plan zu erstellen und eine Reihe von Aufgaben auszuführen, um ein vordefiniertes Ziel zu erreichen.

Dank gebrauchsfertiger Frameworks wie dem Agent Development Kit (ADK) können Sie jetzt ganz einfach eigene KI-Agenten erstellen, auch ohne umfassende Fachkenntnisse. Sie beginnen damit, einen persönlichen Assistenten-Agent zu erstellen, der Sie bei Ihren Aufgaben unterstützt. Fangen wir an!

3. Google Cloud-Projekt erstellen (optional)

Erstellen Sie zuerst ein neues Google Cloud-Projekt, damit die Aktivitäten aus diesem Codelab nur in diesem neuen Projekt ausgeführt werden.

Rufen Sie console.cloud.google.com/projectcreate auf.
Geben Sie die erforderlichen Informationen ein:

Projektname: Sie können einen beliebigen Namen eingeben, z. B. „genai-workshop“.
Standort: Lassen Sie das Feld auf Keine Organisation.
Rechnungskonto: Wenn diese Option angezeigt wird, wählen Sie Google Cloud Platform-Testrechnungskonto aus. Keine Sorge, wenn diese Option nicht angezeigt wird. Fahren Sie einfach mit dem nächsten Schritt fort.

Kopieren Sie die generierte Projekt-ID. Sie benötigen sie später.

Wenn alles in Ordnung ist, klicken Sie auf die Schaltfläche Erstellen.

4. Umgebung einrichten

In diesem Abschnitt richten Sie Ihre Entwicklungsumgebung ein, indem Sie ein Projektverzeichnis erstellen, die erforderlichen APIs aktivieren, eine virtuelle Python-Umgebung einrichten und die erforderlichen Pakete installieren.

Cloud Shell konfigurieren

Nachdem Ihr Projekt erfolgreich erstellt wurde, führen Sie die folgenden Schritte aus, um Cloud Shell einzurichten.

Schritt 1: Cloud Shell starten

Rufen Sie shell.cloud.google.com auf. Wenn Sie ein Pop-up-Fenster sehen, in dem Sie aufgefordert werden, die Autorisierung zu bestätigen, klicken Sie auf Autorisieren.

Schritt 2: Projekt-ID festlegen

Führen Sie den folgenden Befehl im Cloud Shell-Terminal aus, um die richtige Projekt-ID festzulegen. Ersetzen Sie <your-project-id> durch Ihre tatsächliche Projekt-ID, die Sie im Schritt zur Projekterstellung oben kopiert haben.

gcloud config set project <your-project-id>

Im Cloud Shell-Terminal sollte nun das richtige Projekt ausgewählt sein. Die ausgewählte Projekt-ID ist gelb hervorgehoben.

Schritt 3: Erforderliche APIs aktivieren

Wenn Sie Google Cloud-Dienste verwenden möchten, müssen Sie zuerst die entsprechenden APIs für Ihr Projekt aktivieren. Führen Sie die folgenden Befehle im Cloud Shell-Terminal aus, um die Dienste für dieses Codelab zu aktivieren:

gcloud services enable aiplatform.googleapis.com

Wenn der Vorgang erfolgreich war, wird Operation/... finished successfully im Terminal angezeigt.

Virtuelle Python-Umgebung erstellen

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.

Schritt 1: Erstellen Sie ein Projektverzeichnis und rufen Sie es auf:

mkdir -p ai-agents-adk
cd ai-agents-adk

Schritt 2: Erstellen und aktivieren Sie eine virtuelle Umgebung:

uv venv --python 3.12
source .venv/bin/activate

Vor der Terminal-Eingabeaufforderung wird (ai-agents-adk) angezeigt, was darauf hinweist, dass die virtuelle Umgebung aktiv ist.

Schritt 3: Seite „ADK installieren“

uv pip install --no-cache google-adk

5. Agent erstellen

Nachdem Sie Ihre Umgebung eingerichtet haben, können Sie mit der Erstellung der Grundlage für Ihren KI-Agenten beginnen. Für das ADK sind einige Dateien erforderlich, um die Logik und Konfiguration Ihres KI-Agenten zu definieren:

agent.py: Enthält den primären Python-Code Ihres KI-Agenten, der seinen Namen, das verwendete LLM und die wichtigsten Anweisungen definiert.
__init__.py: Markiert das Verzeichnis als Python-Paket, damit das ADK Ihre Agentendefinition erkennen und laden kann.
.env: Speichert vertrauliche Informationen und Konfigurationsvariablen wie API-Schlüssel, Projekt-ID und Standort.

Mit diesem Befehl wird ein neues Verzeichnis mit dem Namen personal_assistant erstellt, das die drei wichtigen Dateien enthält.

adk create personal_assistant

Nachdem der Befehl ausgeführt wurde, werden Sie aufgefordert, einige Optionen zur Konfiguration Ihres Agenten auszuwählen.

Wählen Sie für den ersten Schritt Option 1 aus, um das gemini-3.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-3.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

Wählen Sie für den zweiten Schritt Gemini Enterprise Agent Platform (Option 2) als Backend-Dienstanbieter aus. Das ist die leistungsstarke, verwaltete KI-Plattform von Google Cloud.

1. Google AI
2. Gemini Enterprise Agent Platform
3. Login with Google
Choose a backend (1, 2, 3): 2

Prüfen Sie dann, ob die in den Klammern [...] angezeigte Projekt-ID korrekt ist. Wenn das der Fall ist, drücken Sie die Eingabetaste. Wenn nicht, geben Sie die richtige Projekt-ID im folgenden Prompt ein:

Enter Google Cloud project ID [your-project-id]:

Drücken Sie schließlich die Eingabetaste bei der nächsten Frage, um global als Region für dieses Codelab zu verwenden.

Enter Google Cloud region [us-central1]: global

Die Ausgabe sollte in etwa so aussehen:

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. Agent-Codes ansehen

Öffnen Sie den Ordner ai-agents-adk im Cloud Shell-Editor, um die erstellten Dateien anzusehen.

Klicken Sie oben im Menü auf Datei > Ordner öffnen….
Suchen Sie den Ordner ai-agents-adk und wählen Sie ihn aus.
Klicken Sie auf OK.

Wenn die obere Menüleiste nicht angezeigt wird, können Sie auch auf das Ordnersymbol klicken und Ordner öffnen auswählen.

Wenn 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).

Die Datei .env ist oft standardmäßig ausgeblendet. So machen Sie sie im Cloud Shell-Editor sichtbar:

Klicken Sie oben auf die Menüleiste.
Klicken Sie auf Ansehen.
Wählen Sie Versteckte Dateien einblenden aus.

Sehen Sie sich den Inhalt der einzelnen Dateien an.

agent.py

In dieser Datei wird Ihr Agent mithilfe der Klasse Agent aus der Bibliothek google.adk.agents instanziiert.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-3.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 erforderliche Klasse Agent aus der ADK-Bibliothek importiert.
root_agent = Agent(...): Hier erstellen Sie eine Instanz Ihres KI-Agenten.
name="root_agent": Eine eindeutige Kennung für Ihren Agenten. So erkennt und bezeichnet das ADK Ihren KI-Agenten.
model="gemini-3.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-3.5-flash ist ein schnelles und effizientes Modell, das sich für konversationelle Aufgaben eignet.
description="...": Hier finden Sie eine kurze Zusammenfassung des Zwecks oder der Fähigkeiten des KI-Agenten. Die Beschreibung ist eher für das menschliche Verständnis oder für andere KI-Agents in einem Multi-Agenten-System gedacht, damit sie verstehen, was dieser bestimmte Agent tut. Sie wird häufig für das Logging, Debugging oder zum Anzeigen von Informationen über den Agenten verwendet.
instruction="...": Dies ist der Systemprompt, der das Verhalten Ihres KI-Agenten steuert und seine Persönlichkeit definiert. Sie teilt dem LLM mit, wie es sich verhalten soll und was sein primärer Zweck ist. In diesem Fall wird der Agent als „hilfreicher Assistent“ festgelegt. Diese Anweisung ist entscheidend, um den Konversationsstil und die Fähigkeiten des KI-Agenten zu bestimmen.

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 namens agent (das agent.py entspricht) zu suchen. Diese einfache Zeile sorgt dafür, dass das ADK beim Laden Ihres personal-assistant-Agents die in agent.py definierte root_agent finden und initialisieren kann. Auch wenn sie leer ist, macht das Vorhandensein von __init__.py das Verzeichnis zu einem Python-Paket.

.env

Diese Datei enthält umgebungsspezifische Konfigurationen und vertrauliche Anmeldedaten.

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

GOOGLE_GENAI_USE_ENTERPRISE: Damit wird dem ADK mitgeteilt, dass Sie den Dienst „Gemini Enterprise Agent Platform“ von Google für Ihre generativen KI-Vorgänge verwenden möchten. Das 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 KI-Agenten richtig mit Ihren Cloud-Ressourcen zu verknüpfen und die Abrechnung zu ermöglichen.
GOOGLE_CLOUD_LOCATION: Damit wird der Google Cloud-Standort für Modellanfragen angegeben, z.B. global. Wenn Sie den richtigen Standort verwenden, kann Ihr Agent effektiv mit den Diensten der Gemini Enterprise Agent Platform kommunizieren.

7. Agent im Terminal ausführen

Wenn alle drei Dateien vorhanden sind, können Sie den Agenten direkt über das Terminal ausführen. Führen Sie dazu den folgenden adk run-Befehl im Terminal aus:

adk run personal_assistant

Wenn alles richtig eingerichtet ist, sehen Sie eine ähnliche Ausgabe im Terminal. Ignorieren Sie die Warnungen vorerst. Solange Sie [user]: sehen, können Sie fortfahren.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Legen Sie sofort mit der Unterhaltung los. Geben Sie z. B. „Hallo“ ein. Was kannst du für mich tun?“ und Sie sollten eine Antwort erhalten.

...
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:
...

Die Ausgabe ist manchmal mit Markdown formatiert, was im Terminal schwer zu lesen sein kann. Im nächsten Schritt verwenden Sie die Entwickler-UI, die eine viel umfassendere, chatanwendungsähnliche Umgebung bietet.

Fehlerbehebung

Für diese API-Methode muss die Abrechnung aktiviert werden.

Wenn Sie die Meldung {‘message': ‘This API method requires billing to be enabled'} erhalten, gehen Sie so vor:

Prüfen Sie, ob Sie die richtige Projekt-ID in der Datei .env verwenden.
Rufen Sie die Seite Verknüpftes Rechnungskonto auf und prüfen Sie, ob das Rechnungskonto bereits verknüpft ist.
Wählen Sie andernfalls die Option Google Cloud Platform-Testrechnungskonto aus.

Die Gemini Enterprise Agent Platform API wurde im Projekt nicht verwendet.

Wenn Sie eine Fehlermeldung mit {'message': 'API has not been used in project...'} erhalten, aktivieren Sie die Gemini Enterprise Agent Platform API, indem Sie Folgendes in das Terminal eingeben:

gcloud services enable aiplatform.googleapis.com

Wenn der Vorgang erfolgreich war, wird Operation/... finished successfully im Terminal angezeigt.

Andere Fehler

Wenn Sie andere Fehler erhalten, die oben nicht erwähnt werden, versuchen Sie, den Tab Cloud Shell im Browser neu zu laden und die Autorisierung noch einmal zu bestätigen, falls Sie dazu aufgefordert werden.

8. KI‑Agenten über die Entwicklungs-Web-UI ausführen

Das Agent Development Kit bietet auch eine praktische Möglichkeit, Ihren Agenten über die Entwicklungs-Benutzeroberfläche als Chatanwendung zu starten. Verwenden Sie einfach den Befehl adk web anstelle von adk run..

Wenn in Ihrem Terminal noch adk run ausgeführt wird, geben Sie „exit“ ein, um es zu schließen, bevor Sie den Befehl eingeben.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Im Terminal sollte eine Ausgabe ähnlich der folgenden 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:

Direkt über das Terminal:Klicken Sie mit Strg + Klick (oder Cmd + Klick) auf den bereitgestellten Link, z. B. http://localhost:8000.
Webvorschau verwenden:

Klicken Sie auf den Button 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ähnliche Benutzeroberfläche in Ihrem Browser angezeigt. Chatten Sie einfach über diese Oberfläche mit Ihrem persönlichen Assistenten.

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. Viel Spaß beim Chatten!

9. Bereinigen (optional)

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 oder Cmd + C im Terminal zu beenden.

Ordner und Dateien von Agent-Projekten löschen

Wenn Sie nur den Code aus Ihrer Cloud Shell-Umgebung entfernen möchten, verwenden Sie die folgenden Befehle:

cd ~
rm -rf ai-agents-adk

Gemini Enterprise Agent Platform API deaktivieren

Führen Sie den folgenden Befehl aus, um die zuvor aktivierte API zu deaktivieren:

gcloud services disable aiplatform.googleapis.com

Gesamtes Google Cloud-Projekt beenden

Wenn Sie Ihr Google Cloud-Projekt vollständig herunterfahren möchten, folgen Sie der offiziellen Anleitung.

10. Fazit

Glückwunsch! Sie haben mit dem Agent Development Kit (ADK) erfolgreich einen einfachen persönlichen Assistenten erstellt. Sie haben nun ein solides Fundament und Verständnis der Kernkomponenten eines ADK-Agenten.

Als Nächstes können Sie die Fähigkeiten Ihres KI-Agenten erheblich erweitern, indem Sie ihm Tools zur Verfügung stellen, mit denen er auf Echtzeitinformationen zugreifen und mit externen Diensten interagieren kann. Wenn Sie fortfahren möchten, finden Sie im nächsten Codelab dieser Reihe, KI-Agenten mit ADK erstellen: Tools hinzufügen, eine Anleitung dazu.

Außerdem können Sie an unserem Flaggschiffprogramm GEAR (Gemini Enterprise Agent Ready) teilnehmen, um Zugang zu wertvollen Lernmaterialien zu erhalten. Sie können auch am Get Certified-Programm teilnehmen, einem strukturierten, von Experten geleiteten, praxisorientierten Schulungsprogramm.