Das Prinzip: die Naht gehört uns, die Motoren sind gemietetThe principle: own the seam, rent the engines#
Alles, was man kaufen kann — Spracherkennung, Sprachausgabe, das Sprachmodell, der Medientransport — sitzt hinter einer schmalen, selbst definierten Schnittstelle. Die Schichten, die dem Geschäft gehören, kennen keinen einzigen Anbieter.Everything that can be bought — speech recognition, speech synthesis, the language model, the media transport — sits behind a narrow interface we define. The layers the business owns import no vendor code at all.
Die Naht liegt genau eine Schicht über den Anbietern.The seam sits exactly one layer above the vendors.
Widgets (Chat · Sprache) ← Kundin / customer
Konsolen (Betrieb · Wissen · Verwaltung)
API — versionierte REST + WS + Webhooks
──────────────────────────────────────────────
EIGEN: Orchestrator · Compliance · Sprachpipeline · ERP
contracts.py — die Naht / the seam
──────────────────────────────────────────────
GEMIETET: LLM · STT · TTS · Realtime · Transport
jeweils mit Mock — überall die VoreinstellungDas ist keine Architektur-Ästhetik, sondern ein Verhandlungsargument. Ein Anbieterwechsel ist eine Konfigurationsänderung. Deshalb läuft die gesamte Plattform auch ohne einen einzigen Schlüssel: die Voreinstellung überall ist der Mock.
This is not architectural taste, it is negotiating position. Switching provider is a configuration change. It is also why the whole platform runs with no credentials at all: the default everywhere is the mock.
MandantTenant#
Ein Mandant ist ein Kunde der Plattform: eigene Konfiguration, eigene Zugangsdaten, eigenes Wissen, eigene Gespräche. Alles, was das System liest oder schreibt, ist auf genau einen Mandanten begrenzt.A tenant is one customer of the platform: its own configuration, credentials, knowledge and conversations. Everything the system reads or writes is scoped to exactly one tenant.
Die Mandanten-Kennung ist nie eine Berechtigung. Der Mandant wird aus dem bereits geprüften Zugang abgeleitet — aus dem signierten Cookie oder dem API-Schlüssel — niemals aus einem Feld, das der Aufrufer selbst setzt.
A tenant id is never an authorisation. The tenant is derived from the already-authenticated credential — the signed cookie or the API key — never from a field the caller controls.
Die Kennung wird streng geprüft: Kleinbuchstaben, Ziffern, einfache Bindestriche, höchstens 63 Zeichen. Sie wird zu einem Verzeichnisnamen und zu einem DNS-Label, und diese Enge macht ../ und absolute Pfade nicht etwa gefiltert, sondern nicht darstellbar.The id is strictly validated: lowercase, digits, single hyphens, at most 63 characters. It becomes a directory name and a DNS label, and that narrowness makes ../ and absolute paths not filtered but unrepresentable.
GesprächConversation#
Ein Gespräch ist ein durchgehender Kontakt über einen Kanal — Telefon, Chat oder E-Mail — mit einer Rolle, einer Sprache und einem Verlauf. Es trägt zwei Bewertungen, die man nicht verwechseln darf.A conversation is one continuous contact over a channel — phone, chat or email — with a role, a language and a transcript. It carries two readings, and confusing them is a mistake.
| AnzeigeReading | BeantwortetAnswers | WorausFrom |
|---|---|---|
| Zustand (grün/gelb/rot)Health (green/amber/red) | Braucht dieses Gespräch *mich*?Does this conversation need *me*? | Antwortzeiten, Mühe des Agenten, blockierte FreigabenResponse times, agent effort, blocked approvals |
| Stimmung (−2 … +2)Mood (−2 … +2) | Wie geht es der *Kundin*?How is the *customer* doing? | Wortwahl (lexical) oder ein Modell (model)Word choice (lexical) or a model (model) |
Warum getrennt: Wer ruhig auf eine Freigabe wartet, verliert 40 Zustandspunkte und ist trotzdem entspannt. Ein einziger Wert würde beides mitteln und beide Fragen falsch beantworten.
Why separate: someone waiting calmly on an approval loses 40 health points and is still perfectly relaxed. A single number would average the two and answer both questions wrongly.
Eine leere Stimmung heißt es wurde noch nichts gesagt — das ist nicht dasselbe wie neutral, und die Oberfläche zeigt den Unterschied.An empty mood means nothing has been said yet — which is not the same as neutral, and the interface shows the difference.
Wissenseintrag: zwei Etiketten entscheiden allesKnowledge record: two labels decide everything#
Jeder Eintrag trägt zwei unabhängige Etiketten. Sie zu verwechseln ist der Fehler, der zählt.Every record carries two independent labels. Confusing them is the failure that matters.
| EtikettLabel | EntscheidetDecides | WerteValues |
|---|---|---|
| TypType | *wie es wirkt**how it acts* | fact wird nachgeschlagen · behaviour wird in den Prompt kompiliert · guide wird zu Handbüchern · source nur Herkunftfact is retrieved · behaviour is compiled into the prompt · guide renders to manuals · source is provenance only |
| Autorität × ZielgruppeAuthority × audience | *wie es verwendet werden darf**how it may be used* | official zitierfähig · internal verbindlich · sales Überzeugung · context nie behaupten · signal nur destillierenofficial citable · internal authoritative · sales persuasion · context never asserted · signal distil only |
Eine Wettbewerbsanalyse ist context, ein mitgeschnittenes Gespräch ist signal: beide dürfen einer Kundin nie als Tatsache gesagt werden, egal wie gut die Suche sie findet.A competitor analysis is context, a harvested transcript is signal: neither may ever be stated to a customer as fact, however well retrieval finds it.
Vertrauen kommt aus der Quelle, nie aus der Formulierung. Ein autoritativ klingendes Fremddokument bleibt context. Die Einstufung darf die Zielgruppe verengen, aber niemals über das hinaus erweitern, was die Quelle erlaubt.
Trust comes from the source, never from the prose. An authoritative-sounding third-party document is still context. Classification may narrow the audience but can never widen it past what the source kind allows.
Lebenszyklus eines EintragsA record's lifecycle#
Entwurf ──→ geprüft ──→ veröffentlicht ──→ stillgelegt draft ──→ verified ─→ published ──→ retired ↑ │ │ └───────────┴─────────────┘ eine Bearbeitung setzt zurück / editing re-drafts
draft → publishedist illegal. Nichts erreicht die Produktion ohne die Prüfung und einen Menschen.draft → publishedis illegal. Nothing reaches production without the verifier and a human.- Eine Bearbeitung setzt einen veröffentlichten Eintrag zurück in den Entwurf — was live ist, bleibt nicht versehentlich live, während es umgeschrieben wird.Editing a published record re-drafts it — what is live does not stay live by accident while it is being rewritten.
- Veröffentlichen erhöht die Version und stempelt, wer freigegeben hat. Eine veröffentlichte Version ist damit ein Stand, auf den zurückgerollt werden kann.Publishing bumps the version and stamps the approver, so a published version is a unit that can be rolled back to.
Veröffentlicht heißt nicht erreichbar. Ein Eintrag mit der Zielgruppe internal wird in einem Kundengespräch nie gezeigt — er ist live und trotzdem unsichtbar. Wenn der Agent eine Antwort „nicht kennt", die es offensichtlich gibt: hier zuerst nachsehen.
Published does not mean reachable. A record whose audience is internal is never shown in a customer conversation — it is live and still invisible. When the agent "does not know" an answer that obviously exists, look here first.
Freigabe und regierte SchreibvorgängeApproval and governed writes#
Agenten ändern keine CRM-Daten. Sie schlagen vor; ein Gate schreibt, staffelt nach Risiko und protokolliert. Alles, was Geld bewegt oder unumkehrbar ist, wartet auf einen Menschen.Agents do not mutate CRM records. They propose; a gate commits, tiers by risk and audits. Anything that moves money or cannot be undone waits for a human.
Während eine Freigabe aussteht, wartet der Agent blockierend. Er rät nicht weiter und sagt der Kundin nichts zu, was noch niemand entschieden hat.While an approval is pending the agent blocks. It does not guess onward, and it promises the customer nothing nobody has decided yet.
- SchwelleThreshold
- Pro Mandant einstellbarer Betrag, ab dem freigegeben werden muss.A per-tenant amount above which approval is required.
- Immer-FreigabeAlways-approve
- Bestimmte Aktionen brauchen unabhängig vom Betrag eine Freigabe.Certain actions require approval regardless of amount.
- WiderspruchOpt-out
- Die eine Ausnahme: ein Widerspruch im Gespräch wird sofort und ungeprüft ausgeführt und landet auf der Sperrliste.The one exception: an in-call opt-out commits instantly and ungated and lands on the suppression list.
Warum der Widerspruch nicht wartet: Eine Freigabe, die eine Bitte um Ruhe verzögert, ist genau der Fall, in dem Warten selbst der Schaden ist.
Why opt-out does not wait: an approval queue that delays someone's request to be left alone is precisely the case where the waiting is itself the harm.
LückeGap#
Jedes Mal, wenn der Agent nichts findet, wird die Frage mitgeschrieben — im Wortlaut der Kundin. Das ist keine Fehlerliste, sondern die ehrlichste Produktrückmeldung im Haus.Every time the agent finds nothing, the question is logged — in the customer's own words. This is not an error log; it is the most honest product feedback in the building.
- Sortiert nach betroffenen Gesprächen, nicht nach Anzahl der Fragen. Wer achtmal nachfragt, ist *eine* fehlende Antwort, nicht acht — sonst stünde die genervteste Person oben statt des häufigsten Problems.Sorted by conversations affected, not by question count. Someone asking eight times is *one* missing answer, not eight — otherwise the most frustrated person outranks the most common problem.
- Gruppiert nach Wortüberschneidung, nicht nach Bedeutung. Lieber zu wenig zusammengefasst als zu viel: eine aufgeteilte Zeile sieht man, eine überzusammengefasste versteckt eine fehlende Antwort in einer, die erledigt aussieht.Clustered by word overlap, not meaning. Better to under-merge than over-merge: a split row is visible, an over-merged one hides a missing answer inside one that looks handled.
KurzglossarShort glossary#
- Rolle (Agent)Role (agent)
- Welche Aufgabe der Agent in einem Gespräch hat —
A1_reception,A2_support,A3_billing,A4_telesales. Bestimmt Werkzeuge und Tempo.What job the agent is doing in a conversation —A1_reception,A2_support,A3_billing,A4_telesales. Determines tools and pace. - BeobachtenWatching
- Verantwortlich dafür, es zu bemerken. Der Agent spricht weiter.Being responsible for noticing. The agent keeps speaking.
- ÜbernehmenTakeover
- Sie sprechen jetzt selbst. Der Agent verstummt, die Leitung bleibt bestehen.You are speaking now. The agent goes silent, the line stays up.
- Golden-GateGolden gate
- Die Prüfung, dass eine Veröffentlichung den Agenten nicht schlechter macht. Toleranz 98 %, nicht 100 %.The check that a publish does not make the agent worse. Tolerance is 98%, not 100%.
- SperrlisteSuppression list
- Wer nicht kontaktiert werden will. Erkennt
+49 331 5512345und0331 5512345als dieselbe Person.People who asked not to be contacted. Recognises+49 331 5512345and0331 5512345as the same person. - EinbettungsschlüsselEmbed key
- Der öffentliche Schlüssel im Widget (
acp_pk_…). Er kann nur ein Gespräch beginnen, und nur von der eingetragenen Domain aus. Kein API-Schlüssel.The public key in the widget (acp_pk_…). It can only start a conversation, and only from the registered origin. Not an API key.