1. Einführung
In diesem Codelab erstellen Sie mit dem Agent Development Kit (ADK) von Google und Gemini Schritt für Schritt Ihren ersten KI-Agenten. Sie erstellen einen einfachen Agenten zum Schreiben von Blogbeiträgen, der Inhalte plant und schreibt. Dabei werden die grundlegenden Konzepte von Reasoning und Acting vorgestellt.
Aufgaben
- Richten Sie Ihre Entwicklungsumgebung für das ADK ein.
- Multi-Agenten-System mit einem Planner und einem Writer erstellen
- Führen Sie den KI-Agenten lokal aus und interagieren Sie über die ADK-Webbenutzeroberfläche mit ihm.
Voraussetzungen
- Ein Webbrowser wie Chrome.
- Python 3.10 oder höher ist auf Ihrem Computer installiert.
- Einen Google AI Studio API-Schlüssel.
Dieses Codelab richtet sich an Entwickler aller Erfahrungsstufen, auch an Anfänger.
Geschätzte Dauer: 30 Minuten.
2. Visueller Leitfaden: Was sind KI-Agents?
Bevor wir mit der Entwicklung beginnen, wollen wir uns kurz ansehen, was KI-Agenten sind und welchen gängigen Mustern sie folgen.
Was ist ein KI-Agent?
Im einfachsten Fall ist ein Agent eine Software, die nicht nur Antworten liefert, sondern auch Entscheidungen treffen und Maßnahmen ergreifen kann. Anstatt wie ein herkömmlicher Chatbot eine einzelne Antwort zu generieren, wird Ihre Anfrage analysiert, um herauszufinden, welche Schritte erforderlich sind. Möglicherweise wird eine API aufgerufen, Code ausgeführt und das Ergebnis analysiert, um dann zu entscheiden, was als Nächstes zu tun ist.
Eine der klarsten Erklärungen stammt aus dem Forschungsartikel ReAct: Synergizing Reasoning and Acting in Language Models. Die Idee in diesem Paper war einfach, aber leistungsstark: Sprachmodelle sollten nicht nur Text in einem Durchgang generieren. Sie können tatsächlich Schritt für Schritt argumentieren, eine Aktion ausführen, z. B. ein Tool oder eine API aufrufen, das Ergebnis beobachten und dann entscheiden, was als Nächstes zu tun ist.
Dieser Zyklus aus Denken, Handeln, Beobachten und Anpassen ist die Grundlage für die Funktionsweise moderner KI-Agents. Das entspricht der Definition von Google Cloud: Systeme mit Denkvermögen, Planung und Gedächtnis, die autonom genug sind, um sich anzupassen und Entscheidungen im Namen des Nutzers zu treffen.
Drei Muster für das Verhalten von KI-Agenten
Nicht alle Kundenservicemitarbeiter verhalten sich gleich. Sie lassen sich in drei große Muster unterteilen:
- Sequenzielle Agents: Diese werden Schritt für Schritt wie ein Fließband ausgeführt: Schritt 1, dann Schritt 2, dann Schritt 3. Sie sind vorhersehbar, aber starr.
- Reaktive KI-Agenten: Diese treffen Entscheidungen im Moment. Sie sehen sich den aktuellen Zustand an und fragen: „Was soll ich als Nächstes tun?“ Vielleicht Tool A einmal und Tool B beim nächsten Mal. Sie sind flexibel, planen aber nicht voraus.
- Überlegte oder planende Agents: Diese halten inne, um einen Plan zu entwerfen, und führen ihn dann aus. Wenn Sie eine Reise buchen, kaufen Sie nicht einfach einen Flug, sondern wählen Daten und Hotels aus, legen die einzelnen Schritte fest und führen sie dann aus.
Welcher Ansatz ist der „richtige“? Das hängt vom Problem ab. Bei einfachen, vorhersehbaren Abläufen ist sequenziell in Ordnung. Bei dynamischen Aufgaben ist reaktiv besser. Bei mehrstufigen Zielvorhaben mit Abhängigkeiten sind Planungs-Agents sinnvoll.
In diesem Lab erstellen wir einen Deliberative/Planning-Agent, der zuerst einen Überblick erstellt und dann den Blogbeitrag schreibt.
3. Hinweis
Google Cloud-Konto und -Projekt erstellen
Wenn Sie Ihren Agenten später in diesem Lab in Google Cloud Run bereitstellen möchten, benötigen Sie ein Google Cloud-Konto und ein Projekt, für das die Abrechnung aktiviert ist.
- Melden Sie sich in der Google Cloud Console an. Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes. Wenn Sie noch kein Google-Konto haben, müssen Sie eines erstellen.
- Als Nächstes müssen Sie die Abrechnung in der Cloud Console aktivieren, um Cloud-Ressourcen verwenden zu können. Die Kosten für dieses Codelab sollten nur wenige Cent betragen. Neue Google Cloud-Nutzer haben möglicherweise auch Anspruch auf das kostenlose Testprogramm mit einem Guthaben von 300 $.
- Notieren Sie sich Ihre Projekt-ID (ein eindeutiger Name für alle Google Cloud-Projekte). Sie benötigen diese, um den Agent zu konfigurieren und bereitzustellen.
Google AI Studio-API-Schlüssel abrufen
Wenn Sie Gemini-Modelle verwenden möchten, benötigen Sie einen API-Schlüssel von Google AI Studio.
- Rufen Sie Google AI Studio auf.
- Klicken Sie auf API-Schlüssel abrufen.
- Erstellen Sie einen neuen Schlüssel oder verwenden Sie einen vorhandenen. Kopieren Sie den Schlüssel zur späteren Verwendung.
4. Projektstruktur für den Blog Writer-KI-Agenten erstellen
In diesem Schritt richten Sie das Verzeichnis und die Dateien ein, in denen der Code Ihres Blog-Schreibagenten auf Ihrem lokalen Computer gespeichert werden soll.
1. Arbeitsbereich für den KI‑Agenten zum Schreiben von Blogbeiträgen erstellen
Öffnen Sie das Terminal und führen Sie die folgenden Befehle aus, um ein eigenes Verzeichnis für Ihren Blog-Writer-Agent zu erstellen und dorthin zu wechseln:
mkdir bloggeragent
cd bloggeragent
2. Agent-Dateien initialisieren
Das Google ADK-Framework lädt Agent-Workflows direkt aus Ihrem Projektverzeichnis. Erstellen Sie die erforderlichen Dateien direkt im Stammverzeichnis von bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Abhängigkeiten installieren und Umgebung einrichten
In diesem Schritt richten Sie eine virtuelle Python-Umgebung ein, installieren das Google ADK-Framework und konfigurieren Umgebungsvariablen, um Ihren Blog-Agenten beim Gemini-Modell zu authentifizieren.
1. Agent-Anforderungen konfigurieren
Öffnen Sie die Datei requirements.txt im Verzeichnis bloggeragent und geben Sie die für den Blog-Schreib-Agent erforderlichen Pakete an, indem Sie Folgendes hinzufügen:
google-adk==2.2.0
python-dotenv
2. Virtuelle Umgebung für den Agenten erstellen
Erstellen und aktivieren Sie im Verzeichnis bloggeragent eine virtuelle Python-Umgebung, um die Pakete des KI-Agenten zu isolieren:
python3 -m venv .venv
source .venv/bin/activate
3. ADK-Framework installieren
Installieren Sie die in Ihrem requirements.txt definierten Abhängigkeiten, um Ihren lokalen Arbeitsbereich mit dem Google ADK auszustatten:
pip install -r requirements.txt
4. Anmeldedaten für die Agent API konfigurieren
Öffnen Sie die .env-Datei, die Sie im Stammverzeichnis des Projekts erstellt haben, und fügen Sie Ihren Gemini API-Schlüssel hinzu:
GOOGLE_API_KEY=your_api_key
Ersetzen Sie your_api_key durch den Schlüssel, den Sie aus Google AI Studio kopiert haben.
6. Multi-Agenten-Blog-Writer erstellen
In diesem Schritt implementieren Sie den Hauptworkflow Ihres Agentensystems zum Schreiben von Blogbeiträgen.
Anstelle eines einfachen Chatbots mit einem einzelnen Prompt erstellen Sie ein komplexes Multi-Agenten-System, das selbstkorrigierende Schleifen und die Überprüfung von Gliederungen verwendet, um hochwertige technische Beiträge zu schreiben. Dies entspricht dem Deliberative/Planning-Muster, das wir bereits besprochen haben.
Überblick über die Architektur
So interagieren die Spezialisten in Ihrem System:
init.py konfigurieren
Öffnen Sie __init__.py in Ihrem Texteditor und fügen Sie den folgenden Import hinzu, um den Agent-Workflow für den Runner verfügbar zu machen:
from . import agent
Workflow für den KI-Agenten zum Schreiben von Blogbeiträgen erstellen
Öffnen Sie agent.py in Ihrem Code-Editor und fügen Sie den folgenden Code hinzu, der den Planner, Writer, Validation Checkers und den Haupt-Blogger-Agent definiert:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Agentenarchitektur
Sehen wir uns die Hauptkomponenten des Codes an, den Sie gerade in agent.py hinzugefügt haben, um zu verstehen, wie der Workflow für die Planung und das Schreiben mit mehreren KI-Agenten implementiert wird:
1. Der BlogPlanner-Unteragent
Der blog_planner-Agent ist für die Inhaltsplanung zuständig. Er nimmt das vom Nutzer angegebene Thema auf und erstellt einen strukturierten Überblick in Markdown (mit Titel, Einleitung, 4–6 Abschnitten und einer Zusammenfassung). Der Überblick wird im gemeinsamen Zustands-Dictionary unter dem Schlüssel "blog_outline" gespeichert.
2. OutlineValidationChecker
Der OutlineValidationChecker-Agent fungiert als Qualitätssicherung. Es überprüft die generierten "blog_outline" im Status. Wenn der Entwurf gültig ist, wird mit "ok" geantwortet. Andernfalls wird "retry" zusammen mit einer Liste der fehlenden Elemente zurückgegeben.
3. Der RobustBlogPlanner-Loop
Damit der Agent keine schlechten Zusammenfassungen erstellt, umschließen wir den Planner und den Validation Checker mit einem LoopAgent namens robust_blog_planner. Wenn die Validierung fehlschlägt und "retry" zurückgegeben wird, wird der Planer automatisch bis zu dreimal ausgeführt, um eine Selbstkorrektur zu ermöglichen, bevor mit der nächsten Phase fortgefahren wird.
4. Der BlogWriter-Sub-Agent
Sobald die Gliederung fertig ist, liest der blog_writer-Agent "blog_outline" aus dem Status und generiert den vollständigen technischen Artikel in Markdown. Dabei wird die Struktur der Gliederung beibehalten und der Artikel wird auf Softwareentwickler zugeschnitten.
5. BlogPostValidationChecker und RobustBlogWriter-Schleife
Wie die Gliederung wird auch der endgültige Artikel von BlogPostValidationChecker validiert, um sicherzustellen, dass alle wichtigen Abschnitte vorhanden und klar formuliert sind. Der Autor und der Prüfer sind in der robust_blog_writer-Schleife enthalten, sodass der Artikel bis zu dreimal selbstkorrigiert werden kann, wenn der Prüfer Probleme findet.
6. Schleifen als Tools verfügbar machen
Wir umschließen die Planer-Schleife (robust_blog_planner) und die Writer-Schleife (robust_blog_writer) als Tools (planner_tool und writer_tool) mit AgentTool. So können andere Agenten diese komplexen Workflows aufrufen, als wären es einfache Tools.
7. Der Blogger-Root-Agent
Der root_agent (mit dem Namen Blogger) orchestriert den gesamten Workflow. Wenn ein Thema angegeben wird, wird GenAI durch die Anweisungen dazu angeleitet,
- Rufen Sie
planner_toolauf, um den validierten Abriss zu generieren. - Rufen Sie
writer_toolauf, um den Entwurf auf Grundlage dieses Konzepts zu erstellen. - Erstelle zum Schluss drei alternative Titel und zwei Tweet-Hooks.
Diese Multi-Agent-Loop-Architektur sorgt für Zuverlässigkeit, da LLM-Formatierungs- oder Strukturfehler erkannt und korrigiert werden, bevor die Ausgabe dem Nutzer angezeigt wird.
7. Agent ausführen und testen
Jetzt ist es an der Zeit, Ihren Agenten in Aktion zu sehen.
1. ADK-Web-UI starten
Achten Sie darauf, dass Sie sich im Terminal im bloggeragent-Projektstammverzeichnis befinden und Ihre virtuelle Umgebung aktiv ist (source .venv/bin/activate). Starten Sie dann die Weboberfläche:
adk web
2. Mit dem Agent interagieren
- Öffnen Sie Ihren Browser und rufen Sie
http://127.0.0.1:8000(oder den von Ihnen angegebenen Port) auf. - Sie sollten die ADK-Webbenutzeroberfläche mit dem geladenen
Blogger-Agenten und seinem visuellen Layout sehen (der Blogger-Root-Agent verweist auf die Tools „RobustBlogPlanner“ und „RobustBlogWriter“):
- Geben Sie ein technisches Thema in das Nachrichtenfeld ein und drücken Sie die Eingabetaste. Hier sind einige interessante Test-Prompts, mit denen Sie Ihren Agenten bewerten können:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Sehen Sie sich den Ausführungs-Trace in der Benutzeroberfläche an. Sie sehen, wie
BlogPlannerden Entwurf erstellt,OutlineValidationCheckerihn validiert undBlogWriterden endgültigen Entwurf auf Grundlage des Entwurfs schreibt:
8. In Cloud Run bereitstellen
Nachdem Sie überprüft haben, dass der Agent lokal funktioniert, stellen wir ihn in Google Cloud Run bereit, damit andere ihn verwenden können.
Google Cloud Run ist eine verwaltete Computing-Plattform, mit der Sie zustandslose Container ausführen können, die sich über Webanfragen oder Pub/Sub-Ereignisse aufrufen lassen.
1. Voraussetzungen für die Bereitstellung
Wenn Sie den Blog-Schreibagent in Cloud Run bereitstellen möchten, müssen Sie die Google Cloud CLI (gcloud) auf Ihrem lokalen Computer installieren und authentifizieren:
- Google Cloud CLI installieren: Wenn Sie die Google Cloud CLI noch nicht installiert haben, folgen Sie der Installationsanleitung für die Google Cloud CLI für Ihr Betriebssystem (macOS, Windows oder Linux).
- Lokales Terminal authentifizieren: Führen Sie nach der Installation den folgenden Befehl in Ihrem Terminal aus, um sich in Ihrem Google Cloud-Konto anzumelden:
gcloud auth login - Authentifizierung überprüfen: Prüfen Sie, ob Sie sich erfolgreich in Ihrem Konto angemeldet haben und auf Ihre Google Cloud-Ressourcen zugreifen können:
gcloud auth list
2. Google Cloud-Projekt einrichten
Legen Sie Ihr aktives Projekt im Terminal fest:
gcloud config set project <YOUR_PROJECT_ID>
Aktivieren Sie die erforderlichen Google Cloud-Dienste, die zum Erstellen und Bereitstellen Ihres containerisierten Agents erforderlich sind:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Da mit dem ADK-Bereitstellungsbefehl Google Cloud Build verwendet wird, um den Build-Prozess zu automatisieren, müssen Sie dem Standard-Compute-Dienstkonto die Berechtigung zur Verwendung von Cloud Build gewähren.
Sie können Ihre Projektnummer ermitteln, indem Sie Folgendes ausführen:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Führen Sie die folgenden Befehle aus, um die erforderlichen IAM-Rollen zu binden. Ersetzen Sie
- Gewähren Sie Cloud Build die Berechtigung, Ihren Container zu erstellen:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Gewähren Sie die Berechtigung für den Zugriff auf Gemini Enterprise, damit der bereitgestellte Agent Gemini-Modelle ohne API-Schlüssel aufrufen kann:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Lokale Umgebungsvariablen einrichten
Um den Bereitstellungsbefehl zu vereinfachen und Tippfehler zu vermeiden, legen Sie Ihre Projekt-ID als Umgebungsvariable in Ihrer Terminalsitzung fest:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Mit der ADK-CLI bereitstellen
Die ADK CLI bietet einen optimierten Befehl zum Bereitstellen Ihres Agents in Cloud Run.
Achten Sie darauf, dass Ihre virtuelle Umgebung aktiv ist und Sie sich im Projektverzeichnis bloggeragent befinden. Führen Sie dann den Bereitstellungsbefehl aus:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Während der Bereitstellung werden Sie im Terminal aufgefordert, die folgenden beiden Fragen zu beantworten:
- Repository-Erstellung bestätigen:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yein und drücken Sie die Eingabetaste. - Nicht authentifizierten Zugriff zulassen:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yein und drücken Sie die Eingabetaste. So können Sie öffentlich in Ihrem Browser auf die ADK Web-UI zugreifen.
5. Auf den bereitgestellten Agenten zugreifen
Nach Abschluss der Bereitstellung gibt der Befehl eine URL aus. Öffnen Sie diese URL in Ihrem Browser, um auf Ihre öffentliche ADK-Web-UI zuzugreifen.
9. Bereinigen
Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.
1. Cloud Run-Dienst löschen
Löschen Sie den bereitgestellten bloggeragent-Dienst:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Artifact Registry-Repository löschen
Löschen Sie das Docker-Repository, das zum Speichern der erstellten Container-Images erstellt wurde:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Lokalen Server beenden
Drücken Sie CTRL+C im Terminal, in dem der lokale ADK-Server ausgeführt wird, um ihn zu beenden, und deaktivieren Sie die virtuelle Umgebung:
deactivate
10. Glückwunsch
Glückwunsch! Sie haben Ihren ersten KI-Agenten mit dem ADK von Google und Gemini erstellt.
Das haben Sie gelernt
- Die wichtigsten Konzepte von KI-Agenten (Reasoning und Acting).
- Wie Sie mit dem Google ADK ein Multi-Agenten-System erstellen.
- So führen Sie Ihren Agenten über die Web-UI aus und testen ihn.
Nächste Schritte
- Fügen Sie Ihrem Agenten Tools hinzu, z. B. die Websuche oder API-Aufrufe.
- Im zweiten Video zeigen wir, wie ein MCP-Server integriert wird.