Integrationsunterlagen · v0.1.0 · M1 abgeschlossen Integration material · v0.1.0 · M1 complete

Was die Plattform leistet What the platform does

ACP ist eine mandantenfähige Plattform für agentische Kundenkommunikation: Sprache und Chat, Deutsch und Englisch, Datenhaltung in der EU. Diese Seite beschreibt, was heute tatsächlich im Repository steht. Jede Zahl unten ist im Code nachprüfbar, und was fehlt, steht am Ende der Seite. ACP is a multi-tenant platform for agentic customer conversations: voice and chat, German and English, EU data residency. This page describes what is actually in the repository today. Every figure below is checkable against the code, and what is missing is listed at the end of the page.

Im ÜberblickAt a glance

Nachgezählt am Repository, nicht geschätzt: pytest -m "not live" meldet 840 bestandene Tests; contracts.py deklariert zwölf Protocols; build_v1_router() registriert dreizehn HTTP-Routen und einen WebSocket; das Language-Enum hat sieben Werte (DE, EN, IT, CS, SK, PL, FR) und das Compliance-Gate hält für jeden ein vollständiges Eröffnungsskript bereit. Die Konsolen und das Kunden-Widget selbst sind zweisprachig (DE/EN). Counted from the repository, not estimated: pytest -m "not live" reports 840 passing tests; contracts.py declares twelve Protocols; build_v1_router() registers thirteen HTTP routes and one WebSocket; the Language enum has seven members (DE, EN, IT, CS, SK, PL, FR) and the compliance gate carries a complete opening script for each. The consoles and the customer widget themselves ship DE + EN.

Die eine IdeeThe one idea

Die Naht besitzen, die Motoren mieten Own the seam, rent the engines

Jede Fähigkeit hat einen Mock, und der Mock ist überall der Standard. Ein falsch gesetzter Engine-Name für STT oder TTS fällt mit einer Warnung auf den Mock zurück, statt die Plattform zu stoppen; ein unbekannter Name wird abgelehnt. Every capability has a mock, and the mock is the default everywhere. A selected STT or TTS engine whose credential is missing falls back to the mock with a warning rather than crashing the platform; an unknown name is rejected outright.

Kanäle · Sprachen · DatenraumChannels · languages · residency

Sprache und Chat, und die Sensitivität entscheidet, wohin es geht Voice and chat, and sensitivity decides where the turn may go

MandantentrennungMulti-tenancy

Getrennt wird an der Datenschicht, nicht in der Anfrage Isolation is enforced at the data layer, never from the request

• Die Mandanten-ID ist keine BerechtigungA tenant id is never an authorisation
  Der Geltungsbereich kommt immer aus der bereits geprüften Anmeldung — dem signierten Cookie oder dem API-Schlüssel —, nie aus einem Feld, das der Aufrufer setzt. Tests belegen, dass ?tenant=, ?tenant_id= und X-Tenant-Id ignoriert werden.Scoping always derives from the already-authenticated credential — the signed cookie or the API key — never from a field the caller controls. Tests assert that ?tenant=, ?tenant_id= and X-Tenant-Id are ignored.
• Fremde Ressourcen sind 404, nie 403Another tenant's resource is 404, never 403
  Der Unterschied würde bestätigen, dass die Ressource existiert. Aus demselben Grund sind ein unbekannter und ein deaktivierter Mandant nicht unterscheidbar.The distinction would confirm that the resource exists. For the same reason, an unknown tenant and an inactive one are indistinguishable.
• Pfad-Ausbrüche sind nicht darstellbarPath escapes are unrepresentable
  Eine Mandanten-ID ist ein geprüfter DNS-tauglicher Slug, der zugleich Pfadsegment und DNS-Label ist. ../, absolute Pfade und Label-Spaltung werden bei der Konstruktion abgelehnt statt bei der Benutzung bereinigt; Pfade werden vor der Enthaltensprüfung aufgelöst, was auch Symlink-Ausbrüche schlägt.A tenant id is a validated DNS-safe slug that doubles as a path segment and a DNS label. ../, absolute paths and label splitting are rejected at construction rather than sanitised at use; paths are resolved before the containment check, which also defeats symlink escapes.

Mensch in der SchleifeHuman in the loop

Agenten schlagen vor, Menschen entscheiden Agents propose, humans decide

• FreigabeschwelleApproval threshold
  Alles oberhalb eines konfigurierten Betrags (ACP_APPROVAL_EUR, Standard 100 €) geht als Freigabeanfrage an die Aufsicht, bevor der Agent handelt. Der Schwellwert liegt in den Settings des Mandanten, ist also pro Kunde verschieden.Anything above a configured amount (ACP_APPROVAL_EUR, default €100) becomes an approval request to a supervisor before the agent acts. The threshold lives in the tenant's settings, so it differs per customer.
• Übernahme mitten im GesprächTakeover mid-call
  Eine Aufsicht kann jederzeit in ein laufendes Gespräch eintreten: AGENT → HANDING_OVER → HUMAN, und später zurück. Der Manager hält nur das Kontrollflag; die kaskadierte Pipeline verstummt, eine Realtime-Sitzung tritt über yield_to_human() zurück. Der Anrufer bleibt in derselben Leitung.A supervisor can step into a live conversation at any time: AGENT → HANDING_OVER → HUMAN, and back again later. The manager owns only the control flag; the cascaded pipeline falls silent, a realtime session steps back via yield_to_human(). The caller stays on the same line.
• Nie eine SackgasseNever a dead end
  Der Agent darf nicht mit „das weiß ich nicht“ enden. Die Rollen-Prompts verlangen stattdessen eine kurze Prüfung, eine Rücksprache oder einen zugesagten Rückruf — und eine leere Antwort ohne Text und ohne Werkzeugaufruf gilt der Eskalationslogik ausdrücklich als Sackgasse und wird an einen Menschen übergeben.The agent may not end on "I don't know". The role prompts require a short check, a callback or a promise to come back instead — and an empty response with no text and no tool call is treated by the escalation logic as an explicit dead end and handed to a human.

WissenKnowledge

Markdown in Git ist die Quelle der Wahrheit — alles andere ist abgeleitet Markdown in Git is the source of truth — everything else is derived

1. AufnehmenIngest
   normalisieren und das Original samt Herkunft behaltennormalise, and keep the original with its provenance
2. StrukturierenStructure
   nach Überschriften trennen, nie nach Zeichenzahl — ein Schnitt mitten in einer Einschränkung erzeugt eine Aussage, die schlicht falsch istsplit by heading, never by character count — a boundary mid-qualifier produces a fact that is simply wrong
3. KlassifizierenClassify
   Typ, Kategorie, Sprache, Publikum, Autoritättype, category, language, audience, authority
4. VerifizierenVerify
   jede Behauptung im Quelltext verankern; jede Zahl muss wörtlich vorkommen. Der Verifizierer ist bewusst lexikalisch und kein Modell — ein Modell, das die Ausgabe eines Modells prüft, teilt dessen Fehlermodi.ground every claim in the source text; every figure must appear verbatim. The verifier is deliberately lexical, not model-based — a model checking a model's output shares its failure modes.
5. FreigebenApprove
   ein Mensch, neben der Quelle. Absichtlich nicht automatisch.a human, beside the source. Deliberately not automatic.
6. VeröffentlichenPublish
   ein Commit, ein Neuaufbau — hinter dem Golden-Gateone commit, one rebuild — behind the Golden gate

Regierte SchreibvorgängeGoverned writes

Der Agent ändert keinen ERP-Datensatz — er schlägt ihn vor The agent never mutates an ERP record — it proposes one

• Vorschlag statt SchreibzugriffProposal instead of write access
  Jede Wirkung nach außen läuft über das ai_proposal-Tor, das nach Risiko staffelt, committet und protokolliert. Der Agent hat keinen direkten Schreibpfad in die Kundendaten.Every outward effect goes through the ai_proposal gate, which tiers by risk, commits and audits. The agent has no direct write path into customer records.
• Ausgehende Anrufe sind eine Warteschlange, kein WählautomatOutbound calling is a queue, not a dialler
  Autonomes Kaltakquise-Wählen ist nach § 7 UWG unzulässig. Das Kampagnenmodul wählt deshalb nie: es verwandelt eine Interessentenliste in Anruf-Vorschläge, die ein Mensch freigibt — und genau diese Freigabe ist die vom Gesetz verlangte Initiative, festgehalten mit Freigebendem und Zeitstempel. Erst danach wählt die Plattform, mit human_initiated=True.Autonomous cold dialling is unlawful under §7 UWG. So the campaign module never dials: it turns a prospect list into call proposals a human approves — and that approval is the initiation the law requires, recorded with the approver and a timestamp. Only then does the platform dial, with human_initiated=True.
• Widerspruch im Gespräch wirkt sofortIn-call opt-out is instant
  Der Widerspruch ist das eine Werkzeug, das nicht durch eine Freigabe muss: er committet sich selbst und landet auf der Sperrliste. Die Kampagnen-Warteschlange fragt diese Liste ab, bevor sie überhaupt etwas vorschlägt — abgemeldete Kontakte werden übersprungen und gemeldet, nie vorgeschlagen.Opt-out is the one tool that does not pass through an approval: it auto-commits and lands the contact on the do-not-call list. The campaign queue consults that list before proposing anything at all — opted-out contacts are skipped and reported, never proposed.

RegulatorikCompliance

Die Offenlegung kommt vom Server, damit sie niemand weglassen kann The disclosure comes from the server, so nobody can leave it out

• KI-Offenlegung, EU-KI-Verordnung Art. 50AI disclosure, EU AI Act Art. 50
  Der Hinweistext wird vom Server ausgeliefert und als Eröffnungsnachricht angezeigt, bevor der Besucher tippen kann. Die einbettende Seite kann ihn nicht herausredigieren, denn sie erhält ihn nicht als eigenen Text, sondern als Teil der Sitzungsantwort. Für die Vorschau gibt es einen eigenen Endpunkt. Auch am Telefon gilt: jedes Eröffnungsskript des Compliance-Gates nennt ausdrücklich, dass hier eine KI und kein Mensch spricht.The disclosure is served by the server and rendered as the opening message before the visitor can type. The embedding page cannot edit it out, because it never receives it as its own text — it arrives as part of the session response. A separate endpoint exists to preview it. The same holds on the phone: every opening script in the compliance gate states plainly that this is an AI and not a human.
• Aufzeichnung braucht EinwilligungRecording requires consent
  § 201 StGB und DSGVO Art. 6/7: Das Gate verweigert die Aufzeichnung, bis eine Einwilligung registriert ist. Das Eröffnungsskript fragt sie ab und weist auf das jederzeitige Widerspruchsrecht hin.§201 StGB and GDPR Art. 6/7: the gate refuses recording until consent has been registered. The opening script asks for it and points out the right to object at any time.
• Stimmklonen ist abgeschaltetVoice cloning is switched off
  Das Klonen einer Stimme ist in der Konsole deaktiviert und als das gekennzeichnet, was es verlangt: eine ausdrückliche, aufgezeichnete Einwilligung der sprechenden Person. Es ist kein Schalter, den ein Mandant im Vorbeigehen umlegt.Cloning a voice is disabled in the console and labelled with what it requires: explicit, recorded consent from the person whose voice it is. It is not a switch a tenant flips in passing.

BeobachtbarkeitObservability

EhrlichkeitHonesty

Was noch nicht fertig ist What is not done yet

Alles Obenstehende ist heute grün — auf Mocks. Das Folgende ist es nicht, und es steht hier, weil eine Integrationsunterlage, die Lücken verschweigt, beim ersten echten Anruf auffliegt. Everything above is green today — on mocks. The following is not, and it is listed here because integration material that hides its gaps is found out on the first real call.