Diese Seite wurde von der Cloud Translation API übersetzt.

KI‑Agents mit dem ADK erstellen: Die Grundlagen

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 Agenten. 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 der generativen 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
Neugier und Lernbereitschaft

Testrechnungskonto einlösen

Für dieses Codelab benötigen Sie außerdem ein aktives Google Cloud-Rechnungskonto. Wenn Sie noch kein Testrechnungskonto haben, gehen Sie so vor, um es einzulösen:

Öffnen Sie in Ihrem Browser ein Inkognitofenster.
Rufen Sie dieses Einlöseportal auf.
Melden Sie sich mit Ihrem privaten Gmail-Konto an.
Folgen Sie der Schritt-für-Schritt-Anleitung im Portal.

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

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 konfigurieren

Google Cloud-Projekt erstellen

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 die Einstellung 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, da Sie sie später benötigen.

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

Cloud Shell konfigurieren

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

1. Cloud Shell aufrufen

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

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 wird gelb hervorgehoben.

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.

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.

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

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

2. Erstellen und aktivieren Sie eine virtuelle Umgebung:

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

Der Eingabeaufforderung des Terminals wird das Präfix (ai-agents-adk) vorangestellt, was darauf hinweist, dass die virtuelle Umgebung aktiv ist.

3. ADK-Installationsseite

uv pip install 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 Agents zu definieren:

agent.py: Enthält den primären Python-Code Ihres Agents, in dem sein Name, das verwendete LLM und die wichtigsten Anweisungen definiert werden.
__init__.py: Markiert das Verzeichnis als Python-Paket, damit das ADK Ihre Agent-Definition 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 namens 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 zum Konfigurieren 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

Prüfen Sie dann, ob die in den eckigen Klammern [...] angezeigte Projekt-ID richtig eingestellt ist. Wenn ja, drücken Sie die Eingabetaste. Wenn nicht, geben Sie die richtige Projekt-ID in der folgenden Aufforderung ein:

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

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

Enter Google Cloud region [us-central1]:

Im Terminal sollte eine ähnliche Ausgabe angezeigt werden.

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

6. Agent-Codes ansehen

Wenn Sie die erstellten Dateien ansehen möchten, öffnen Sie den Ordner ai-agents-adk im Cloud Shell-Editor.

Klicken Sie im oberen 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.

Sobald das Editorfenster vollständig geladen ist, rufen Sie den Ordner personal-assistant auf. Die oben genannten erforderlichen Dateien (agent.py, __init__.py und .env) werden angezeigt.

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

Klicken Sie oben in der Menüleiste
Klicken Sie auf Ansehen.
Wählen Sie Ausgeblendete Dateien ein-/ausblenden aus.

Sehen Sie sich 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 erforderliche Agent-Klasse aus der ADK-Bibliothek importiert.
root_agent = Agent(...): Hier erstellen Sie eine Instanz Ihres KI‑Agents.
name="root_agent": Eine eindeutige Kennung für Ihren Agent. So erkennt und bezeichnet das ADK Ihren KI-Agenten.
model="gemini-2.5-flash": Dieser wichtige Parameter gibt an, welches Large Language Model (LLM) Ihr Agent als zugrunde liegendes „Gehirn“ zum Verstehen, Schlussfolgern und Generieren von Antworten verwendet. gemini-2.5-flash ist 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 KI-Agenten 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 für die Gestaltung des Konversationsstils und der Fähigkeiten des Agenten.

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 es 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_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.

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 in Ihrem Terminal. Ignorieren Sie die Warnungen vorerst. Solange Sie [user]: sehen, können Sie fortfahren.

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

Chatten Sie mit dem Kundenservicemitarbeiter. Geben Sie etwas wie „Hallo. 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 wir die Entwickler-UI für eine viel umfangreichere, chatanwendungsähnliche Erfahrung.

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

Vertex AI API wurde im Projekt nicht verwendet

Wenn Sie eine Fehlermeldung mit {'message': 'Vertex AI API has not been used in project...'} erhalten, aktivieren Sie die Vertex AI 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. Agent in der Entwicklungs-Web-UI ausführen

Das Agent Development Kit bietet auch eine praktische Möglichkeit, Ihren Agent über die Entwicklungsoberflä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 diesen Befehl eingeben:

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

Strg + Klicken oder Befehlstaste + Klicken auf den Link (z.B. http://localhost:8000), wie im Terminal angezeigt.

Ü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 Oberflä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

9. Bereinigen (optional)

Da in diesem Codelab keine Produkte mit langer Laufzeit verwendet werden, reicht es aus, die aktiven Agent-Sitzungen (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 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.

10. Fazit

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

Als Nächstes können Sie die Funktionen Ihres Agents erheblich erweitern, indem Sie ihm Tools geben, 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-Agents mit ADK erstellen: Tools nutzen, eine Anleitung dazu.