Integrationsunterlagen · v0.1.0 Integration material · v0.1.0

Was Sie bereitstellen müssen What you need to provide

Eine Checkliste für den Tag, an dem Sie anfangen. Sie ist bewusst zweigeteilt: oben steht, was Sie zum Starten brauchen, unten, was Sie zum Livegehen brauchen — und dazwischen liegt eine Menge Arbeit, die Sie ohne einen einzigen Zugangsschlüssel erledigen können. A checklist for the day you begin. It is deliberately split in two: what you need to start comes first, what you need to go live comes second — and a great deal of work sits in between that you can do without a single credential.

Der wichtigste Satz auf dieser SeiteThe most important sentence on this page

LaufzeitRuntime

Was auf dem Rechner liegen muss What has to be on the machine

• Python 3.11 oder neuerPython 3.11 or newer
  Als Mindestversion im Projekt festgelegt. Die Laufzeitabhängigkeiten sind bewusst wenige und alle in einer Lock-Datei fixiert: Pydantic, FastAPI, Uvicorn, HTTPX, python-dotenv, argon2-cffi und structlog. Jedes Anbieter-SDK ist ein optionales Extra, das nur sein eigener Adapter lädt.Declared as the project's minimum. Runtime dependencies are deliberately few and all pinned in a lock file: Pydantic, FastAPI, Uvicorn, HTTPX, python-dotenv, argon2-cffi and structlog. Every vendor SDK is an optional extra that only its own adapter loads.
• Eine Container-LaufzeitA container runtime
  Der mitgelieferte Build ist zweistufig: ein Wheel wird gegen die Laufzeit-Lock-Datei gebaut und dann auf einem schlanken Basis-Image als Nicht-Root-Benutzer mit no-new-privileges ausgeführt. Der Healthcheck ruft /health mit Bordmitteln auf, damit kein zusätzliches Binary ins Image wandert. Der Compose-Stack startet ohne Zugangsdaten.The bundled build is two-stage: a wheel is built against the runtime lock file, then run on a slim base image as a non-root user with no-new-privileges. The healthcheck calls /health with the standard library, so no extra binary enters the image. The compose stack comes up with no credentials.
• Persistenter SpeicherPersistent storage
  Unter ACP_DATA_ROOT liegt je Mandant ein eigenes Verzeichnis mit Transkripten, Wissensregistry und Auswertungsläufen. Das ist ein echtes Dateisystem, kein Cache: was hier verschwindet, ist weg.Under ACP_DATA_ROOT each tenant gets its own directory holding transcripts, the knowledge registry and evaluation runs. This is a real filesystem, not a cache: what disappears here is gone.
• Ein Reverse-Proxy mit TLSA reverse proxy with TLS
  Die Anwendung spricht HTTP; Terminierung, Zertifikate und die Wahl, ob /docs und /openapi.json öffentlich sein sollen, liegen bei Ihnen. Für das Kunden-Widget brauchen Sie ohnehin HTTPS, sonst greift die Origin-Bindung nicht sinnvoll.The application speaks HTTP; termination, certificates and the decision whether /docs and /openapi.json should be public are yours. The customer widget needs HTTPS regardless, otherwise origin binding is not meaningful.

Erst beim LivegangOnly when going live

Zugangsdaten, und was jede einzelne freischaltet Credentials, and what each one unlocks

Jede Zeile schaltet unabhängig um. Es gibt keinen Stichtag, an dem alles gleichzeitig live gehen muss — Sie liefern einen Schlüssel, setzen eine Variable, und genau dieser eine Pfad verlässt die Mock-Welt. Each row flips independently. There is no cut-over day on which everything must go live at once — you supply a key, set a variable, and exactly that one path leaves the mock world.

Umgebungsvariablen · PlattformEnvironment variables · platform

Deploymentweite Haltung, einmal beim Start gelesen Deployment-wide posture, read once at boot

Diese Variablen gehören dem Deployment, nicht einem Mandanten. Sie entscheiden, ob überhaupt echte Engines gebaut werden dürfen und wer die Konsole betreten darf. These belong to the deployment, not to a tenant. They decide whether real engines may be constructed at all, and who may enter the console.

Umgebungsvariablen · MandantEnvironment variables · tenant

Je Mandant aufgelöst — im SaaS-Betrieb aus der Registry, nicht aus einer Datei Resolved per tenant — from the registry in SaaS, not from a file

Im Einzelmandanten-Betrieb kommen diese Werte aus der .env und beschreiben den Standardmandanten. Sobald mehrere Mandanten laufen, werden sie je Mandant aus einem expliziten Mapping aufgelöst — dieselben Namen, andere Quelle. In single-tenant operation these come from .env and describe the default tenant. Once several tenants run, they are resolved per tenant from an explicit mapping — same names, different source.

GeheimnisseSecrets

Die Datei-Konvention und vier Regeln, die zumachen statt aufmachen The file convention, and four rules that close rather than open

• 1 — Live ist der Normalfall, nicht die Ausnahme1 — Live is the default reading, not the exception
  Ein Deployment gilt als LIVE, außer ACP_ENV ist exakt mock, test oder ci. Die frühere Prüfung lautete „gleich live“ — und damit las sich ausgerechnet production als nicht live, was die Boot-Prüfung abschaltete, anonymen Admin-Zugang erlaubte, einen flüchtigen Signierschlüssel erzeugte und das Secure-Flag vom Sitzungscookie nahm. Die Beweislast liegt jetzt darauf, offline zu sein.A deployment counts as LIVE unless ACP_ENV is exactly mock, test or ci. The previous check was "equals live" — which made production, of all values, read as not live, disabling the boot check, permitting anonymous admin access, minting an ephemeral signing key and dropping Secure from the session cookie. The burden of proof is now on being offline.
• 2 — In live wird der Start verweigert, nicht improvisiert2 — In live the process refuses to start rather than improvise
  Beim Hochfahren werden ACP_CONSOLE_SECRET (mindestens 32 Byte) und ACP_INGEST_TOKEN verlangt. Es gibt keinen Entwicklungs-Rückfall und keinen „wenn nicht gesetzt, dann erlauben“-Zweig. Alle Probleme werden gesammelt und gemeinsam gemeldet, damit Sie ein kaputtes Deployment einmal reparieren und nicht die nächste fehlende Variable beim nächsten Neustart entdecken. Die Fehlermeldung zitiert Ihren eigenen ACP_ENV-Wert.At boot, ACP_CONSOLE_SECRET (at least 32 bytes) and ACP_INGEST_TOKEN are required. There is no development fallback and no "if unset, allow" branch. All problems are collected and reported together, so you fix one broken deployment instead of discovering the next missing variable on the next restart. The error quotes your own ACP_ENV value back at you.
• 3 — Anonymer Zugang wird in live abgelehnt3 — Anonymous access is refused in live
  ACP_ALLOW_ANON in einem live gewerteten Deployment führt zu einem Fehler, nicht zu einer stillen Nichtbeachtung. Eine stille Nichtbeachtung wäre schlimmer: Sie glauben, die Konsole sei offen, und sie ist es nicht — oder umgekehrt.ACP_ALLOW_ANON in a deployment that counts as live raises an error rather than being quietly ignored. Quiet ignoring would be worse: you believe the console is open when it is not — or the other way round.
• 4 — Ein fehlendes Token schließt den Endpunkt4 — A missing token closes the endpoint
  Ohne ACP_INGEST_TOKEN antwortet die Ingest-Brücke mit 503; ohne ACP_METRICS_TOKEN antwortet /metrics mit 503. Ein unkonfigurierter Endpunkt ist geschlossen und nicht ungeprüft. Wer die Metriken abgreifen will, muss das Token also bewusst setzen — das ist der Punkt.Without ACP_INGEST_TOKEN the ingest bridge answers 503; without ACP_METRICS_TOKEN, /metrics answers 503. An unconfigured endpoint is closed, not unchecked. Anyone who wants to scrape metrics must set the token deliberately — that is the point.

NetzwerkNetwork

Was hinaus darf, was herein muss What may go out, what has to come in

Was Sie auf keinen Fall tun dürfenWhat you must never do

Niemals einen API-Schlüssel in eine Webseite Never put an API key in a web page

<script src="https://acp.example/static/widget/acp-widget.js"
        data-key="acp_pk_..." data-lang="de" async></script>

Zwei weitere Dinge, die die Konsolen absichtlich nicht tun: kein Schreib-Zugangsdatum wird im localStorage abgelegt (dort wäre es unbegrenzt für jedes Skript der Origin lesbar, lange nachdem der Bediener weggegangen ist), und Modellausgabe wird im Widget über textContent gesetzt, nie über innerHTML — was ein Modell sagt, darf auf einer fremden Seite nicht ausführbar werden. Two more things the consoles deliberately do not do: no write credential is kept in localStorage (where it would stay readable by any script on the origin, indefinitely, long after the operator walked away), and model output in the widget is set via textContent, never innerHTML — what a model says must not become executable in someone else's page.

DatenschutzData protection

Transkripte sind personenbezogene Daten — behandeln Sie sie so Transcripts are personal data — treat them as such

• Was gespeichert wirdWhat is stored
  Gesprächstranskripte samt Zeitstempeln und Gesprächskennungen, die Wissensregistry als Markdown in Git, Auswertungsläufe sowie die technischen Zähler. Transkripte enthalten Kundengespräche und damit personenbezogene Daten; das steht auch im Code an der Stelle, an der sie geschrieben werden. Der Webhook-Umschlag trägt bewusst keine Inhalte, sondern Kennungen und Typen — wer Inhalte braucht, holt sie sich mit einer berechtigten Rückfrage.Conversation transcripts with timestamps and conversation ids, the knowledge registry as Markdown in Git, evaluation runs, and the technical counters. Transcripts contain customer conversations and therefore personal data; the code says so at the point where they are written. The webhook envelope deliberately carries no content, only ids and types — a receiver that needs content calls back for what it is entitled to.
• Wo es liegtWhere it lives
  Je Mandant unter einem eigenen Wurzelverzeichnis, abgeleitet aus dem geprüften Slug. Voreingestellte Region ist eu-central-1. Die Region ist eine Angabe der Konfiguration, keine Zauberei: Sie stellen sicher, dass Host, Datenbank und die gewählten Engines tatsächlich in der EU stehen — die Plattform hilft dabei, indem sie sensible Bahnen gar nicht erst hinauslässt.Per tenant under its own root directory, derived from the validated slug. The default region is eu-central-1. Region is a configuration statement, not magic: you are the one who ensures the host, the database and the chosen engines really sit in the EU — the platform helps by refusing to let sensitive lanes leave at all.
• Aufbewahrung ist Ihre EntscheidungRetention is your decision
  Die Plattform bringt keine automatische Löschfrist und keine Anonymisierung mit. Transkripte bleiben liegen, bis der Betreiber eine Regel setzt. Das ist bewusst offen gelassen, weil die richtige Frist vom Zweck abhängt — aber es heißt, dass Sie sie festlegen müssen, bevor echte Gespräche anfangen. Dasselbe gilt, wenn Sie Transkripte je für Training verwenden wollen: dann brauchen Sie zusätzlich Einwilligung und Anonymisierung.The platform ships no automatic deletion schedule and no anonymisation. Transcripts stay until the operator sets a rule. That is left open on purpose, because the right period depends on the purpose — but it means you must decide it before real conversations start. The same holds if you ever want to use transcripts for training: that additionally needs consent and anonymisation.
• Einwilligung und Offenlegung liefern Sie im WortlautYou supply the consent and disclosure wording
  Die Plattform erzwingt die Mechanik — die KI-Offenlegung kommt vom Server und kann von der einbettenden Seite nicht weggelassen werden, und ohne registrierte Einwilligung verweigert das Gate die Aufzeichnung. Den geprüften Text und die Auftragsverarbeitungsverträge mit den gewählten Anbietern bringen Sie mit.The platform enforces the mechanics — the AI disclosure is served by the server and cannot be omitted by the embedding page, and without registered consent the gate refuses to record. The reviewed wording and the data-processing agreements with your chosen providers are yours to bring.