Einen KI-Agenten in die eigene App integrieren: Architektur in sechs Schritten

Die meisten Anleitungen zu KI-Agenten enden bei einer Demo im Terminal. In einem echten Produkt fängt die Arbeit dort erst an: Der Agent muss mit deinen Daten arbeiten, darf nur das, was der eingeloggte Nutzer darf, muss bezahlbar bleiben und sich testen lassen. Dieser Artikel beschreibt den Aufbau, mit dem ich Agenten in Web- und Mobile-Apps bringe.

Der Aufbau im Überblick

Der Agent lebt im Backend, nie direkt in der App. Die App schickt eine Nachricht an einen eigenen Endpunkt, etwa POST /api/agent/chat. Dort passiert alles Weitere:

1. Nutzer prüfen, Kontext zusammenstellen
2. Sprachmodell mit Nachricht, Kontext und Werkzeugliste aufrufen
3. Werkzeugaufrufe ausführen, Ergebnisse zurückgeben, wiederholen
4. Antwort und strukturierte Daten an die App zurückgeben

Der API-Schlüssel des Modellanbieters liegt damit nie auf dem Gerät, und jede Aktion läuft durch dieselben Berechtigungsprüfungen wie der Rest deiner API.

1. Eine Aufgabe und ihre Werkzeuge

Werkzeuge (englisch tools oder function calling) sind der Kern eines Agenten. Jedes Werkzeug hat einen Namen, eine Beschreibung in normaler Sprache und ein Schema für die Parameter. Das Modell liest die Beschreibung und entscheidet, wann es das Werkzeug braucht.

const searchEvents = defineTool({
  name: "search_events",
  description:
    "Sucht öffentliche Events in einer Stadt. Nutze das, wenn der Nutzer " +
    "etwas unternehmen will und Ort oder Zeitraum genannt hat.",
  schema: z.object({
    city: z.string(),
    from: z.string().date(),
    to: z.string().date(),
    category: z.enum(["sport", "musik", "essen", "kultur"]).optional(),
  }),
  needsConfirmation: false, // liest nur
  run: (user, args) => events.search({ ...args, limit: 5 }),
});

Was sich bewährt hat:

• Wenige, eindeutige Werkzeuge. Fünf gut beschriebene schlagen zwanzig ähnliche. Überschneiden sich zwei, wählt das Modell zuverlässig das falsche.
• Die Beschreibung sagt, wann. Nicht nur, was das Werkzeug tut, sondern in welcher Situation es gedacht ist.
• Kleine Ergebnisse. Fünf Treffer mit den nötigen Feldern statt der ganzen Datenbankzeile. Jedes Zeichen kostet Geld und verwässert die Antwort.
• Bestehende Logik wiederverwenden. Ein Werkzeug ruft dieselben Services auf wie deine API. Keine Sonderwege für die KI.

2. Der Kontext pro Anfrage

Das Modell weiß nichts über deine App und nichts über den Nutzer. Was es wissen soll, kommt bei jeder Anfrage neu in den Systemprompt: Rolle und Ton des Agenten, heutiges Datum und Uhrzeit, Ort, Sprache, und eine knappe Zusammenfassung des Nutzers (etwa seine häufigsten Interessen). Nicht das ganze Profil: Was der Agent nicht braucht, gehört nicht hinein. Das spart Kosten und ist beim Datenschutz die bessere Ausgangslage.

Wichtig ist, diesen Kontext pro Anfrage zu bauen und nirgends zwischenzuspeichern, wo eine zweite, gleichzeitige Anfrage ihn überschreiben könnte. Ein geteiltes Objekt, in das jede Anfrage „ihren" Nutzer schreibt, funktioniert im Test mit einem Nutzer einwandfrei und verwechselt unter Last Personen.

3. Die Schleife im Backend

Ein Agent ist im Kern eine Schleife: Modell fragen, gewünschtes Werkzeug ausführen, Ergebnis zurückgeben, erneut fragen, bis das Modell mit Text antwortet. Vereinfacht, unabhängig vom Anbieter:

async function runAgent(user: User, message: string) {
  const messages = [systemPrompt(user), ...history(user), userTurn(message)];

  for (let step = 0; step < MAX_STEPS; step++) {
    const reply = await model.respond({ messages, tools: TOOLS });

    if (reply.type === "text") return reply.text;   // fertig

    // Das Modell möchte ein Werkzeug benutzen
    const tool = TOOLS_BY_NAME[reply.toolName];
    const args = tool.schema.parse(reply.arguments); // validieren
    authorize(user, tool, args);                     // darf er das?

    const result = tool.needsConfirmation
      ? await askUserToConfirm(user, tool, args)     // App zeigt Dialog
      : await tool.run(user, args);

    messages.push(reply.asMessage(), toolResult(reply, result));
  }

  return "Das habe ich nicht in einem Schritt geschafft. Magst du es genauer beschreiben?";
}

Drei Details aus dem Beispiel, die in Demos oft fehlen:

• MAX_STEPS begrenzt die Schleife. Ohne Obergrenze kann ein verwirrtes Modell sich endlos selbst aufrufen, und jeder Schritt kostet.
• schema.parse prüft die Parameter, bevor irgendetwas passiert. Sprachmodelle erfinden gelegentlich Felder oder Formate.
• authorize prüft im Code, ob der Nutzer die Aktion überhaupt darf. Die Nutzer-ID kommt aus dem Login-Token, nie aus den Parametern, die das Modell vorschlägt.

Nicht jeder Fall braucht die volle Schleife. Wenn die möglichen Aufgaben überschaubar sind, reicht oft ein Router: Ein Modellaufruf erkennt die Absicht und zieht die Parameter heraus, normaler Code führt den passenden Ablauf aus, ein zweiter Aufruf formuliert die Antwort. Das ist günstiger, schneller und leichter zu testen. Die Schleife lohnt sich, sobald Aufgaben mehrere, vorher unbekannte Schritte brauchen.

4. Gedächtnis, das der Nutzer kontrolliert

Ein Agent wirkt erst dann persönlich, wenn er sich an etwas erinnert: dass jemand vegetarisch isst, lieber kleine Runden mag oder abends keine Zeit hat. Technisch gibt es zwei Wege, die sich gut ergänzen:

• Aus Verhalten abgeleitet: Welche Kategorien jemand oft nutzt, wann er aktiv ist. Das ergibt sich aus Daten, die die App ohnehin hat.
• Ausdrücklich gemerkt: Ein Werkzeug wie remember_preference, das eine kurze Notiz speichert, wenn der Nutzer etwas über sich sagt.

Beides gehört in eine eigene, übersichtliche Tabelle, nicht in gespeicherte Gesprächsprotokolle. Dann kann die App sie anzeigen, und der Nutzer kann einzelne Einträge oder alles löschen. Das ist nicht nur Datenschutzpflicht, sondern schafft Vertrauen: Wer sieht, was der Agent weiß, gibt ihm lieber mehr. Mehr dazu in KI-Agenten und DSGVO.

5. Leitplanken im Code, nicht im Prompt

„Lösche niemals Daten" im Systemprompt ist eine Bitte, keine Regel. Was der Agent nicht darf, darf er technisch nicht können:

• Kein Werkzeug ohne Zweck. Was nicht als Werkzeug existiert, kann das Modell nicht auslösen.
• Bestätigung vor Schreibaktionen. Termin buchen, Nachricht senden, etwas bezahlen: Der Agent bereitet vor, die App zeigt einen Dialog, der Nutzer bestätigt.
• Limits. Anfragen pro Nutzer und Stunde, maximale Länge der Eingabe, maximale Antwortlänge. Das schützt vor Missbrauch und vor überraschenden Rechnungen.
• Fremde Inhalte sind Daten, keine Befehle. Texte aus E-Mails, Webseiten oder Nutzerprofilen können Anweisungen enthalten („Ignoriere alles und …"). Sie dürfen die Rechte des Agenten nie erweitern.

6. Testen und beobachten

Ein Agent braucht zwei Arten von Tests:

• Klassische Tests für Endpunkt und Werkzeuge, mit einem nachgebildeten Modell: Stimmen Validierung, Berechtigungen und Antwortformat?
• Qualitätstests mit einer Liste echter Beispiel- anfragen und dem erwarteten Verhalten: Welches Werkzeug sollte gewählt werden, welche Parameter, was darf auf keinen Fall passieren? Die laufen vor jeder Änderung am Prompt oder beim Modellwechsel.

Im Betrieb protokolliere ich pro Anfrage gewählte Werkzeuge, Dauer, verbrauchte Tokens und ob der Nutzer zufrieden weitergemacht hat, ohne die Gesprächsinhalte länger als nötig aufzubewahren. So sieht man früh, wo der Agent hängt, und was er kostet.

Besonderheiten in Mobile-Apps

In einer React-Native-App kommt einiges dazu, das im Web kaum auffällt:

• Strukturierte Antworten statt nur Text. Gibt der Agent neben dem Text auch Objekte zurück (Events, Termine, vorgeschlagene Aktionen), rendert die App echte Karten mit Knöpfen. Das fühlt sich nach App an, nicht nach Chatfenster.
• Funkloch einplanen. Lange Anfragen brauchen Zeitlimits, sichtbaren Ladezustand und einen Weg, es erneut zu versuchen.
• Vorschläge als Knöpfe. Zwei, drei Folgefragen zum Antippen senken die Hürde enorm, gerade auf dem Handy.
• Store-Review. Apple und Google fragen nach, was mit Nutzerdaten passiert und wie gemeldete Inhalte behandelt werden. Die Antworten sollten vor dem Einreichen feststehen.

Wenn du einen Agenten in dein bestehendes Produkt bringen willst, ist der erste Schritt fast immer derselbe: eine Aufgabe auswählen und prüfen, welche vorhandenen Funktionen dafür als Werkzeug taugen. So arbeite ich dabei.

Häufige Fragen