ADK: Von den Grundlagen bis hin zu Multi-Tool-Agents

1. Einführung

Dieses Codelab bietet eine umfassende Einführung in die Entwicklung von Agenten mit dem ADK. Es beginnt mit den Grundlagen und geht dann zur Entwicklung von Multi-Tool-Agenten über.

Ein KI-Agent ist ein Softwaresystem, das ein Large Language Model (LLM) als „Reasoning Engine“ verwendet, um ein Ziel zu erreichen, indem es autonom eine Reihe von Aufgaben ausführt.

Ein LLM ist ein leistungsstarker Berater, der Ihnen Ratschläge geben kann. Ein KI-Agent ist ein proaktiver Entwickler, der Tools verwenden kann, um diese Ratschläge umzusetzen.

LLM im Vergleich zu Agents

Das Brain (LLM): Bietet Problemlösungs-, Planungs- und Natural Language Understanding-Funktionen. Es wird entschieden, was zu tun ist.

Die Hände (Tools): Das sind die APIs, SDKs und benutzerdefinierten Funktionen, die es dem Agenten ermöglichen, mit der realen Welt zu interagieren. Er führt den Plan aus.

Das Agent Development Kit (ADK)

Das Agent Development Kit (ADK) ist ein spezielles Framework, das die Erstellung, Bereitstellung und Orchestrierung von KI-Agenten vereinfacht. Sie bietet die standardisierten Bausteine, die erforderlich sind, um ein statisches Large Language Model in einen dynamischen Agenten zu verwandeln, der Code ausführen, APIs aufrufen und mehrstufige Workflows verwalten kann.

Ein Multi-Tool-Agent ist ein Orchestrator, der verschiedene spezialisierte Funktionen wie eine Suchmaschine, eine Datenbank und einen Taschenrechner auswählen und in eine bestimmte Reihenfolge bringen kann, um komplexe Probleme zu lösen. Es wird intelligent ermittelt, welches Tool für jeden Schritt verwendet werden soll. Die Ausgabe einer Aktion kann als Eingabe für die nächste verwendet werden, um ein endgültiges Ziel zu erreichen.

Aufgaben

In diesem Codelab erstellen Sie einen „Healthy Hints“-Agenten, einen intelligenten Ernährungsberater, der sich von einer einfachen Text-KI zu einem leistungsstarken Multi-Tool entwickelt. Sie beginnen mit der Erstellung eines einfachen Konversations-Agents, der Ernährungskonzepte versteht. Dann statten Sie ihn nach und nach mit einem Storage SDK-Tool zum Archivieren von Zutatenbildern und einem Vision-Tool zum „Lesen“ und Analysieren dieser Bilder aus. Am Ende dieses Labs haben Sie einen voll funktionsfähigen Orchestrator, der ein hochgeladenes Foto eines Lebensmitteletiketts aufnehmen, es zur Aufzeichnung in einem Cloud-Bucket speichern und sofort „Gesundheitstipps“ für jede Zutat bereitstellen kann.

2. Vorbereitung

Ein Google Cloud-Projekt mit aktivierter Abrechnung
Webbrowser

Projekt erstellen

Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell aktivieren

Sie verwenden die Cloud Shell, eine Befehlszeilenumgebung, die in der Google Cloud Console ausgeführt wird und in der die erforderlichen Sprachen bereits vorinstalliert sind. Klicken Sie in der Cloud Console rechts oben auf Cloud Shell aktivieren:

Sobald die Verbindung mit der Cloud Shell hergestellt ist, sehen Sie, dass Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt ist. Führen Sie in Cloud Shell den folgenden Befehl aus, um zu prüfen, ob Sie authentifiziert sind:

gcloud auth list

Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt:

gcloud config list project

Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:

gcloud config set project <YOUR_PROJECT_ID>

Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.

Editor öffnen

In diesem Codelab verwenden wir den integrierten Cloud-Editor. Klicken Sie im Cloud Shell-Fenster rechts oben auf die Schaltfläche „Editor öffnen“. Dadurch wird ein VSCode-Editor geöffnet.

3. ADK-Einrichtung

Wechseln wir zum Cloud Shell-Terminal, das wir im vorherigen Abschnitt aktiviert haben:

Virtuelle Umgebung erstellen und aktivieren (empfohlen)

Erstellen Sie im Cloud Shell-Terminal eine virtuelle Umgebung:

python -m venv .venv

Aktivieren Sie die virtuelle Umgebung:

source .venv/bin/activate

ADK installieren

pip install google-adk

4. Google API-Schlüssel

Google API-Schlüssel mit AI Studio erstellen:

Rufen Sie https://aistudio.google.com/ auf und klicken Sie im Menü unten links auf Get API Key.

Es wird ein Fenster mit API-Schlüsseln angezeigt. Klicken Sie in diesem Fenster auf „API-Schlüssel erstellen“:

Ein Pop-up-Fenster zum Erstellen eines neuen Schlüssels wird angezeigt. Geben Sie dem Schlüssel den Namen healthy-hints-key.

Rufen Sie das Drop-down-Menü „Importiertes Projekt auswählen“ auf.

Klicken Sie auf Import Project. Es wird ein Seitenfenster mit allen Ihren Google Cloud-Projekten angezeigt. Wählen Sie das Projekt aus, mit dem Sie arbeiten möchten.

Klicken Sie auf „Importieren“.

Das Drop-down-Menü wird jetzt mit dem Projekt aktualisiert, das Sie gerade importiert haben. Wählen Sie das Projekt im Drop-down-Menü aus. Klicken Sie jetzt auf „Schlüssel erstellen“. Sie sehen jetzt die Liste der erstellten API-Schlüssel. Klicken Sie auf das Kopiersymbol des API-Schlüssels, den Sie gerade erstellt haben.

5. Beispiel-Agent

Erstellen Sie im Cloud Shell-Terminal ein Stammverzeichnis für Ihren Agenten am gewünschten Speicherort im Projekt:

adk create healthy_hints

Sie können ein beliebiges Modell auswählen. In diesem Codelab verwenden wir jedoch „gemini-2.5-flash“.

In diesem Codelab verwenden wir Google AI. Fügen Sie den API-Schlüssel ein, den Sie im vorherigen Schritt erstellt haben.

Öffnen wir den Ordner, den wir gerade erstellt haben. Klicken Sie im Menü ganz links auf das Symbol und dann auf „Datei“ > „Ordner öffnen“. Wählen Sie den Ordner healthy_hints aus, der gerade erstellt wurde. Er befindet sich normalerweise im Ordner /home/<username>.
Die Ordnerstruktur healthy_hints sieht in der Regel so aus:

Sie sehen eine .env-Datei mit Ihrem Google-API-Schlüssel. Sie können diese Datei verwenden, um beliebige Umgebungsvariablen festzulegen.
Außerdem wird eine weitere Datei mit dem Namen agent.py erstellt. Das ist unsere Hauptagentendatei. Hier wird ein Beispiel für einen Stamm-Agenten erstellt. Sehen wir uns den Inhalt dieser Datei genauer an. Zuerst importieren wir llm_agent aus dem ADK. Anschließend verwenden wir die ADK-DSL, um den Stamm-Agent zu erstellen. Wir geben den Modellnamen als Gemini-2.5-flash an, benennen den Agenten und geben eine passende Beschreibung an. Die Anweisung ist hier das Wichtigste. Hier teilen wir dem Agenten in natürlicher Sprache mit, was er tun soll.
Dieser Beispiel-KI-Agent ist ziemlich allgemein gehalten. Er beantwortet einfach jede Frage, die ein Nutzer hat.
Lassen Sie uns diesen Agenten nun lokal ausführen. Es gibt zwei Möglichkeiten, mit diesem Agenten zu interagieren : über die Befehlszeile und über das Web.
CLI: Führen Sie den folgenden Befehl außerhalb des Verzeichnisses healthy_hints aus.

adk run healthy_hints

Wenn Sie sich im Verzeichnis healthy_hints befinden, führen Sie den folgenden Befehl aus:

adk run .

Die Ausgabe sollte in etwa so aussehen:

Schreiben Sie „Hallo“ oder stellen Sie eine Frage. Die Antwort kann für jeden unterschiedlich sein. Das ist das Wesen von generativer KI.

Web: Führen Sie den folgenden Befehl im übergeordneten Verzeichnis von healthy_hints aus :

adk web

6. Multi-Tool-Agent

Ein Tool ist ein modulares Codefragment – in der Regel eine Funktion oder eine API –, mit dem ein Agent über sein internes Wissen hinaus mit der Welt interagieren kann.

Arten von Tools im ADK

Funktionstools:Benutzerdefinierte Logik, die Sie selbst schreiben. Das kann beispielsweise eine Funktion sein, die eine Verbindung zu Ihrer spezifischen Datenbank herstellt, oder ein benutzerdefinierter Log-Parser für das spezielle Format Ihres Unternehmens.
Integrierte Tools:Einsatzbereite Funktionen, die von Google oder dem ADK bereitgestellt werden, z. B. Google Suche, Code Interpreter oder Google RAG Engine.
Agents-as-Tools::In fortschrittlichen „Multi-Tool“- oder „Multi-Agent“-Systemen kann ein spezialisierter Agent als Tool für einen anderen fungieren. Ein „Search Agent“ kann beispielsweise ein Tool sein, das von einem „Research Manager Agent“ verwendet wird.

In diesem Codelab geht es um die Funktionstools. Jetzt machen wir unseren Agenten zu einem Multi-Tool.

Fügen wir eine neue Methode get_weather in agent.py hinzu.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Wir ändern die Datei agent.py und ändern den Namen, die Beschreibung und die Anleitung des Agenten:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Bisher haben wir nur ein Tool erstellt. Erstellen wir nun mehrere Tools:

Erstellen wir eine weitere Methode mit dem Namen get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Wir ändern unseren Agenten so, dass er dieses Tool ebenfalls aufruft:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Wir haben die Beschreibung, die Anleitung und die Tools entsprechend angepasst. Jetzt führen wir diesen aktualisierten Agenten aus. Dieses Mal würde der Agent auch die aktuelle Uhrzeit und das aktuelle Wetter nennen.

7. SDK-Integration

Jetzt wissen wir, wie wir mehrere Tools verwenden. Sehen wir uns einige Beispiele aus der Praxis an. Lassen Sie uns einen Agenten für gesunde Tipps erstellen. Wir laden jedes Bild mit einer Liste von Inhaltsstoffen in unseren Agent hoch. Der Agent informiert uns dann darüber, welche Inhaltsstoffe gesund sind und welche nicht.

Erstellen wir zuerst einen Bucket in Google Cloud Storage, in den wir das Bild hochladen können. Öffnen wir einen neuen Tab und rufen wir https://console.cloud.google.com/ auf. Geben Sie in der Suchleiste „Cloud Storage“ ein. Wählen Sie nun unter „Produkte und Seiten“ die Option „Cloud Storage“ aus:

Dadurch gelangen Sie zur Übersichtsseite von Google Cloud Storage. Klicke auf die Schaltfläche Create bucket. Geben Sie auf der Seite zum Erstellen von Buckets den Namen des Buckets ein. Der Name kann beliebig sein. In diesem Codelab verwenden wir healthy-hints-bucket-kolkata. Lassen Sie alles andere unverändert und klicken Sie auf die Schaltfläche Create.

Erstellen wir eine neue Datei mit dem Namen requirements.txt und fügen wir google-cloud-storage ein. Wir verwenden das Python Storage SDK, um das Bild in Storage hochzuladen.

Installieren wir zuerst die Abhängigkeiten:

pip install -r requirements.txt

Möglicherweise müssen Sie zuerst die Storage API aktivieren. Führen Sie dazu den folgenden Befehl in Ihrem Terminal aus:

gcloud services enable storage.googleapis.com

Jetzt fügen wir ein neues Tool zum Hochladen des Bildes hinzu.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Aktualisieren wir nun unseren Agent, damit er das neue Tool verwendet:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Wir fügen jetzt ein weiteres Tool hinzu, mit dem die Zutaten aus dem Bild gelesen werden können. Fügen wir google-cloud-vision in requirements.txt ein und installieren wir die neue Abhängigkeit.

pip install -r requirements.txt

Möglicherweise müssen Sie die Vision API zuerst aktivieren. Führen Sie dazu den folgenden Befehl in Ihrem Terminal aus:

gcloud services enable vision.googleapis.com

Jetzt fügen wir ein neues Tool read_ingredients hinzu :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Aktualisieren wir nun unseren Agent, damit er dieses Tool verwendet.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Fazit

Herzlichen Glückwunsch zum Abschluss des Codelabs „Healthy Hints“! Sie haben eine Standard-KI erfolgreich von einem Textgenerator in einen proaktiven Multi-Tool-Agent umgewandelt. Durch die Integration der Vision API und des Cloud Storage SDK mit dem ADK haben Sie Ihrem Agenten die „Augen“ zum Lesen von Labels und den „Speicher“ zum Archivieren von Labels gegeben. Sie haben gesehen, wie der Agent autonom entscheidet, wann eine Datei gespeichert wird, und wie er Rohdaten interpretiert, um praktische Gesundheitstipps zu geben.

Diese Grundsätze dienen als Blaupause für jedes automatisierte System. Ob Sie nun die Cloud-Infrastruktur verwalten oder persönliche Assistenten entwickeln – das Prinzip bleibt dasselbe: Definieren Sie spezielle Tools und lassen Sie den Agenten die Logik orchestrieren. Als Nächstes können Sie weitere Tools wie eine „Nährwertdatenbank“ oder ein „E‑Mail-Tool“ hinzufügen, um die Wirkung Ihres Agents zu erhöhen.

ADK: Von den Grundlagen bis hin zu Multi-Tool-Agents Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.