Mieterportal/n8n/README-assistent.md

KI-Assistent (v1.37) – Einrichtung N8N + Kimi

Der Assistent läuft so: Portal-Chat → N8N-Webhook → Kimi (Moonshot API) mit 6 Portal-Tools → Antwort zurück ins Portal.

Stand: Der Workflow ist auf dem Produktivsystem (hocks.eu) bereits serverseitig eingerichtet und aktiv. Die Datei assist-workflow.json in diesem Ordner ist die dokumentierte Referenz-Version. Der produktive Workflow wurde direkt in die N8N-Datenbank eingespielt, weil die lokale N8N-API in Version 2.x keinen zuverlässigen programmatischen Import erlaubt (401-Problem). Bei einem Re-Import auf einem anderen System müssen die drei Platzhalter im Code-Node belegt werden.

1. Architektur des Workflows

Ein einzelner Workflow „Mieterportal – KI-Assistent (Kimi)", Webhook POST mp-assist, drei Nodes:

1. Webhook Portal (n8n-nodes-base.webhook, typeVersion 2, responseMode responseNode) – produktive URL: http://n8n:5678/webhook/mp-assist (internes Docker-Netz npm_default). – Wichtig: Der Node braucht die Property webhookId (gleich der Node-ID) auf Root-Ebene, sonst registriert n8n den Webhook bei responseMode: responseNode nicht (404 „not registered").
2. Assistent (Kimi + Tools) (n8n-nodes-base.code, typeVersion 2, runOnceForAllItems) – Prüft den Header x-assist-secret selbst gegen das Shared Secret. – Ruft https://api.moonshot.ai/v1/chat/completions (Modell kimi-k2.6) per this.helpers.httpRequest auf, mit OpenAI-kompatiblem Tool-Calling für genau die 6 Portal-Endpunkte unter /api/assist/tools/… (Schleife, max. 6 Runden). – Kein temperature-Parameter senden – kimi-k2.6 akzeptiert nur temperature: 1, sonst 400 „invalid temperature". – Kein URLSearchParams im Sandbox-Code verwenden – nicht verfügbar; Query-Strings manuell mit encodeURIComponent bauen. – 429 (Rate-Limit) wird abgefangen und als freundliche Meldung zurückgegeben.
3. Antwort an Portal (n8n-nodes-base.respondToWebhook, typeVersion 1.1) – respondWith: json, Body ={{ { antwort: $json.antwort } }}.

Der langchain-basierte Entwurf (AI-Agent-Node) wurde verworfen: Die @n8n/n8n-nodes-langchain- Nodes liefen auf diesem Server nicht zuverlässig. Der Code-Node-Ansatz hat keine externen Abhängigkeiten und keine Credentials (alle Geheimnisse als Literale im Code-Node).

2. Geheimnisse (Platzhalter im Workflow-JSON)

Platzhalter im Code-Node	Bedeutung	Wo konfiguriert
<ASSIST_SHARED_SECRET>	Header x-assist-secret zwischen Portal und n8n	portal.env (ASSIST_SHARED_SECRET)
<ASSIST_KEY>	Header x-assist-key für die 6 Tool-Endpunkte	portal.env (ASSIST_API_KEY)
<KIMI_API_KEY>	Moonshot-API-Key (sk-…)	Code-Node, Konstante ganz oben

3. Portal-Env auf dem Server

In /opt/mieterportal/portal.env (nur auf dem VPS, gitignored):

N8N_ASSIST_WEBHOOK=http://n8n:5678/webhook/mp-assist
ASSIST_SHARED_SECRET=<langes-zufaelliges-geheimnis-1>
ASSIST_API_KEY=<langes-zufaelliges-geheimnis-2>

Danach: cd /opt/mieterportal && docker compose up -d.

4. Kosten

Kimi kimi-k2.6: ~0,4 US-Cent pro Frage (Systemprompt + Tool-Schleife). Bei 20 Fragen/Tag typisch unter 5 €/Monat. Aufladung des Moonshot-Kontos ab ~5 $.

5. Test

Im Portal als Verwaltung: KI-Assistent in der Navigation → „Welche Wohnungen stehen leer?" Der erste Aufruf dauert ggf. 10–60 s (Tool-Schleife).

Serverseitig direkt testbar:

docker exec mp-api node -e "fetch('http://n8n:5678/webhook/mp-assist',{method:'POST',headers:{'Content-Type':'application/json','x-assist-secret':'<SECRET1>'},body:JSON.stringify({frage:'Welche Wohnungen stehen leer?',verlauf:[],benutzer:'E2E'})}).then(async r=>console.log(r.status,await r.text()))"

Fehlerbilder

Fehlermeldung	Ursache
„not registered" (404)	Workflow nicht aktiv, webhookId am Webhook-Node fehlt, oder n8n neu gestartet ohne Outbox-Eintrag
„invalid temperature" (400)	temperature != 1 im Kimi-Payload
„Assistent antwortet nicht (N8N Status 500)"	Kimi 429 (Rate-Limit, kurz warten) oder Code-Fehler – Executions in n8n prüfen
Antwort „Tool … nicht erreichbar"	Portal-Tool-Endpunkte nicht erreichbar (Netz npm_default, x-assist-key)

Datenschutz-Hinweis

Das Tool mieter_kontakt liefert personenbezogene Daten an Kimi (Serverstandort Singapur, Training laut Anbieter-AGB möglich). Wer das vermeiden will, entfernt den Tool-Eintrag aus dem TOOLS-Array im Code-Node – alle anderen Tools liefern nur Bestands- und Zahlen-Daten.