IntegrationshandbuchIntegration manual

Schritt für Schritt zur AnbindungStep-by-step integration manual

Acht Abschnitte, in der Reihenfolge, in der sie zu tun sind. Jeder Befehl und jeder Endpunkt auf dieser Seite ist gegen dieses Repository ausgeführt worden; die gezeigten Antworten sind echte Antworten, keine Beispiele aus dem Kopf. Eight sections, in the order you do them. Every command and every endpoint on this page was run against this repository; the responses shown are real responses, not examples from memory.

Voraussetzung für die Abschnitte 1 bis 2: Python 3.11 oder neuer, git, für den Container zusätzlich Docker. Zugangsdaten brauchen Sie bis Abschnitt 8 keine. Prerequisites for sections 1 and 2: Python 3.11 or newer, git, and Docker for the container. You need no credentials anywhere up to section 8.

Vier Befehle. Der erste baut die Umgebung, der zweite ist der QA-Gate, der dritte spielt ein vollständiges Gespräch durch, der vierte startet die Betriebskonsole. Four commands. The first builds the environment, the second is the QA gate, the third plays a complete conversation, the fourth starts the operations console.

make install
make gate
make demo
make console

• make install legt .venv an und installiert das Paket samt Entwicklungswerkzeug. Einmalig.creates .venv and installs the package plus the dev tooling. Once.
• make gate der QA-Gate: ruff, mypy, pytest -m "not live" und die Isolationsprüfung. Grün heißt grün — ohne ein einziges Geheimnis.the QA gate: ruff, mypy, pytest -m "not live" and the isolation guard. Green means green — with not one secret.
• make demo spielt offline durch: ein Gespräch mit Latenzmessung, eine Freigabe über 200 EUR, die Ablehnung eines autonomen Ausgangsanrufs nach §7 UWG und einen Modellwechsel per Konfiguration.runs offline: a conversation with latency measurement, a EUR 200 approval, the refusal of an autonomous outbound call under §7 UWG, and a model swap by configuration.
• make console startet die Konsole auf 127.0.0.1:8080 mit ACP_ENV=mock. Betrieb unter /, Wissen unter /knowledge, Verwaltung unter /admin.starts the console on 127.0.0.1:8080 with ACP_ENV=mock. Operations at /, knowledge at /knowledge, administration at /admin.

Was der Gate tatsächlich ausführt — nachlesbar mit make -n gate: What the gate actually runs — readable with make -n gate:

.venv/bin/ruff check src tests
.venv/bin/mypy
.venv/bin/pytest -m "not live"
bash scripts/check_isolation.sh

Die Konsole zeigt ihre Oberfläche öffentlich, holt aber jede Zahl authentifiziert. Ohne Anmeldung erscheint deshalb der Hinweis „Sitzung abgelaufen“. Für den lokalen Blick genügt ACP_ALLOW_ANON=1 — in live verweigert der Start damit den Dienst, absichtlich. The console serves its shell publicly but fetches every number authenticated. Without a sign-in you therefore see the “session expired” banner. For a local look, ACP_ALLOW_ANON=1 is enough — in live that same variable refuses the boot, deliberately.

ACP_ENV=mock ACP_ALLOW_ANON=1 .venv/bin/uvicorn acp.console.app:app --host 127.0.0.1 --port 8080

Weitere Ziele: make test (nur Tests), make test-cov (mit Abdeckung), make lint, make typecheck, make audit (Abhängigkeitsprüfung gegen bekannte Schwachstellen). Further targets: make test (tests only), make test-cov (with coverage), make lint, make typecheck, make audit (dependency scan against known vulnerabilities).

make docker-build
make compose-up

• make docker-build baut acp-platform:dev aus deploy/Dockerfile: zwei Stufen, ein Rad gegen requirements.lock, Laufzeit als Benutzer 10001 ohne Rechteerweiterung. Der Gesundheitscheck ruft /health mit der Standardbibliothek — kein curl im Bild.builds acp-platform:dev from deploy/Dockerfile: two stages, a wheel against requirements.lock, runtime as user 10001 with no privilege escalation. The healthcheck calls /health from the standard library — no curl in the image.
• make compose-up startet drei Dienste: die Konsole auf 127.0.0.1:8080, PostgreSQL 16.4 und Redis 7.4. Bilder tragen exakte Versionen, nie :latest.brings up three services: the console on 127.0.0.1:8080, PostgreSQL 16.4 and Redis 7.4. Images carry exact versions, never :latest.

Der Stapel kommt ohne jedes Geheimnis hoch: ACP_ENV steht per Vorgabe auf mock, und ../.env wird eingebunden, falls vorhanden, aber nicht verlangt. Genau das ist der Punkt — ein Mandant wird live, indem er Geheimnisse liefert, nicht indem jemand Code ändert. The stack comes up with no secret at all: ACP_ENV defaults to mock, and ../.env is included if present but never required. That is the point — a tenant goes live by supplying secrets, not by anyone changing code.

Prüfen Sie den Container so: Check the container like this:

curl -s http://127.0.0.1:8080/health
{"status":"ok","version":"0.1.0","region":"eu-central-1"}

Zwei Geltungsbereiche, bewusst getrennt: Plattform gilt für das ganze Deployment und wird einmal beim Start gelesen; Mandant gilt pro Kunde und kommt später aus dem Mandantenregister. Nichts verändert os.environ — viele Mandanten leben mit eigener Konfiguration im selben Prozess. Two scopes, deliberately separated: platform applies to the whole deployment and is read once at boot; tenant applies per customer and later comes from the tenant registry. Nothing mutates os.environ — many tenants coexist in one process with their own configuration.

Jedes Geheimnis darf stattdessen aus einer Datei kommen. <NAME>_FILE gewinnt gegen <NAME>, und der Wert taucht damit weder in docker inspect noch in einem Absturzbericht auf. Leer gilt als nicht gesetzt: Every secret may come from a file instead. <NAME>_FILE beats <NAME>, so the value appears neither in docker inspect nor in a crash dump. Blank counts as unset:

ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_api_key
ACP_CONSOLE_SECRET_FILE=/run/secrets/acp_console_secret
ACP_INGEST_TOKEN_FILE=/run/secrets/acp_ingest_token

Und so sieht die fail-closed-Regel aus, wenn etwas fehlt. Beachten Sie den zweiten Fall: production ist kein Sonderwort, sondern schlicht „nicht offline“ — deshalb greift dieselbe Prüfung: And this is what the fail-closed rule looks like when something is missing. Note the second case: production is not a special word, merely “not offline” — so the same check applies:

ACP_ENV=production .venv/bin/uvicorn acp.console.app:app

SecretError: refusing to start: ACP_ENV='production' is treated as a LIVE
deployment (only ['ci', 'mock', 'test'] are offline).
  - required secret ACP_CONSOLE_SECRET is not set
    (set ACP_CONSOLE_SECRET or ACP_CONSOLE_SECRET_FILE). Refusing to start.
  - required secret ACP_INGEST_TOKEN is not set
    (set ACP_INGEST_TOKEN or ACP_INGEST_TOKEN_FILE). Refusing to start.

Alle Probleme werden auf einmal gemeldet, nicht eins nach dem anderen — und nicht erst bei der ersten Anfrage, die zufällig ein Geheimnis braucht. Every problem is reported at once rather than one at a time — and at startup, not on the first request that happens to need a secret.

GET /v1/health ist der einzige unauthentifizierte Endpunkt der Produkt-API. Alles andere braucht einen Mandantenschlüssel als Bearer-Token. GET /v1/health is the only unauthenticated endpoint in the product API. Everything else needs a tenant key as a bearer token.

curl -s http://127.0.0.1:8080/v1/health
{"status":"ok","api_version":"v1"}

Es gibt bewusst keinen Ausstellungs-Endpunkt: Ausstellen vergibt einen mandantenweiten Zugang, und außerhalb der HTTP-Oberfläche kann eine übernommene Konsolensitzung keinen Schlüssel erzeugen. Ausgestellt wird auf dem Host; der Klartext erscheint genau einmal, gespeichert wird nur sein Hash: There is deliberately no issuance endpoint: issuing hands out a tenant-wide credential, and keeping it off the HTTP surface means a hijacked console session cannot mint one. Issuance happens on the host; the plaintext appears exactly once and only its hash is stored:

# On a deployed instance. The key file sits on the data volume, so the key
# keeps working across restarts and releases.
docker exec -i acp-console-1 python -m acp.api issue-api acme read,write "acme prod"

# Locally, against a checkout:
ACP_KEYS_DIR=var python -m acp.api issue-api acme read,write "local dev"

# List what exists, and take one back. Revocation is refused from the next
# request onward — no restart, because the file decides authority.
python -m acp.api list acme
python -m acp.api revoke <key-id>

.venv/bin/uvicorn acp.console.app:app --host 127.0.0.1 --port 8080

Der Schlüssel hat die Form acp_sk_<key-id>_<secret>. Gespeichert wird nur sein Hash; der Klartext erscheint genau einmal. Damit fragen Sie, wer Sie sind: The key has the shape acp_sk_<key-id>_<secret>. Only its hash is stored; the plaintext appears exactly once. With it you ask who you are:

curl -s http://127.0.0.1:8080/v1/tenant \
     -H "Authorization: Bearer acp_sk_0f521c65f209934b_<secret>"

{"tenant_id":"acme","key_id":"0f521c65f209934b","scopes":["read","write"],
 "region":"eu-central-1"}

• Der Mandant kommt immer aus dem Schlüssel. ?tenant=, ?tenant_id= und X-Tenant-Id werden ignoriert — Tests sichern das ab.The tenant always comes from the key. ?tenant=, ?tenant_id= and X-Tenant-Id are ignored — tests pin that down.
• Jeder Fehlerfall antwortet gleich: 401 {"detail":"invalid API key"} für fehlend, falsch geformt, unbekannt und widerrufen.Every failure answers identically: 401 {"detail":"invalid API key"} for missing, malformed, unknown and revoked.
• Ein fremdes Gespräch ist 404, nie 403 — der Unterschied würde bestätigen, dass es existiert.Another tenant's conversation is 404, never 403 — the distinction would confirm it exists.
• Schreibende Routen verlangen den Bereich write; ein Lese-Schlüssel bekommt 403.Writing routes require the write scope; a read-only key gets 403.

Der Rest der Oberfläche, wie er in src/acp/api/v1.py steht: The rest of the surface, as it stands in src/acp/api/v1.py:

curl -s -X POST http://127.0.0.1:8080/v1/knowledge \
     -H "Authorization: Bearer acp_sk_<key-id>_<secret>" \
     -H "Content-Type: application/json" \
     -d '{"title":"Versandkosten",
          "body":"Der Versand innerhalb Deutschlands kostet 4,90 EUR.",
          "category":"service","language":"de","summary":"Versandkosten Inland"}'

{"record_id":"versandkosten","title":"Versandkosten",
 "summary":"Versandkosten Inland","category":"service","language":"de",
 "status":"draft","authority":"internal","audience":"internal",
 "version":1,"citable":false}

Beachten Sie "status":"draft" und "citable":false. Ein Entwurf steuert keinen Agenten: nur veröffentlichte Einträge erreichen die Produktion, und nur eine amtliche Quelle wird gegenüber Kunden zitierfähig. Note "status":"draft" and "citable":false. A draft steers no agent: only published records reach production, and only an official source becomes citable to customers.

Der Lebenszyklus ist im Code erzwungen, nicht bloß dokumentiert: The lifecycle is enforced in code, not merely documented:

draft ──→ verified ──→ published ──→ retired
  ↑            │             │
  └────────────┴─────────────┘

SchemaError: illegal transition draft -> published for 'versandkosten'

• Entwurf → verifiziert — der Verifier erdet jede Aussage im Quelltext; jede Zahl muss dort wörtlich stehen. Er ist absichtlich lexikalisch und kein Modell: ein Modell, das ein Modell prüft, teilt dessen Fehler.Draft → verified — the verifier grounds every claim in the source text; every figure must appear there verbatim. It is deliberately lexical and not a model: a model checking a model shares its failure modes.
• Verifiziert → veröffentlicht — ein Mensch gibt frei, in der Konsole unter /knowledge, mit der Quelle daneben. Das Veröffentlichen ist ein Commit, und das Golden-Gate prüft dabei, ob der Agent schlechter geworden ist.Verified → published — a human approves, in the console at /knowledge, with the source beside it. Publishing is a commit, and the golden gate checks whether the agent got worse.
• Entwurf → veröffentlicht gibt es nicht. Weder über die API noch über die Konsole; der Übergang wirft die oben gezeigte Ausnahme. Eine Bearbeitung eines veröffentlichten Eintrags setzt ihn zurück in den Entwurf.Draft → published does not exist. Not through the API, not through the console; the transition raises the exception shown above. Editing a published record puts it back into draft.

Ehrlich zum heutigen Stand: die Freigabe ist eine menschliche Handlung, aber sie hat noch keinen HTTP-Endpunkt. Verifizieren und Veröffentlichen laufen serverseitig über die Registry — registry.publish(record_id, actor="…"), was den Commit schreibt und den Freigebenden stempelt. Die Konsole zeigt Bestand, Status und Herkunft; sie täuscht keine Schaltfläche vor, die es nicht gibt. Honest about today: approval is a human action, but it has no HTTP endpoint yet. Verify and publish run server-side through the registry — registry.publish(record_id, actor="…"), which writes the commit and stamps the approver. The console shows the inventory, status and provenance; it fakes no button that does not exist.

Was der Agent später findet, prüfen Sie so — die Suche liefert nur veröffentlichtes und kundentaugliches Material: Check what the agent will find like this — retrieval returns only published, customer-safe material:

curl -s -G http://127.0.0.1:8080/v1/knowledge-search \
     -H "Authorization: Bearer acp_sk_<key-id>_<secret>" \
     --data-urlencode "q=Was kostet der Versand?" --data-urlencode "language=de"

curl -s -X POST http://127.0.0.1:8080/v1/webhooks \
     -H "Authorization: Bearer acp_sk_<key-id>_<secret>" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/acp/webhook",
          "events":["turn.completed","conversation.escalated"]}'

{"endpoint_id":"ccd086565d831d82","url":"https://example.com/acp/webhook",
 "events":["turn.completed","conversation.escalated"],"active":true,
 "secret":"BYHpdmnTHljmXPPnEG4nH8Xbukk-CCrLSeXuO-Lr7ig"}

Das Signaturgeheimnis erscheint wie ein Schlüssel genau einmal, hier in der Antwort auf die Registrierung. Ein späteres GET /v1/webhooks liefert an dieser Stelle null. Abonnierbar sind: conversation.started, conversation.ended, turn.completed, approval.requested, conversation.escalated, turn.budget_exceeded. Eine leere Liste heißt „alles“. The signing secret appears exactly once, like a key — here, in the registration response. A later GET /v1/webhooks returns null in that field. Subscribable events: conversation.started, conversation.ended, turn.completed, approval.requested, conversation.escalated, turn.budget_exceeded. An empty list means “everything”.

So sieht eine Zustellung aus. Der Rumpf wird mit sortierten Schlüsseln und ohne Leerzeichen serialisiert, damit die Signatur reproduzierbar ist: This is what a delivery looks like. The body is serialised with sorted keys and no whitespace so the signature is reproducible:

X-ACP-Event:     turn.completed
X-ACP-Signature: t=1787558400,v1=f442c3f4a3a99fa506d0ca559c080ffcd242b7c3a0363508176533f425c6f1e8

{"data":{"conversation_id":"web-1a2b3c4d5e6f7a8b"},"event":"turn.completed",
 "occurred_at":1787558400.0,"tenant_id":"acme"}

v1 = HMAC-SHA256( secret, "{timestamp}.{body}" )

Der Zeitstempel liegt im signierten Material — eine mitgeschnittene Zustellung lässt sich deshalb nicht später erneut abspielen, sofern Sie die Frische prüfen. Lehnen Sie alles ab, was älter als 300 Sekunden ist, und signieren Sie gegen den Rumpf wie empfangen, nie gegen ein neu serialisiertes Objekt. The timestamp sits inside the signed material — a captured delivery therefore cannot be replayed later, provided you check freshness. Reject anything older than 300 seconds, and verify against the body as received, never against a re-serialised object.

Prüfung in Python:Verification in Python:

import hashlib, hmac, time

def verify(secret: str, body: str, header: str, tolerance_s: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        timestamp, received = int(parts["t"]), parts["v1"]
    except (ValueError, KeyError):
        return False
    if abs(time.time() - timestamp) > tolerance_s:
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, received)

Dasselbe in JavaScript (Node):The same in JavaScript (Node):

const crypto = require("node:crypto");

function verify(secret, body, header, toleranceS = 300) {
  const parts = {};
  for (const piece of header.split(",")) {
    const i = piece.indexOf("=");
    parts[piece.slice(0, i)] = piece.slice(i + 1);
  }
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceS) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${timestamp}.${body}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Beide Fassungen vergleichen in konstanter Zeit. Wer die Plattform selbst betreibt, kann stattdessen acp.api.webhooks.verify_signature aufrufen — dieselbe Implementierung, die auch signiert. Both versions compare in constant time. If you run the platform yourself you can call acp.api.webhooks.verify_signature instead — the same implementation that signs.

Eine private Adresse wird abgelehnt. Das ist die Funktion, nicht der Fehler: Ihre URL ist ein Ziel, das die Plattform aus ihrer eigenen Vertrauenszone heraus anspricht. A private address is refused. That is the feature, not the fault: your URL is a destination the platform will reach from inside its own trust boundary.

HTTP/1.1 400 Bad Request

{"detail":"address 10.0.0.5 is not publicly routable. Policy: https only;
 no loopback, private, link-local, multicast or reserved addresses;
 no *.internal / *.local / localhost; no known internal service ports;
 DNS re-checked at delivery time (rebinding);
 override with ACP_WEBHOOK_ALLOW_HOSTS"}

Der erste Satz wechselt mit der verletzten Regel — etwa webhook url must use https oder host 'hooks.internal' is internal. Geprüft wird bei der Registrierung und erneut bei jeder Zustellung, weil DNS angreiferkontrolliert ist. Zustellung selbst ist „fire and forget“ mit bis zu drei Versuchen; 4xx außer 429 wird nicht wiederholt, und ein hängender Empfänger kann ein laufendes Gespräch weder verzögern noch scheitern lassen. The first sentence changes with the rule that was broken — for example webhook url must use https or host 'hooks.internal' is internal. It is checked at registration and again at every delivery, because DNS is attacker-controlled. Delivery itself is fire-and-forget with up to three attempts; 4xx other than 429 is not retried, and a hanging receiver can neither delay nor fail a live conversation.

Ein Script-Tag, keine Abhängigkeit, kein Build-Schritt: One script tag, no dependency, no build step:

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

• acp_pk_ ist öffentlich — und muss es sein.acp_pk_ is public — and has to be. Was auf einer Webseite steht, kann jeder lesen. Deshalb gehört dort niemals ein API-Schlüssel hin: acp_sk_ gewährt Lesen und Schreiben für den ganzen Mandanten und wäre eingefügt in eine Seite eine veröffentlichte Zugangsberechtigung.Anything on a web page is readable by anyone. So an API key never belongs there: acp_sk_ grants read and write across the whole tenant, and pasted into a page it is a published credential.
• Geschützt wird nicht durch Geheimhaltung, sondern durch die Herkunft.Protection comes from the origin, not from secrecy. Der Browser setzt Origin, und eine Seite kann diesen Wert nicht fälschen. Ein Schlüssel, der von einer anderen Domain kommt, ist wertlos. Eine leere Herkunftsliste erlaubt nichts — eine unfertige Einrichtung bleibt geschlossen statt offen.The browser sets Origin and a page cannot forge it, so a key used from another domain is inert. An empty origin list allows nothing — an unfinished setup stays closed rather than open.
• Der Schlüssel kauft nur eine Sitzung.The key buys only a session. Er wird gegen ein kurzlebiges, auf ein einziges Gespräch signiertes Token getauscht (30 Minuten). Das Widget kann das Gespräch nicht benennen, in das es schreibt — ein Besucher kann also nie in den Chat eines anderen schreiben.It is exchanged for a short-lived token signed for a single conversation (30 minutes). The widget cannot name the conversation it posts into, so one visitor can never write into another's chat.
• Der KI-Hinweis kommt vom Server.The AI disclosure comes from the server. Er wird mit der Sitzung ausgeliefert und als erste Nachricht angezeigt, bevor der Besucher tippen kann — die einbettende Seite kann ihn nicht weglassen. Artikel 50 der EU-KI-Verordnung ist damit nicht Ihre Bastelaufgabe.It is delivered with the session and rendered as the opening message before the visitor can type — the embedding page cannot omit it. EU AI Act Article 50 is therefore not left to your page.

Den Wortlaut können Sie sich vorher ansehen: You can preview the exact wording:

curl -s http://127.0.0.1:8080/widget/v1/disclosure

{"de":"Sie sprechen mit einem KI-Assistenten. Auf Wunsch übergebe ich an einen Menschen.",
 "en":"You are speaking with an AI assistant. I can hand over to a person at any time."}

Das Widget rendert in einem Shadow-DOM: Ihr Seiten-CSS kann es nicht kaputt machen, und es kann Ihre Seite nicht umgestalten. Farben kommen aus --acp-* und vererben durch die Shadow-Grenze — Ihre Marke ist ein Token-Override, kein Fork. Modellausgabe wird über textContent gesetzt, nie über innerHTML. Mit data-lang="en" startet es englisch, mit data-title tragen Sie eine eigene Überschrift ein. The widget renders in a shadow DOM: your page CSS cannot break it, and it cannot restyle your page. Colours come from --acp-* and inherit through the shadow boundary — your brand is a token override, not a fork. Model output is set through textContent, never innerHTML. With data-lang="en" it starts in English, and data-title sets your own heading.

Die meisten dieser Antworten sind kein Defekt, sondern eine Entscheidung. Alle Texte unten sind echte Antworten dieses Repositories. Most of these answers are a decision, not a defect. Every message below is a real response from this repository.