Wie die KI auf dieser Seite funktioniert: Ein Mastra-Production-Teardown

Der Assistent, mit dem du sprichst, ist die Demo

Die meisten Agenturen zeigen dir einen Chatbot-Screenshot. Der KI-Assistent auf dieser Seite ist das echte System, in Produktion, gebaut auf Mastra. Dieser Guide öffnet es. Kein Diagramm-Theater, nur die Architektur, die Tradeoffs und die Teile, die wirklich zählen, wenn ein KI-Feature echten Traffic überleben muss.

Die Erkenntnis, die die meisten Teams verpassen: Das Sprachmodell macht vielleicht zehn Prozent eines Produktions-KI-Assistenten aus. Die anderen neunzig Prozent sind Routing, Tools, State, Locale, Security und die langweiligen Zustellungsgarantien, die entscheiden, ob ein Lead je einen Menschen erreicht. Das allgemeine Pattern haben wir in Vom KI-Prototyp zur Produktion behandelt. Das hier ist der konkrete Build.

Die Form des Systems

Der Assistent ist eine Reihe von Mastra-Agenten, jeder mit einer engen Aufgabe, exponiert über Next.js-API-Routes:

• quoteAgent: der konversationelle Assistent auf den Quote- und Kontaktflächen. Er beantwortet Fragen zu Services, qualifiziert auf natürliche Weise und erfasst Leads.
• chatbotAgent: ein leichtgewichtiger Assistent für die interaktive Demo.
• visionAgent, voiceAgent, analyticsAgent: fokussierte Agenten hinter dem Demo-Playground.

Jeder Agent ist eine schlichte Deklaration: ein Name, ein Satz Instruktionen, ein Modell und die Tools, die er aufrufen darf. Die Modell-ID ist in einem Modul zentralisiert, sodass eine Änderung über jeden Agenten hinweg eine einzeilige Bearbeitung plus ein Deployment ist, kein Search-and-Replace über die gesamte Codebasis.

export const quoteAgent = new Agent({
  name: "quoteAgent",
  instructions: `...`,
  model: MODEL,
  tools: { submitProposal, scheduleCall, draftEmail, sendSummary },
});

Diese Struktur ist der Punkt. Der Agent enthält keine Business-Logik. Er entscheidet, welches Tool wann aufgerufen wird. Die Tools enthalten die Logik.

Tool Calling ist, wo die Arbeit passiert

Ein Chat, der nur Text zurückgibt, ist ein Spielzeug. Der Quote-Agent hat vier Tools, und die Instruktionen sind so geschrieben, dass er sie in dem Moment aufruft, in dem er die erforderlichen Felder hat, ohne den User um Erlaubnis zu fragen, um fortzufahren:

• submitProposal: einen Projekt-Lead erfassen (Name, E-Mail, Zusammenfassung).
• scheduleCall: einen Call mit dem Team buchen.
• sendSummary: eine Zusammenfassung des Gesprächs per E-Mail schicken.
• draftEmail: eine E-Mail vorbereiten, die das Team prüft.

Die Disziplin, die das nutzbar macht, steckt im Prompt: die minimal erforderlichen Felder sammeln, dann handeln. Keine "Soll ich fortfahren?"-Schleifen, keine leeren Bestätigungen. Wenn der User einen Namen, eine E-Mail und eine Projektzusammenfassung gegeben hat, feuert das Proposal-Tool. Der User bekommt ein klares Ergebnis, keine Sackgasse.

Die Locale lebt im Runtime-Kontext, nicht im Prompt

Diese Seite erscheint in fünf Sprachen: Englisch, Deutsch, Französisch, Spanisch und Arabisch. Der Assistent muss in der Sprache des Besuchers antworten und das Register respektieren, formelles Sie im Deutschen zum Beispiel, sowie Rechts-nach-links für Arabisch.

Der falsche Weg dafür ist, die Locale in den System-Prompt einzubacken und einen Prompt pro Sprache neu zu bauen. Der richtige Weg ist Runtime-Kontext. Jede Anfrage trägt die Locale, aufgelöst aus einem expliziten Wert, einem x-i18n-locale-Header oder dem Accept-Language-Header, und der Agent liest sie zur Generierungszeit:

const runtimeContext = new RuntimeContext();
if (finalLocale) runtimeContext.set("locale", finalLocale);
runtimeContext.set("requestId", requestId);

Ein Agent, ein Satz Instruktionen, fünf Sprachen. Dieselbe Request-ID fließt durch die Logs, sodass ein einzelnes Gespräch end to end nachvollzogen werden kann.

State, der degradiert statt zu brechen

Der Conversation-Storage nutzt LibSQL, wenn eine Datenbank-URL konfiguriert ist, und fällt auf einen In-Memory-Store zurück, wenn nicht. Der Import ist lazy und in ein try and catch gewickelt, sodass eine fehlende optionale Dependency den Assistenten nie lahmlegt. Er läuft einfach ohne dauerhafte Historie.

Das ist ein wiederkehrendes Prinzip über das System hinweg: Optionale Infrastruktur degradiert zu einem sicheren Default, statt zu werfen. Aggregation, die eine Quelle nicht erreicht, gibt leer zurück. Der Assistent, der eine Datenbank nicht erreicht, antwortet weiter. Nichts, was dem User zugewandt ist, hängt davon ab, dass ein optionaler Service vorhanden ist.

Die Security-Schicht um jede Anfrage

Das Modell ist der einfache Teil. Die Request-Grenze ist, wo Produktions-KI-Features Schaden nehmen. Jeder Assistenten-Call durchläuft dieselben Gates, bevor ein einziges Token generiert wird:

1. Methoden- und Input-Validierung: nur POST, Input-Länge begrenzt, fehlerhafte Bodies werden mit einem strukturierten Fehler und einer Request-ID abgewiesen.
2. Rate Limiting: Limits pro Anfrage, sodass ein einzelner Client das Inference-Budget nicht leersaugen kann.
3. Origin- und CSRF-Verifizierung: Browser-Calls müssen von einem erlaubten Origin kommen und ein gültiges CSRF-Token tragen. Das Token wird als Cookie gesetzt und bei jedem mutierenden Call geprüft.
4. Interne Autorisierung: Server-zu-Server-Calls von unserem eigenen Backend überspringen die Browser-Checks über einen expliziten internen Auth-Pfad, nie über ein implizites Bypass.

Diese sind nicht KI-spezifisch. Es sind dieselben Gates, die jeder ernsthafte Endpoint braucht. Der Fehler, den Teams machen, ist, eine KI-Route als besonders zu behandeln und sie zu überspringen. Ein LLM-Endpoint ist immer noch ein Endpoint, und er gibt bei jedem Call Geld aus, was das Rate Limit ebenso zu einer Kostenkontrolle macht wie zu einer Sicherheitskontrolle.

Kein stiller Lead-Verlust

Ein Lead, den die KI erfasst, das System aber verliert, ist schlimmer als gar keine KI. Deshalb werden Leads in den Log-Stream journaled, bevor die Zustellung versucht wird, und Zustellungsfehler werden explizit geloggt statt verschluckt. Wenn ein E-Mail-Provider ausfällt, existiert der Lead trotzdem im Record und kann wiederhergestellt werden. Der Erfassungspfad und der Zustellungspfad sind bewusst entkoppelt, denn das Teure am Verlust ist die Absicht, nicht die E-Mail.

Streaming, weil Latenz ein Feature ist

Antworten streamen Token für Token, statt zu blockieren, bis die vollständige Antwort fertig ist. Auf einer Sales-Fläche ist gefühlte Latenz der Unterschied zwischen einem Besucher, der wartet, und einem, der geht. Streaming wird in einem kleinen dedizierten Helper gehandhabt, sodass jede Agenten-Route dasselbe Verhalten bekommt, ohne die Plumbing zu wiederholen.

Was wir bewusst nicht gebaut haben

Gute Architektur ist auch eine Liste von Dingen, zu denen du Nein gesagt hast.

• Kein Allzweck-Assistent. Der Quote-Agent ist auf das Oronts-Geschäft beschränkt. Bitte ihn, FizzBuzz zu schreiben oder Buchstaben in einem Wort zu zählen, und er lehnt ab und lenkt zurück. Ein Sales-Assistent, der Trivia beantwortet, ist ein Risiko, kein Feature, und ein offen gehaltener Assistent ist eine offen gehaltene Angriffsfläche.
• Keine erfundenen Zahlen. Der Assistent nennt veröffentlichte Preisbänder wortwörtlich und konstruiert nie einen projektspezifischen Kostenvoranschlag. Planungsspannen kommen von einem Senior Engineer nach dem Scoping, nie von einem Modell, das hilfreich sein will.
• Keine Versprechen. Er bestätigt nie Machbarkeit, legt sich nie auf eine Timeline fest und garantiert nie ein Ergebnis. Er sammelt Informationen und übergibt an Menschen.

Diese Constraints leben in den Instruktionen, und sie sind die wichtigsten Zeilen im ganzen System. Die Fähigkeit eines Modells ist durch die Guardrails um es herum begrenzt, und auf einer kommerziellen Seite sind die Guardrails das Produkt.

Die Erkenntnis für deinen eigenen Build

Wenn du ein KI-Feature in Produktion bringst, ist die Modellwahl die Entscheidung, die du am wenigsten bereuen wirst. Steck deinen Aufwand in die Grenze: Validierung, Rate Limiting, Locale, graceful Degradation und einen Erfassungspfad, der die Absicht nie verliert. Frameworks wie Mastra geben dir die Agenten- und Tool-Primitive, damit du diesen Aufwand dort investieren kannst, wo er sich auszahlt.

Für die umgebenden Patterns schau dir unsere Guides zu Multi-Agenten-Architektur, KI-Observability und Human-in-the-Loop-KI an. Wenn du diese Art System in dein eigenes Produkt eingebaut haben willst, starte ein Gespräch oder fordere ein Angebot an.