Von Prototypen zu Kundenservicemitarbeitern mit ADK

1. Übersicht

Wo fängt die Entwicklung mit KI heute an? Für die meisten von uns beginnt es oft mit einer einfachen Frage: „Kann das Modell tatsächlich helfen, das Problem zu lösen, über das ich nachgedacht habe?“ Genau hier kommt Google AI Studio ins Spiel. Hier können Sie schnell Prototypen für alles erstellen. Ich möchte meine Küche umbauen und bin mir sicher, dass Gemini mir dabei helfen kann. Allerdings bin ich Ingenieur und kein Bauunternehmer. Ich bin mir nicht sicher, was ich fragen soll – es gibt so viel zu beachten: Vorschriften, Ausstattung usw. Lassen Sie uns das aufschlüsseln und Gemini einen sehr detaillierten Prompt für uns generieren lassen. Dann können wir einen vollständigen Renovierungsplan erstellen und das Ergebnis visualisieren. Aber Moment. Wie kann ich Unternehmen dabei helfen, ihr Geschäft auszubauen? GIB AGENTS EIN!!!

Ein Agent ist ein autonomes Programm, das mit einem KI-Modell kommuniziert, um eine zielbasierte Operation mit den ihm zur Verfügung stehenden Tools und dem Kontext auszuführen. Es ist in der Lage, autonome Entscheidungen auf der Grundlage von Fakten zu treffen.

Das Agent Development Kit (ADK)

Das Agent Development Kit (ADK) ist ein flexibles und modulares Framework zum Entwickeln und Bereitstellen von KI-Agenten. Das ADK unterstützt das Erstellen komplexer Anwendungen, indem mehrere unterschiedliche Agenteninstanzen zu einem Multi-Agenten-System (MAS) zusammengefasst werden.

Im ADK ist ein Multi-Agenten-System eine Anwendung, in der verschiedene KI-Agenten, oft in einer Hierarchie, zusammenarbeiten oder sich koordinieren, um ein größeres Ziel zu erreichen. Diese Strukturierung Ihrer Anwendung bietet erhebliche Vorteile, darunter verbesserte Modularität, Spezialisierung, Wiederverwendbarkeit, Wartbarkeit und die Möglichkeit, strukturierte Steuerungsabläufe mithilfe dedizierter Workflow-Agenten zu definieren.

Aufgaben

Sind Sie bereit, von unserem PROMPT-Prototyp zu „Einen Agenten erstellen“ zu wechseln? Wir erstellen einen Agenten, der das Angebotsdokument für das Küchenrenovierungsprojekt generiert. In diesem Lab haben Sie folgende Aufgaben:

  1. Einen einfachen Agenten zum Generieren eines Angebots für die Renovierung mit dem ADK erstellen
  2. Generiertes Dokument mit Renovierungsvorschlag in einem Cloud Storage-Bucket speichern
  3. Agent in Cloud Shell und in der Webausgabe des Agenten testen

Voraussetzungen

  • Ein Browser, z. B. Chrome oder Firefox
  • Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.

2. Hinweis

Projekt erstellen

  1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
  2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist .
  3. Aktivieren Sie Cloud Shell, indem Sie auf diesen Link klicken. Sie können zwischen dem Cloud Shell-Terminal (zum Ausführen von Cloud-Befehlen) und dem Editor (zum Erstellen von Projekten) wechseln, indem Sie in der Cloud Shell auf den entsprechenden Button klicken.
  4. Sobald die Verbindung mit der Cloud Shell hergestellt ist, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt ist:
gcloud auth list
  1. Führen Sie den folgenden Befehl in Cloud Shell aus, um zu prüfen, ob der gcloud-Befehl Ihr Projekt kennt.
gcloud config list project
  1. Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:
gcloud config set project <YOUR_PROJECT_ID>
  1. Verwenden Sie Python 3.9 oder höher.

Weitere gcloud-Befehle und Informationen zur Verwendung finden Sie in der Dokumentation.

3. Prototyp

Rufen Sie Google AI Studio auf. Beginnen Sie mit der Eingabe Ihres Prompts. Hier ist mein Prompt:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Passen Sie die Parameter auf der rechten Seite an, um eine optimale Antwort zu erhalten.

Auf Grundlage dieser einfachen Beschreibung hat Gemini einen unglaublich detaillierten Prompt für mich erstellt, mit dem ich meine Renovierung starten kann. Wir verwenden Gemini, um noch bessere Antworten von AI Studio und unseren Modellen zu erhalten. Je nach Anwendungsfall können Sie auch verschiedene Modelle auswählen.

Wir haben uns für Gemini 2.5 Pro entschieden. Das ist ein Thinking-Modell, was bedeutet, dass wir noch mehr Ausgabetokens erhalten, in diesem Fall bis zu 65.000 Tokens, für lange Analysen und detaillierte Dokumente. Die Gemini-Denkblase wird angezeigt, wenn Sie Gemini 2.5 Pro aktivieren. Diese Version hat native Schlussfolgerungsfunktionen und kann Anfragen mit langem Kontext verarbeiten.

Hier ein Snippet der Antwort:

4e4361663df80964.png

AI Studio hat meine Daten analysiert und all diese Dinge wie Schränke, Arbeitsplatten, Rückwand, Bodenbelag, Spüle, Kohäsion, Farbpalette und Materialauswahl erstellt. Gemini zitiert sogar Quellen.

Versuchen Sie nun, die Idee mit einem anderen Prompt zum Leben zu erwecken.

  1. Kopieren Sie diesen Prompt und fügen Sie ihn in den Prompt-Editor ein:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Hängen Sie ein Bild Ihrer aktuellen Küche an (oder verwenden Sie mein Beispielbild einer Küche).
  2. Ändern Sie das Modell in „Gemini 2.0 Flash Preview Image Generation“, damit Sie Bilder generieren können.

Ich habe diese Ausgabe erhalten:

fb33e7b1f6560a0c.png

Das ist die Stärke von Gemini.

Gemini kann Videos analysieren, Bilder generieren und echte Informationen mit der Google Suche verknüpfen – das sind nur einige der Funktionen, die nur mit Gemini möglich sind.

In AI Studio können Sie diesen Prototyp verwenden, den API-Schlüssel abrufen und ihn mit dem Vertex AI ADK zu einer vollständigen Agent-Anwendung skalieren.

4. ADK-Einrichtung

Wechseln Sie nun zum Cloud Shell-Terminal, das Sie im Abschnitt „Vorbereitung“ aktiviert haben:

  1. Erstellen Sie eine virtuelle Umgebung und aktivieren Sie sie (empfohlen).

Erstellen Sie im Cloud Shell-Terminal eine virtuelle Umgebung:

python -m venv .venv

Aktivieren Sie die virtuelle Umgebung:

source .venv/bin/activate
  1. ADK installieren
pip install google-adk

5. Projektstruktur

  1. Erstellen Sie im Cloud Shell-Terminal ein Stammverzeichnis für Ihre agentischen Apps am gewünschten Speicherort für Ihr Projekt:
mkdir agentic-apps
  1. Erstellen Sie im Hauptverzeichnis einen Ordner für unser aktuelles Projekt:
mkdir renovation-agent
  1. Rufen Sie den Cloud Shell-Editor auf und erstellen Sie die folgende Projektstruktur, indem Sie die Dateien anlegen (zuerst leer):
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Quellcode

  1. Öffnen Sie init.py und fügen Sie den folgenden Inhalt ein:
from . import agent
  1. Rufen Sie „agent.py“ auf und aktualisieren Sie die Datei mit dem folgenden Inhalt aus dem folgenden Pfad:

In agent.py importieren wir die erforderlichen Abhängigkeiten, rufen Konfigurationsparameter aus der Datei „.env“ ab und definieren den root_agent, der ein Angebotsdokument generiert und in einem Cloud Storage-Bucket speichert. Für den Cloud Storage-Schritt verwenden wir das Tool „store_pdf“.

HINWEIS: Das PDF ist derzeit NICHT FORMATIERT. Basierend auf dem PR der Community-Entwickler wurde das folgende Snippet hier eingefügt [nicht getestet]. Sie können es in der Methode „store_pdf“ anpassen:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Prüfen, ob Sie den Cloud Storage-Bucket haben

Hier wird das vom KI-Agenten generierte Angebotsdokument gespeichert. Erstellen Sie ihn und gewähren Sie Zugriff, damit das mit Vertex AI erstellte agentenbasierte System darauf zugreifen kann. Gehen Sie dazu so vor:

https://cloud.google.com/storage/docs/creating-buckets#console

Geben Sie Ihrem Bucket den Namen next-demo-store. Wenn Sie einen anderen Namen verwenden, müssen Sie den Wert von STORAGE_BUCKET in der .env-Datei aktualisieren (im Schritt „ENV Variables Setup“).

  1. Um den Zugriff auf den Bucket einzurichten, rufen Sie die Cloud Storage-Konsole und Ihren Storage-Bucket auf. In unserem Fall lautet der Bucket-Name „next-demo-storage“: https://console.cloud.google.com/storage/browser/next-demo-storage.

Klicken Sie auf „Berechtigungen“ > „Hauptkonten ansehen“ > „Zugriff gewähren“. Wählen Sie „allUsers“ als Identitäten und „Storage Object User“ als Rolle aus.

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. Liste mit Abhängigkeiten erstellen

Listen Sie alle Abhängigkeiten in requirements.txt auf. Sie können sie aus dem Repository kopieren.

Single-Agenten-System – Erklärung des Quellcodes

In der Datei „agent.py“ sind die Struktur und das Verhalten unseres Multi-Agenten-Systems für die Küchenrenovierung mithilfe des Agent Development Kit (ADK) definiert. Sehen wir uns die wichtigsten Komponenten an:

Agent-Definition

Root-Agent (Orchestrator): proposal_agent

Der root_agent fungiert als Orchestrator dieses Single-Agenten-Systems. Er empfängt die Renovierungsanfrage und bestimmt anhand der Anforderungen, welche Tools aufgerufen werden sollen.

Der root_agent sammelt dann die Antworten der Tools und kombiniert sie, um eine umfassende Antwort zu geben. In diesem Fall haben wir nur das Tool „store_pdf“.

7. Datenfluss und Schlüsselkonzepte

Der Nutzer initiiert eine Anfrage über die ADK-Schnittstelle (entweder das Terminal oder die Webbenutzeroberfläche).

  1. Die Anfrage wird vom root_agent empfangen.
  2. Der root_agent analysiert die Anfrage und leitet sie nach Bedarf an das Tool weiter.
  3. Das Tool „store_pdf“ wurde entwickelt, um den überarbeiteten Textinhalt in eine PDF-Datei zu schreiben und diese dann in Google Cloud Storage hochzuladen.
  4. Die Antwort wird dann an den root_agent zurückgegeben.
  5. Der root_agent kombiniert die Antworten und gibt eine endgültige Ausgabe an die Nutzerin oder den Nutzer aus.

LLMs (Large Language Models)

Die KI-Agenten nutzen LLMs, um Texte zu generieren, Fragen zu beantworten und Schlussfolgerungen zu ziehen. Die LLMs sind das „Gehirn“, das den Agenten hilft, Nutzeranfragen zu verstehen und zu beantworten. In dieser Anwendung verwenden wir Gemini 2.5.

Google Cloud Storage

Dient zum Speichern der generierten Dokumente mit den Renovierungsangeboten. Sie müssen einen Bucket erstellen und den KI-Agenten die erforderlichen Berechtigungen für den Zugriff darauf gewähren.

Cloud Run (optional)

Der OrderingAgent verwendet eine Cloud Run-Funktion, um mit AlloyDB zu interagieren. Cloud Run bietet eine serverlose Umgebung, in der Code als Reaktion auf HTTP-Anfragen ausgeführt werden kann.

AlloyDB

Wenn Sie den OrderingAgent verwenden, müssen Sie eine AlloyDB-Datenbank zum Speichern der Bestellinformationen einrichten.

.env-Datei

In der .env-Datei werden vertrauliche Informationen wie API-Schlüssel, Datenbankanmeldedaten und Bucket-Namen gespeichert. Es ist wichtig, diese Datei sicher aufzubewahren und sie nicht in Ihrem Repository zu speichern. Außerdem werden dort die Konfigurationseinstellungen für die Agenten und Ihr Google Cloud-Projekt gespeichert. Der root_agent oder unterstützende Funktionen lesen in der Regel Werte aus dieser Datei. Achten Sie darauf, dass alle erforderlichen Variablen in der .env-Datei korrekt festgelegt sind. Dazu gehört auch der Name des Cloud Storage-Buckets.

8. Modelleinrichtung

Die Fähigkeit Ihres KI-Agenten, Nutzeranfragen zu verstehen und Antworten zu generieren, basiert auf einem Large Language Model (LLM). Ihr Agent muss sichere Aufrufe an diesen externen LLM-Dienst durchführen. Dazu sind Authentifizierungsanmeldedaten erforderlich. Ohne gültige Authentifizierung lehnt der LLM-Dienst die Anfragen des Agents ab und der Agent kann nicht funktionieren.

  1. Rufen Sie einen API-Schlüssel von Google AI Studio ab.
  2. Ersetzen Sie im nächsten Schritt, in dem Sie die .env-Datei einrichten, <<your API KEY>> durch den tatsächlichen Wert Ihres API-Schlüssels.

9. Umgebungsvariablen einrichten

  1. Legen Sie die Werte für die Parameter in der .env-Vorlagendatei in diesem Repository fest. In meinem Fall enthält die .env-Datei diese Variablen:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Ersetzen Sie die Platzhalter durch Ihre Werte.

10. Agent ausführen

  1. Wechseln Sie im Terminal zum übergeordneten Verzeichnis Ihres Agent-Projekts:
cd agentic-apps/renovation-agent
  1. Alle Abhängigkeiten installieren
pip install -r requirements.txt
  1. Sie können den folgenden Befehl in Ihrem Cloud Shell-Terminal ausführen, um den KI-Agenten auszuführen:
adk run .
  1. Sie können Folgendes ausführen, um es in einer mit dem ADK bereitgestellten Web-UI auszuführen:

Hinweis: Sie müssen diesen Befehl AUSSERHALB des Ordners Ihres Agent-Projekts ausführen. Gehen Sie einen Schritt zurück und führen Sie ihn dann aus:

adk web
  1. Testen Sie mit den folgenden Prompts:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Ergebnis

Für den Befehl adk run . Das Ergebnis sieht so aus:

2703603a907329ae.pngae56b38cc6da9afe.png

…

91452a4de933a75b.png

Sie können prüfen, ob das Dokument mit dem Renovierungsvorschlag im Cloud Storage-Bucket erstellt wurde.

12. In Cloud Run bereitstellen

  1. Erstellen Sie im Stammordner des Projekts eine Datei mit dem Namen Dockerfile:
cd agentic-apps/renovation-agent
  1. Inhalte aus dem GitHub-Repository kopieren
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

in dieses Dockerfile.

  1. Stellen Sie die Anwendung mit dem folgenden Befehl in Cloud Run bereit:
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

Das war's. Nach der Bereitstellung sollte der Endpunkt im Terminal angezeigt werden und kann verwendet werden.

13. Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in diesem Beitrag verwendeten Ressourcen in Rechnung gestellt werden:

  1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen.
  3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Herunterfahren, um das Projekt zu löschen.

14. Glückwunsch

Das wars! Sie haben das Lab erfolgreich abgeschlossen. Sie haben mit dem ADK erfolgreich eine Multi-Agenten-App erstellt und mit ihr interagiert. Das Multi-Agenten-System soll die Küchenrenovierung vereinfachen, indem es Aufgaben wie das Erstellen von Angeboten, das Überprüfen von Genehmigungen und das Verfolgen des Bestellstatus automatisiert. Jeder KI-Agent hat eine bestimmte Rolle und der root_agent koordiniert die Aktivitäten, um eine umfassende Lösung zu bieten. Das System nutzt LLMs, Google Cloud-Dienste und möglicherweise externe APIs, um seine Funktionen bereitzustellen. Hier finden Sie einen Link zur Produktdokumentation.