Jenseits des Chat-Fensters: Architektur eines WhatsApp-AI-Agenten auf Google ADK

Die meisten KI-Demos bestehen aus einem Textfeld, das mit einem Modell verbunden ist: Eine Frage wird eingegeben, es kommt eine fließende Antwort heraus, und das Publikum ist zufrieden. Ein Produkt, auf das echte Kunden angewiesen sind, hat eine längere Liste an Anforderungen. Es muss sich an Gespräche erinnern, mit aktuellen Unternehmensdaten arbeiten, Aktionen ausführen, Fehlern standhalten und den Kunden an einen Menschen weiterleiten, wenn Automatisierung nicht ausreicht.

Dieser Artikel zeigt die Architektur eines Produktassistenten, der innerhalb von WhatsApp für einen EV-Lademarkt in Sri Lanka läuft. Er dient EV-Fahrern, Eigentümern, die Ladestationen betreiben könnten, sowie Menschen, die einfach etwas über EV-Ladung lernen möchten. Am Ende haben Sie einen konkreten Entwurf für die Komponenten, die das Modell umgeben, sowie eine Reihe von Designregeln, die Sie in Ihrem eigenen Assistenten wiederverwenden können – unabhängig vom jeweiligen Kanal.

Warum der Kanal das Produkt prägt

Das Team wählte WhatsApp, damit niemand ein weiteres Programm installieren muss, nur um eine Frage zu stellen. Die Zielnutzer sind bereits in WhatsApp aktiv: Sie wissen, wie man eine Nachricht sendet, einen Standort teilt, einen Kontakt speichert und auf eine bestimmte Nachricht in einem Thread antwortet. Das Treffen mit den Nutzern dort beseitigt das Einarbeitungsproblem völlig. Anstatt den Menschen beizubringen, wie man ein KI-Produkt verwendet, erscheint der Assistent in einem Tool, das sie bereits verstehen.

Diese Wahl bringt außerdem Einschränkungen mit sich, denen ein Web-Chatbot niemals ausgesetzt ist:

• Antworten müssen kurz sein, denn lange Antworten wirken auf dem Handy überladen.
• Nachrichten sollten in einem natürlichen Tempo eintreffen und nicht als einziger Textblock.
• Forderungen nach Standortinformationen sollten über Whattsapps eingebaute Schnittstelle für das Teilen von Standorten erfolgen.
• Kontaktinformationen sollten als echte Kontaktkarte angezeigt werden, nicht als eingefügter Text.

Ziel ist ein Gesprächsverlauf, der sich wie bei WhatsApp anfühlt – und nicht ein auf eine Messaging-App gepresster Desktop-Chatbot. Behalten Sie das für jeden Kanal im Hinterkopf: Die Benutzeroberflächenkonventionen der Plattform sind Teil der Spezifikation, keine Dekoration.

Der Anfragenpfad vom webhook zur Antwort

Die Backend-Logik ist in Python mit Google’s Agent Development Kit (ADK) sowie FastAPI geschrieben. ADK kann einen fertiggestellten API-Server für Agenten erstellen, der eine integrierte Unterstützung für den Betrieb von Agenten, das Verwalten von Sitzungen sowie das Streamen von Ergebnissen als Ereignisse bietet. Dieser API-Server läuft auf FastAPI und Uvicorn, wodurch eine Erweiterung mit einem benutzerdefinierten WhatsApp-webhook sowie branchenspezifischen Endpunkten einfach möglich ist.

Ein ADK-Agent setzt sich aus vier Komponenten zusammen:

• Einem Modell, wie zum Beispiel Gemini.
• Anweisungen, die die Rolle und Grenzen des Agenten definieren.

Tools, mit denen Daten abgerufen oder Aktionen ausgeführt werden können.

Eine Sitzung, die das Gesprächsmemory speichert.

Durch eine end-to-end-Überwachung einer einzigen Nachricht wird das Design konkret:

1. Ein Benutzer sendet eine WhatsApp-Nachricht, und Meta leitet sie an den FastAPI-Webhook weiter.
2. Die Backend-Plattform analysiert die Nachricht und überträgt sie in Chatwoot, damit das Support-Team das Gespräch verfolgen kann.
3. Das Backend sucht die Sitzung für diesen Benutzer und leitet die Nachricht an ADK weiter.
4. ADK startet den Koordinator, der die Anfragen weiterleitet: technische Fragen an den EV-Agenten, Einnahmefragen an den Preismodul-Agenten, Standortsuchen an den Station-Agenten.
5. Der ausgewählte Agent durchsucht entweder die Vertex AI-Wissensdatenbank oder ruft ein Tool auf, um beispielsweise Standortdaten abzufragen, Einnahmen zu schätzen, eine Kontaktkarte zu senden oder den Standort des Benutzers anzufragen.

Sobald die Antwort fertig ist, formatiert FastAPI sie in kurze WhatsApp-Nachrichten, sendet sie über Metas API und kopiert die Antwort in Chatwoot.

Bemerken Sie, wie gering der Anteil des Modells an diesem Prozess ist. Die Parsing, die Abfrage von Sessions, das Routing, das Formatieren, die Übermittlung und das Spiegeln sind alles gewöhnliche Backend-Aufgaben.

Ein Koordinator, drei Spezialisten

Der Assistent ist als Koordinator organisiert, der Aufgaben an drei spezialisierte Agenten delegiert:

• Ein EV-Infrastruktur-Agent für Ladetypen, Installation und Vorschriften.
• Ein Preis- und Geschäfts-Agent für wirtschaftliche Aspekte der Hosting-Lösungen.
• Ein Stationssuch-Agent zur Erkennung von Ladestellen.

Die einzige Aufgabe des Koordinators besteht darin, die Absicht zu verstehen und das Gespräch an den richtigen Spezialisten weiterzuleiten. Eine Frage zu Ladegerättypen wird an die Abteilung für Infrastruktur weitergeleitet, ein Anfrager, der sich nach möglichen Einnahmen erkundigt, wird an die Abteilung für Preise weitergeleitet, und eine Anfrage nach Stationen in der Nähe von Galle geht an die Stationssuche. Diese Weiterleitungen sind für den Benutzer unsichtbar, der das Gefühl hat, ein kontinuierliches Gespräch mit einem einzigen Assistenten zu führen.

Die Alternative bestand darin, einen einzigen großen Agenten mit einer langen Systemanweisung sowie allen angehängten Tools zu verwenden. Das funktioniert für ein Prototyp, doch mit zunehmender Anzahl an Tools und Gesprächsflüssen zeigte sich, dass die Aufteilung der Verantwortlichkeiten auf drei Arten Vorteile brachte: Jede Anweisung blieb kurz, es war leicht zu erkennen, welcher Agent welches Tool aufrufen konnte, und jeder Fluss konnte unabhängig getestet werden. Auch die Trennung eines Koordinators von seinen Spezialisten, ein dokumentiertes Muster der Agentenorchestrierung, machte Änderungen günstiger, da der Preisfluss ohne Beeinflussung der Stationssuche überarbeitet werden konnte.

Es gibt einen Kostenfaktor, der erwähnt werden sollte. Jede Routenentscheidung stellt einen weiteren Modellaufruf dar, der fehlschlagen kann; daher scheitert eine falsch geroutete Anfrage auf eine Weise, wie es ein einzelner Agent niemals tun würde. Das ist einer der Gründe, warum die später beschriebene Bewertungsstrategie prüft, welcher Agent und welche Werkzeuge gewählt wurden – und nicht nur die endgültige Formulierung. Für eine ausführlichere Erklärung dazu, wie Routing und spezialisierte Agenten zusammenwirken, siehe spezialisierte Agenten, ein Keyword-Router und Interrupt in LangGraph.

Antworten auf einer kontrollierten Wissensbasis gründen

Ein Unternehmensassistent darf keine Fakten erfinden, und die Ladeinfrastruktur für Elektrofahrzeuge ist voller Details, bei denen leicht Fehler entstehen können: Ladekapazitäten, Ladezeiten, Installationsanforderungen, Vorschriften, Fahrzeugmodelle sowie firmenspezifische Informationen. Viele dieser Aspekte ändern sich im Laufe der Zeit, und ein allgemeines Modell verfügt über nur begrenzte Kenntnisse des lokalen Marktes.

Die Lösung ist die retrieval-augmented Generation. Die relevanten Kenntnisse werden als Korpus im RAG Engine von Vertex AI gespeichert, und bevor ein technisches Frage beantwortet wird, kann der Agent nach den am relevantesten passenden Abschnitten darin suchen. Es existieren zwei separate Suchwege: einer für allgemeine Ladeinfrastrukturen und einer für Fahrzeugmodelle sowie Fragen zu Ladezeiten. Durch diese Aufteilung des Korpus bleiben die Ergebnisse fokussiert, denn eine Frage dazu, wie lange ein bestimmtes Auto zum Aufladen benötigt, konkurriert nicht mit Vorschriftendokumenten um die obersten Ergebnisse.

Die Arbeitsteilung ist die zentrale Idee. Das Modell erstellt weiterhin die Antwort, doch die Daten stammen aus Quellen, die das Unternehmen kontrolliert und ohne erneutes Trainieren aktualisieren kann.

Gespräche in Handlungen umwandeln

Der größte Schritt bestand darin, über das Beantworten von Fragen hinauszugehen. Der Assistent verfügt über Werkzeuge, die tatsächliche Aufgaben erledigen können. Er kann:

• Den Backend-Teil des Marktplatzes abfragen, um herauszufinden, wie viele Ladestationen in der Nähe einer bestimmten Stadt vorhanden sind.
• Eine native WhatsApp-Ortungsanfrage senden.
• Die Firmenkarteikarte versenden.
• Den Standort des Büros als Kartenpin teilen.
• Eine Schätzung der potenziellen Einnahmen für jemanden erstellen, der in Erwägung zieht, eine Ladestation zu betreiben.
• Ein Gespräch bei Bedarf an einen Menschen melden.

Warum die Einnahmenberechnung aus reinem Python besteht

Der Einnahmenfluss zeigt die wichtigste Designregel des Systems. Zunächst sammelt der Assistent durch Gespräche Informationen über das Eigentum des Nutzers sowie dessen Ladeanforderungen. Anschließend berechnet er den monatlichen Energieverbrauch, die erwarteten Einnahmen, die Stromkosten, den monatlichen und jährlichen Gewinn.

Diese Berechnungen erfolgen mithilfe deterministischer Python-Code, nicht durch das Sprachmodell selbst. Modelle sind bei arithmetischen Aufgaben unzuverlässig, und die Finanzdaten, die einem potenziellen Kunden präsentiert werden, müssen reproduzierbar und überprüfbar sein. Das Modell steuert das Gespräch und extrahiert die Eingaben; der Code erzeugt anschließend die Zahlen. Das Ergebnis wird über ein strukturiertes WhatsApp-Muster übermittelt, und der Lead wird in Google Sheets erfasst.

Nutzen Sie das Modell für Sprache und Entscheidungen sowie herkömmliche Software für alles, was präzise sein muss.

Diese Regel gilt weit über Preisgestaltung hinaus: Die Handhabung von Datumsangaben, Einheitenumrechnungen, Eignungsprüfungen sowie alles mit rechtlichem oder finanziellen Gewicht gehört in den Code, den das Modell aufruft, und nicht in die Ausgabe des Modells.

Sitzungszustand ist Produktlogik

Eine gute Konversation hängt davon ab, was zuvor geschehen ist. Der Assistent führt für jede WhatsApp-Nummer eine separate Sitzung, in der der Name des Benutzers, die Telefonnummer, die von ihm ausgewählte Menüoption, aktuelle Nachrichten, der Standort sowie die ID der letzten Nachricht gespeichert werden.

Durch das Speichern der ID der letzten Nachricht kann das System Antworten auf spezifische Menünachrichten verstehen, was WhatsApp-Nutzer ständig tun. Der Sitzungszustand ermöglicht außerdem, dass mehrstufige Abläufe nahtlos weiterlaufen. Eine Standortübertragung funktioniert beispielsweise wie folgt:

1. Fragen, ob der Benutzer seinen Standort teilen möchte.

Warten Sie darauf, dass die Standortnachricht von WhatsApp ankommt.

Speichern Sie die Koordinaten in der Sitzung ab.

Fahren Sie das Einrichtungsgespräch dort fort, wo es aufgehört hat.

Ohne diesen Zustand würde jede Nachricht als Beginn eines neuen Gesprächs betrachtet werden. Der Speicher in einem Agenten ist kein optionales Zusatzfeature; er bestimmt das Verhalten des Produkts und verdient genauso viel Designaufmerksamkeit wie jede andere Funktion.

Formatierung für kleine Bildschirme

Eine überraschende Erkenntnis war, dass eine technisch korrekte Antwort dennoch falsch wirken kann – allein aufgrund ihrer Form. Modelle neigen dazu, lange Absätze, Markdown-Listen sowie mehrere Ideen in einem Block zusammenzufassen. Das liest sich auf einem Desktop gut, ist aber in einer Chat-Blase schlecht lesbar.

Eine spezielle Formatierungsschicht kümmert sich darum. Sie:

• Übersetzt Markdown in WhatsApps eigene Formatierungssyntax.
• Erkennnt Listen, die innerhalb von fließendem Text versteckt sind.

Erstellt sie wieder als lesbare Aufzählungspunkte.

Splittet lange Antworten in mehrere kürzere Nachrichten auf.

Kurze Pausen zwischen den Abschnitten geben dem Leser Zeit, jede Idee aufzunehmen. Es geht nicht darum, so zu tun, als würde ein Mensch tippen; es geht um das Tempo. Tippen-Indikatoren, die über die Meta API gesendet werden, zeigen an, dass eine Antwort vorbereitet wird.

Der Assistent reagiert außerdem auf bestimmte Nachrichten mit einem Emoji – und zwar selektiv. Ein leichtgewichtiges Modell wie Flash Lite entscheidet, ob eine Nachricht eine Reaktion verdient; falls ja, wird die Reaktion über die Meta API gesendet. Emotionale, aufregende, lustige oder bedeutungsvolle Nachrichten erhalten möglicherweise ein Emoji, während routinemäßige Nachrichten wie „okay“, „danke“ oder einfache Anweisungen in der Regel keines erhalten. Die Verwendung eines kleinen, günstigen Modells für diese Entscheidungsfindung hält Latenzzeiten und Kosten niedrig, während die Hauptagenten sich um den Inhalt der Nachrichten kümmern. Solche Details erscheinen einzeln unbedeutend, doch zusammen bestimmen sie, ob das Produkt natürlich anmutet.

Ein Weg zu einem Menschen offen halten

Automatisierung sollte niemals eine Mauer zwischen Kunden und dem Unternehmen darstellen. Jedes eingehende Gespräch wird mit Chatwoot synchronisiert, und auch die Antworten des Assistenten werden hinzugefügt, sodass das Support-Team stets genau sieht, was gesagt wurde.

Wenn ein Benutzer nach einer echten Person fragt oder Anzeichen von Frustration zeigt, aktiviert der Assistent einen Prozess für menschliche Unterstützung, bei dem die Anfrage zusammen mit der Frage des Benutzers aufgezeichnet wird, damit das Team sie bearbeiten kann. Da das gesamte Gespräch bereits abgebildet ist, muss die Person, die übernimmt, den Kunden nicht bitten, sich zu wiederholen.

Automatisierung sollte repetitive Arbeiten beseitigen, nicht den Zugang zu einer Person.

Zuverlässigkeit außerhalb des Gesprächs

Das System sendet außerdem ausgehende WhatsApp-Vorlagenkampagnen, was ein subtiles Problem mit sich bringt: Eine Werbebotschaft sollte niemals jemanden stören, der mitten in einem Support-Gespräch ist. Vor dem Versand prüft das System, wann jeder Empfänger zuletzt mit dem Assistenten interagiert hat. Jene, die vor Kurzem noch gesprochen haben, bleiben vorerst unberührt: Ihre Nachricht wird zurückgehalten, in SQLite gespeichert und einem Wiederholungs-Endpunkt zur Verfügung gestellt, der sie später senden kann.

Dazu kommen die weniger attraktiven Funktionen, die jedes Service benötigt:

• Deduplizierung eingehender Nachrichten, da Webhooks dasselbe Ereignis mehrfach übermitteln können.
• Health-Monitoring.
• Bearbeitung des Refreshs von Zugriffstoken.
• CORS-Kontrollen für die HTTP-Endpunkte.
• Basierte Deployment-Lösung mit Docker.
• Fehlerverfolgung mit Sentry.

Nichts davon würde bei einer Demo jemanden beeindrucken. Alle werden unverzichtbar, sobald sich die Demo in einen Dienst verwandelt, auf den die Kunden angewiesen sind.

Testen des Verhaltens, nicht nur des Textes

Agenten sind schwieriger zu testen als gewöhnliche Funktionen, denn derselbe Eingabewert kann leicht unterschiedliche Ausgabeergebnisse liefern. Noch schlimmer ist, dass die Fehlermöglichkeiten aus dem endgültigen Text nicht offensichtlich sind. Eine Antwort kann gut klingen, obwohl das falsche Tool aufgerufen wurde, oder das richtige Tool kann aufgerufen werden, während das Ergebnis schlecht übermittelt wird.

Daher verwendet das Bewertungssystem simulierte Gespräche, die Infrastrukturfragen, Preisabrechnungsprozesse sowie Gespräche zwischen Spezialisten umfassen. Die Überprüfungen beziehen sich auf den Ablauf der Toolnutzung, also welche Agenten und Tools in welcher Reihenfolge aufgerufen wurden, und nicht nur auf die Formulierung der endgültigen Antwort.

Anderungen an den Prompts werden auf dieselbe Weise behandelt. Anstatt den Systemprompt manuell zu bearbeiten, experimentierte das Team mit einem Optimierungsprozess, bei dem mögliche Anweisungen anhand einer festgelegten Reihe von Gesprächen bewertet werden, einschließlich der GEPA-basierten Prompt-Optimierung. Die Kandidatanweisungen werden mit Trainingsfragen verglichen, und ein separater Bewertungsalgorithmus unter Verwendung von Gemini bewertet jede Antwort hinsichtlich Genauigkeit und Persönlichkeit. Dadurch wird die Arbeit mit Prompts zu etwas, das eher einer Ingenieurarbeit ähnelt: Anstatt eine Änderung wegen eines besseren Gefühls beizubehalten, kann man das Verhalten in einer wiederholbaren Reihe von Gesprächen vergleichen. Für jede Konfiguration mit einem Modell als Bewertungsalgorithmus gilt eine Einschränkung: Der Bewertungsalgorithmus hat eigene Voreingenommenheiten, weshalb es sinnvoll ist, seine Bewertungen vor der Verwendung für wichtige Entscheidungen mit menschlichem Urteil abzugleichen.

Haupterkenntnisse

• Das Modell ist nur ein Bestandteil; der größte Teil der Ingenieursarbeit liegt in der Routenplanung, dem Abrufen von Informationen, dem Zustandsmanagement, den Werkzeugen, der Formatierung, der Fehlerbehandlung und der Eskalation.
• Splittieren Sie einen wachsenden Agenten in einen Koordinator sowie spezialisierte Expert:innen, sobald Anfragen und Werkzeuglisten schwer zu verarbeiten sind, und testen Sie die Routenplanung selbst.
• Basierten Sie faktische Antworten auf einer von Ihnen kontrollierten Wissensdatenbank und führen Sie präzise Aufgaben wie Berechnungen in deterministischem Code aus.
• Betrachten Sie den Sitzungszustand sowie die kanalbezogene Formatierung als Kern der Produktlogik.
• Bewahren Sie stets einen sichtbaren, einfachen Weg zu einem Menschen auf.
• Bewerten Sie die Werkzeugverläufe innerhalb eines festgelegten Gesprächssatzes, damit Änderungen an den Anfragen gemessen statt nur geschätzt werden können.

Das Umhüllen einer API-Aufrufanfrage mit einem Prompt liefert eine Demo. Ein zuverlässiger Agent ist ein vollständiges System, in dem Sprachmodelle, Daten, Tools, Produktdesign sowie herkömmliche Backend-Entwicklung jeweils die Aufgaben erledigen, für die sie am besten geeignet sind.