Viele kleine Ladenbesitzer in Schwellenländern oder ländlichen Regionen sind nicht besonders technikaffin. Moderne CRMs und Inventar-Tools basieren auf einer Annahme, die in der Praxis selten zutrifft: dass Nutzende problemlos durch Dashboards, Menüs, mehrstufige Formulare und englischsprachige Interfaces navigieren können. Für die meisten inhabergeführten Geschäfte ist das eine Hürde.
Es gibt jedoch eine Software, die überall flüssig beherrscht wird: WhatsApp.
Daraus entstand eine einfache Frage: Was wäre, wenn das gesamte Geschäft – Bestellungen, Abrechnungen, Kundenbücher, Zahlungen – direkt in WhatsApp stattfinden könnte? Keine neue App, kein Webportal, keine Schulung. Einfach Nachrichten schreiben, so wie jeden Tag.
Das war die Ausgangslage. Dies ist die Entwicklungsgeschichte dahinter.
Was gebaut wurde
Auf hoher Ebene ist das System denkbar einfach aufgebaut.
Die Basis bildet ein KI-Agent mit einer PostgreSQL-Datenbank im Hintergrund. Die Datenbank verwaltet genau die Daten, die für ein kleines Geschäft zählen: Kunden, Bestellungen, Zahlungen, Kassenbücher (Ledger) und Inventar. Über der Datenbank liegen die typischen Funktionen einer klassischen REST-API: create_order, get_order, get_ledger, record_payment, search_customer und ähnliche CRUD-Operationen inklusive spezifischer Geschäftslogik.
Der KI-Agent fungiert als intelligente Schicht zwischen der WhatsApp-Nachricht und diesen Funktionen. Nachricht rein, Antwort raus – die gesamte Logik dazwischen wird automatisiert verarbeitet.
Durch die Anbindung an die WhatsApp Business API läuft die Kommunikation wie mit jedem normalen WhatsApp-Kontakt. Ob Text-Mix, verschiedene Sprachen oder Sprachnachrichten statt Tippen – der Agent verarbeitet jeden Input flexibel und natürlich.
Für Geschäfte, die ihren Laden ohnehin schon über WhatsApp organisieren, ändert sich in der Handhabung nichts. Das Smartphone wird lediglich um eine KI-Komponente erweitert.
Die Struktur des Agenten – Ein kurzer Überblick
Die Umsetzung basiert auf dem OpenAI Agents SDK. Der entscheidende Faktor für das Architektur-Design war hierbei die native Unterstützung von Multi-Agenten-Handoffs.
Das System setzt sich wie folgt zusammen:
- Customer-Facing Agent: Der zentrale Einstiegspunkt. Jede WhatsApp-Nachricht landet zuerst hier. Dieser Agent beantwortet selbst keine geschäftlichen Fragen, sondern analysiert lediglich die Art der Anfrage für die Weiterleitung.
- Order Agent: Zuständig für alles rund um Bestellungen, Rechnungen, Zahlungen und Kassenbücher. Dieser Agent hat Zugriff auf die operativen Datenbank-Tools.
- Customer Agent: Verantwortlich für allgemeine Produktanfragen, Verfügbarkeiten und Kundenprofile. Zudem lässt sich hierüber die Transaktionshistorie einzelner Kunden abrufen.
Sobald der Customer-Facing Agent eine Nachricht registriert, erfolgt eine grundlegende Klassifizierung: Handelt es sich um eine operative oder eine allgemeine Anfrage? Wenn Rechnungen erstellt, Zahlungen geprüft oder Kassenbücher eingesehen werden sollen, geht die Nachricht an den Order Agent. Bei Fragen zu Produkten oder Kundenhistorien übernimmt der Customer Agent.
Der Ziel-Agent führt anschließend eine eigene logische Bewertung durch. Er ermittelt die exakte Nutzerabsicht (create_order, get_order, get_ledger, record_payment) und ruft die entsprechende Funktion als Tool mit den passenden Parametern auf. Die Funktion interagiert mit PostgreSQL, liefert saubere Daten zurück und der Agent formuliert die Antwort in der Sprache des Nutzers.
Auf WhatsApp-Seite ist lediglich die finale Textantwort sichtbar. Drei Agenten und eine Datenbank verschwinden hinter einer einzigen, natürlichen Chat-Antwort.
Umsetzung mit dem OpenAI Agents SDK
Als technologische Basis dient das TypeScript Agents SDK von OpenAI – @openai/agents. Die Installation erfolgt über eine einzige Zeile:
Bash
npm install @openai/agents zod
Da das SDK Zod für die Definition von Tool-Parametern nutzt, werden beide Pakete zusammen installiert. Nach dem Setzen des API-Keys als Umgebungsvariable ist das Setup startbereit:
Bash
export OPENAI_API_KEY=sk-...
Mehr Vorbereitung ist nicht nötig. Das SDK verzichtet bewusst auf komplexen Overhead.
Definition eines Agenten
Ein Agent wird im SDK als Objekt mit einem Namen, Instruktionen und einer Liste von Tools definiert. Die Instruktionen legen die Rolle fest – also was der Agent tun soll und was nicht. Die Tools repräsentieren die ausführbaren Funktionen.
Die beiden spezialisierten Agenten des Systems sehen im Code wie folgt aus:
TypeScript
import { Agent } from '@openai/agents';
const customerAgent = new Agent({
name: 'Customer Agent',
instructions: `You are a helpful assistant for a grocery store.
Handle product inquiries, availability questions, and customer profile lookups.
When a customer asks about their purchase history or outstanding balance,
retrieve and present it clearly.
Always be concise, friendly, and professional.`,
tools: [searchCustomer, getLedger],
});
const orderAgent = new Agent({
name: 'Order Agent',
instructions: `You are an order management assistant for a grocery store.
You handle order creation, billing, payment recording, and ledger lookups.
Before creating an order, confirm the item, quantity, and price with the customer.
Keep responses clear and structured. Always include the order total
and order ID in confirmations.`,
tools: [createOrder, getOrder, recordPayment, getLedger, searchCustomer],
});Was zeichnet einen Agenten aus?
- Ein Modell kombiniert mit Instruktionen, die als System-Prompt fungieren.
- Die Instruktionen definieren die genaue Rolle sowie die Grenzen des Agenten.
- Jeder Agent besitzt einen klar fokussierten Aufgabenbereich (Order Agent für Transaktionen, Customer Agent für Lookups).
- Tools werden direkt bei der Definition übergeben (tools: […]) und stehen dem Agenten während des Runs zur Verfügung.
Erstellung der Function-Tools
Ein Tool dient als Brücke zwischen dem Agenten und der Datenbank. Es wird aufgerufen, sobald das Modell eine erforderliche Aktion erkennt.
TypeScript
import { tool } from '@openai/agents';
import { z } from 'zod';
const createOrder = tool({
name: 'create_order',
description: 'Creates a new sales order and generates an invoice for the customer. Call this tool when the user wants to record a product sale. Requires the customer name, item, quantity in kilograms, and the price per kilogram.',
parameters: z.object({
customer_name: z.string().describe('Full name of the customer placing the order'),
item: z.string().describe('The product being purchased, e.g. Apples, Mangoes, Bananas'),
quantity_kg: z.number().describe('Quantity of the item in kilograms'),
rate_per_kg: z.number().describe('Price per kilogram in the local currency'),
}),
execute: async (params) => {
// Datenbank-Integrationsschicht
// create_order(params)
},
});Die Kernbestandteile im Überblick:
- name: Der interne Bezeichner für das Modell. Sinnvoll ist eine präzise snake_case-Benennung wie create_order statt generischer Namen wie tool1.
- description: Das wichtigste Feld. Das Modell analysiert die Beschreibung, um den Aufrufzeitpunkt zu bestimmen. Ungenaue Beschreibungen führen schnell zu Fehlaufrufen.
- parameters: Ein strukturiertes Zod-Schema für die erwarteten Inputs. Jedes Feld erhält einen Typ (z.string(), z.number()) und eine .describe()-Methode zur Werte-Extraktion. Fehlen Pflichtparameter in der Nachricht, fordert das Modell diese automatisch an.
- execute: Die eigentliche Funktion, die nach erfolgreicher Validierung aller Parameter ausgeführt wird. Sie verarbeitet die Inputs und liefert einen einfachen String zurück.
Handoffs einrichten
Über Handoffs übergeben Agenten die Konversation untereinander. Dadurch lassen sich Verantwortlichkeiten sauber trennen, ohne komplexe Routing-Logik manuell schreiben zu müssen.
TypeScript
import { Agent } from '@openai/agents';
const customerFacingAgent = Agent.create({
name: 'Customer Facing Agent',
instructions: `You are the entry point for a shopkeeper's WhatsApp assistant.
Your only job is to understand what the user is asking and hand off to the right agent.
If the message is about an order, bill, payment, or ledger - hand off to the Order Agent.
If it is a general query - hand off to the Customer Agent.
Do not answer anything yourself.`,
handoffs: [orderAgent, customerAgent],
});Funktionsweise der Übergabe:
- handoffs: […] – Die Registrierung an dieser Stelle erlaubt es dem primären Agenten, nachgelagerte Agenten wie Tools aufzurufen. Routing-Logik oder Switch-Statements sind nicht erforderlich; das Modell steuert den Handoff inhaltsbasiert.
- Kontext-Erhalt – Bei der Übergabe wird der gesamte Chat-Verlauf an den neuen Agenten übermittelt. Die Bearbeitung knüpft direkt an den vorherigen Zustand an.
- Agent.create() vs new Agent() – Für Handoff-Strukturen ist Agent.create() zu bevorzugen, um die Typsicherheit der Rückgabewerte über alle Agenten hinweg zu gewährleisten.
Ausführung des Gesamtsystems
TypeScript
import { run } from '@openai/agents';
let history: any[] = [];
// Schritt 1 - Erste Nachricht aus dem Geschäft
const result1 = await run(customerFacingAgent, "Create a bill for John", { history });
history = result1.history;
// Schritt 2 - Folge-Nachricht, Kontext bleibt erhalten
const result2 = await run(customerFacingAgent, "5kg apples at $3 per kg", { history });
history = result2.history;- run(agent, message, { history }) – Der zentrale Aufruf des Agenten. Erfordert den Einstiegs-Agenten, die aktuelle Nachricht und das History-Array. Das SDK übernimmt das gesamte Handling (Agenten-Auswahl, Handoffs, Tool-Aufrufe).
- history – Ein Array mit allen vorherigen Nachrichten des Chats. Es startet leer und wächst mit jedem Durchlauf automatisch durch das SDK an.
- result.history – Das aktualisierte Array nach der Ausführung. Die Übergabe beim nächsten Aufruf stellt sicher, dass Folge-Kontexte wie „mach stattdessen 5kg daraus“ korrekt verarbeitet werden können.
- result.finalOutput – Die finale Textantwort des zuletzt aktiven Agenten.
Ablauf in der Praxis (Tracing)
Das SDK generiert automatisch Traces für jeden Durchlauf. Jeder Agentenaufruf, Ausführungszeiten und die gesamte Handoff-Kette lassen sich im Traces-Bereich der OpenAI-Plattform nachvollziehen.
Ein typischer Bestellprozess läuft wie folgt ab:
- Customer-Facing Agent empfängt: „Erstelle eine Rechnung für John über 10 kg Äpfel“
- Klassifizierung als Bestellanfrage $\rightarrow$ Handoff an den Order Agent
- Order Agent übernimmt. Da der Preis fehlt, erfolgt die Rückfrage: „Wie hoch ist der Preis pro kg für die Äpfel?“
- Nutzer antwortet: „3 Euro pro kg“
- Order Agent führt create_order aus mit customer_name: „John“, item: „Apples“, quantity_kg: 10, rate_per_kg: 3
- Das Tool schreibt in PostgreSQL und liefert die Bestätigung: „Invoice created. John: 10kg Apples @ 3€/kg = 30€. Order ID: 1042“
Drei Agenten. Ein Datenbank-Schreibvorgang. Eine Klärungsschleife. Zwei Nachrichten genügen für eine fertige Rechnung.
Relevante Workflows automatisieren
Die Kernkomponenten – Agenten, Tools, Handoffs und History – lassen sich auf unterschiedlichste Szenarien übertragen. Ob mobile Zeiterfassung per Sprachnachricht, automatisierte Terminabsprachen im Gesundheitswesen oder Sendungsverfolgung in der Logistik im gesamten DACH-Raum.
Die Definition des Wissensstands und der Fähigkeiten liegt beim Entwickler – das Modell steuert die Ausführung.
Wenn Prozesse im Unternehmen eine intelligentere Schnittstelle erfordern: Einfach bauen
Schreibe einen Kommentar