Symptom → UrsacheSymptom → cause#
Diese Tabelle enthält die Fehler, die beim Aufbau dieses Systems tatsächlich passiert sind — nicht die, die man sich ausdenken würde.This table holds the failures that actually happened while building this system — not the ones you would invent.
| SymptomSymptom | Fast immerAlmost always | PrüfenCheck |
|---|---|---|
| Nach jedem Neustart sind alle abgemeldetEveryone is logged out after each restart | ACP_CONSOLE_SECRET ist nicht gesetzt — der Dienst erzeugt ein flüchtiges Geheimnis.ACP_CONSOLE_SECRET is unset — the service generates an ephemeral one. | Das Protokoll beim Start sagt es ausdrücklich.The startup log says so explicitly. |
| Niemand kann sich anmelden, Dienst „nicht gesund"Nobody can sign in, service "not healthy" | Die Kontodatei ist für den Dienstbenutzer unlesbar. Er scheitert geschlossen.The account file is unreadable to the service user. It fails closed. | Eigentümer und Rechte der Datei.File owner and permissions. |
| Der Agent „kennt" eine Antwort nicht, die es gibtThe agent "does not know" an answer that exists | Der Eintrag ist internal, oder seine Autorität ist context/signal.The record is internal, or its authority is context/signal. | Zielgruppe und Autorität, in dieser Reihenfolge.Audience and authority, in that order. |
| Wir haben Wissen eingepflegt, nichts ändert sichWe entered knowledge, nothing changed | Es sind Entwürfe. Nur Veröffentlichtes steuert einen Agenten.They are drafts. Only published records steer an agent. | Der Bestand nach Status auf der Wissensübersicht.Stock by status on the knowledge overview. |
| Der Anrufpool ist leer, obwohl Kontakte da sindThe call pool is empty although contacts exist | Kampagne im Entwurf, außerhalb der Anrufzeiten, oder keine datierte Vorbeziehung.Campaign is a draft, outside calling hours, or no dated prior relationship. | Jede gesperrte Zeile nennt ihren Grund.Every blocked row states its reason. |
| Ein Dokument wird beim Hochladen abgelehntA document is rejected on upload | Es ist ein Scan ohne Textebene. Abgelehnt statt halb übernommen.It is a scan with no text layer. Rejected rather than half-ingested. | Die Meldung nennt OCR ausdrücklich.The message names OCR explicitly. |
| Eine URL wird nicht geholtA URL is not fetched | Sie zeigt ins eigene Netz oder hinter einen Login. Beides wird grundsätzlich verweigert.It points inside your own network, or behind a login. Both are refused outright. | Öffentlich erreichbar? Ohne Anmeldung?Publicly reachable? Without signing in? |
| Links im Handbuch oder in der Doku enden im NichtsLinks in the handbook or docs go nowhere | Die Seite wurde ohne abschließenden Schrägstrich aufgerufen; relative Links lösen dann gegen die Wurzel auf.The page was opened without a trailing slash; relative links then resolve against the site root. | /handbook leitet auf /handbook/ um — dem Redirect folgen./handbook redirects to /handbook/ — follow the redirect. |
KonfigurationConfiguration#
| VariableVariable | BedeutungMeaning |
|---|---|
ACP_ENVACP_ENV | mock oder eine echte Betriebsart. mock braucht keine Zugangsdaten.mock or a real mode. mock needs no credentials. |
ACP_CONSOLE_SECRETACP_CONSOLE_SECRET | Signiert Sitzungs-Cookies. Ohne ihn überlebt keine Anmeldung einen Neustart.Signs session cookies. Without it no session survives a restart. |
ACP_CONSOLE_USERSACP_CONSOLE_USERS | Pfad zur Kontodatei. Wird bei Änderung neu gelesen, ohne Neustart.Path to the account file. Re-read on change, with no restart. |
ACP_DATA_ROOTACP_DATA_ROOT | Wurzel aller Mandantendaten. Jeder Mandant bekommt darunter sein eigenes Verzeichnis.Root of all tenant data. Each tenant gets its own directory beneath it. |
ACP_REGIONACP_REGION | Datenresidenz, voreingestellt eu-central-1.Data residency, eu-central-1 by default. |
ACP_CONFIDENTIAL_FRONTIERACP_CONFIDENTIAL_FRONTIER | Erlaubt vertraulichem Verkehr ein Frontier-Modell — nur bei EU-Region und Zero-Retention.Allows confidential traffic to a frontier model — only on an EU-region, zero-retention posture. |
Die Konfiguration wird pro Mandant aufgelöst und ist eingefroren. Kein Anfragebearbeiter kann verändern, was eine gleichzeitige Anfrage sieht — das ist der Grund, warum Mandantentrennung überhaupt haltbar ist.
Configuration is resolved per tenant and frozen. No request handler can mutate what a concurrent request sees — which is why tenant isolation holds at all.
RollenmatrixRole matrix#
| AktionAction | viewerviewer | supervisorsupervisor | leaderleader | adminadmin |
|---|---|---|---|---|
| Fläche und Verläufe lesenRead floor and transcripts | jayes | jayes | jayes | jayes |
| Übernehmen und sprechenTake over and speak | neinno | jayes | jayes | jayes |
| Freigaben entscheidenDecide approvals | neinno | jayes | jayes | jayes |
| Wissen anlegen und freigebenCreate and release knowledge | neinno | jayes | jayes | jayes |
| Konten des eigenen Teams anlegenCreate own-team accounts | neinno | neinno | jayes | jayes |
| Mandant, Schlüssel, AbrechnungTenant, keys, billing | neinno | neinno | neinno | jayes |
API in KürzeThe API in brief#
Versioniert im Pfad: ein brechender Wechsel erscheint als /v2, bestehende Anbindungen laufen weiter. Innerhalb von v1 gilt: Felder kommen hinzu, sie verschwinden nie und werden nie umgewidmet.Versioned in the path: a breaking change ships as /v2 and existing integrations keep working. Within v1 the promise is: fields may be added, never removed or repurposed.
Ein Schlüssel gehört einem System. Eine Sitzung gehört einer Person. Keines funktioniert auf der Fläche des anderen.A key belongs to a system. A session belongs to a person. Neither works on the other's surface.
Authorization: Bearer acp_sk_<key-id>_<secret>
| EndpunktEndpoint | ZweckPurpose |
|---|---|
GET /v1/healthGET /v1/health | Der einzige Endpunkt ohne Authentifizierung.The only unauthenticated endpoint. |
GET /v1/conversationsGET /v1/conversations | Gespräche dieses Mandanten. Der Mandant kommt aus dem Schlüssel, nie aus einem Parameter.This tenant's conversations. The tenant comes from the key, never from a parameter. |
POST /v1/conversations/{id}/messagesPOST /v1/conversations/{id}/messages | Nachricht senden, Antwort des Agenten erhalten.Send a message, get the agent's reply. |
POST /v1/knowledgePOST /v1/knowledge | Erzeugt einen Entwurf. Einen Veröffentlichen-Endpunkt gibt es nicht.Creates a draft. There is no publish endpoint. |
GET /v1/knowledge-searchGET /v1/knowledge-search | Sucht wie ein Kundengespräch — internes Material kommt nie zurück.Retrieves as a customer conversation would — internal material never comes back. |
POST /v1/webhooksPOST /v1/webhooks | Endpunkt registrieren; das Signaturgeheimnis wird genau einmal zurückgegeben.Register an endpoint; the signing secret is returned exactly once. |
Ein Gespräch eines anderen Mandanten antwortet 404, nie 403. Beim WebSocket reist der Schlüssel als Parameter, weil Browser keine Header setzen können — er wird geprüft, bevor die Verbindung angenommen wird.
Another tenant's conversation answers 404, never 403. On the WebSocket the key travels as a parameter because browsers cannot set headers — it is validated before the socket is accepted.
Das Widget einbettenEmbedding the widget#
<script src="https://acp.example/static/widget/acp-widget.js"
data-key="acp_pk_..." data-lang="de" async></script>- Es trägt einen öffentlichen Einbettungsschlüssel, nie einen API-Schlüssel. Ihn zu besitzen erlaubt genau eines: ein Gespräch zu beginnen, und nur von der eingetragenen Domain.It carries a public embed key, never an API key. Holding it permits exactly one thing: starting a conversation, and only from the registered origin.
- Shadow DOM — die einbettende Seite kann das Widget nicht kaputtstylen, und das Widget nicht die Seite.Shadow DOM — the host page cannot break the widget's styling, and the widget cannot restyle the host.
- Offenlegung zuerst — serverseitig geliefert und angezeigt, bevor jemand tippen kann.Disclosure first — server-supplied and shown before anyone can type.
textContent, nieinnerHTML— Modellausgabe darf in einer fremden Seite nicht ausführbar werden.textContent, neverinnerHTML— model output must not become executable in someone else's page.
Die Farbgebung kommt aus --acp-*-Variablen, die durch die Shadow-Grenze vererbt werden. White-Labelling ist eine Token-Überschreibung, nie ein CSS-Umbau.Colour comes from --acp-* variables, which inherit through the shadow boundary. White-labelling is a token override, never a CSS rewrite.
WeiterlesenFurther reading#
- IntegrationsmaterialIntegration material
- /integration/ — Funktionsumfang, Voraussetzungen, Fahrplan./integration/ — features, requirements, roadmap.
- VertrauensseiteTrust page
- /trust/ — öffentlich, für Kundinnen und Aufsicht./trust/ — public, for customers and regulators.
- Dieses Handbuch als MarkdownThis handbook as Markdown
docs/handbook/de/unddocs/handbook/en/— mit Bildern, zum Import ins Wiki.docs/handbook/de/anddocs/handbook/en/— with images, ready to import into a wiki.- Screenshots neu erzeugenRegenerate the screenshots
scripts/handbook_fixture.pystartet die Beispieldaten,scripts/handbook_shots.pyfotografiert sie.scripts/handbook_fixture.pyserves the sample data,scripts/handbook_shots.pyphotographs it.