eksadmin/n8n-compose
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ec581f67da7a3b2dc643997eaab5cb4b55ab8b53
n8n-compose/docs/superpowers/specs/2026-03-16-ai-support-automation-design.md

11 KiB
Raw Blame History

AI-gestützte IT-Support-Automatisierung mit Wissensdatenbank

Datum: 2026-03-16
Status: Design-Phase abgeschlossen, zur Implementation bereit
Autor: Team

1. Problemstellung & Ziel

Problem: Manuelle IT-Support-Tickets in Freescout erfordern manuelle Bearbeitung. Viele wiederkehrende Probleme könnten automatisiert werden, aber lokales KI-Modell ist noch nicht vollständig vertrauenswürdig.

Ziel: Ein Hybrid-System aufbauen, das:

  • Eingehende Mails analysiert mit lokalem LLM
  • Lösungsvorschläge macht (automatische Behebung oder Baramundi-Job)
  • Mensch genehmigt alle Actions (Approval-Gate)
  • Eine selbstlernende Wissensdatenbank aufbaut und nutzt
  • Mit der Zeit immer bessere Vorschläge macht

Success-Kriterium:

  • ✅ Mindestens 50% der Tickets werden von KI erkannt
  • ✅ Mensch kann innerhalb Freescout approven/rejecten
  • ✅ Genehmigt → automatische Ausführung (Baramundi oder Antwort)
  • ✅ KB wächst mit jeder genehmigten Lösung

2. Architektur-Übersicht

Komponenten & Technologien

Komponente Technologie Grund
Orchestrierung n8n (Docker) bereits vorhanden, robust
Mail-Quelle Freescout API (https://ekshelpdesk.fft-it.de) direkter API-Zugriff
KI-Engine LiteLLM API (http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de/v1/chat/completions) lokales, OpenAI-kompatibles Modell
Vector Database Milvus oder Weaviate (Docker) semantische Suche für KB
Knowledge Base Vector Embeddings + Metadaten Problem → Kategorie → Lösung → Häufigkeit
Job-Execution Baramundi Management Server API IT-Jobs auslösen
Approval-UI Freescout Notes + Custom Field Mensch genehmigt direkt in Freescout
Optional Storage PostgreSQL (Docker) Audit Trail, History, Metadaten

System-Datenfluss

┌─────────────────────────────────────────────────────────────────┐
│ 1. MAIL-INGESTION & KI-ANALYSE                                  │
└─────────────────────────────────────────────────────────────────┘
  Freescout (neue Mails)
       ↓
  n8n Polling Workflow (alle 5 Min)
       ↓
  [Für jedes neue Ticket]
       ├→ Vector DB Query: "Ähnliche Probleme finden?"
       ├→ LLM-Call mit Mail + KB-Context
       ├→ Parse KI-Response
       └→ Speichere Vorschlag in Freescout (Note + Custom Field)

┌─────────────────────────────────────────────────────────────────┐
│ 2. HUMAN APPROVAL (Mensch-in-the-Loop)                          │
└─────────────────────────────────────────────────────────────────┘
  Freescout Ticket zeigt KI-Vorschlag
       ↓
  Support-Mitarbeiter liest Vorschlag
       ↓
  [Approve] oder [Reject] geklickt
       ↓
  Custom Field "AI_SUGGESTION_STATUS" = "APPROVED" / "REJECTED"

┌─────────────────────────────────────────────────────────────────┐
│ 3. EXECUTION & KB-UPDATE                                        │
└─────────────────────────────────────────────────────────────────┘
  n8n Webhook triggert bei Field-Änderung
       ├→ Branching:
       │  ├─ Baramundi-Job? → Baramundi API Call
       │  └─ Automatische Antwort? → Mail/Antwort senden
       └→ Bei Success: Lösung in Vector DB speichern
              ├─ Generiere Embedding
              ├─ Speichere [Problem | Kategorie | Lösung | Häufigkeit]
              └─ Update bestehende KB-Einträge (Häufigkeit++)

3. Workflows (n8n)

Workflow A: Mail-Processing & KI-Analyse

Trigger: Cron (alle 5 Minuten)

Schritte:

  1. Freescout API: Hole neue, unverarbeitete Tickets

    • Endpoint: GET /api/conversations?status=active&limit=20
    • Filter: processed_by_ai == false

  2. Für jedes Ticket:

    • Extract Mail-Inhalt: subject, body, customer_email
    • Vector DB Query: Suche semantisch ähnliche Probleme aus KB
      • Query: subject + first 500 chars of body
      • Return: Top 3 Ergebnisse mit Kategorie + Lösung

  3. LLM-Call mit:

    {
  "system": "Du bist IT-Support-Assistent. Analysiere das Ticket und nutze die KB.",
  "user_content": {
    "ticket": { "subject": "...", "body": "..." },
    "similar_kb_entries": [ {...}, {...}, {...} ]
  }
}

  4. Parse Response (JSON):

    {
  "kategorie": "Hardware|Software|Account|Netzwerk|Sonstiges",
  "problem_verstanden": "Kurze Zusammenfassung",
  "lösung_typ": "BARAMUNDI_JOB | AUTOMATISCHE_ANTWORT | ESKALATION",
  "baramundi_job": {
    "name": "Job-Name",
    "parameter": { "..." }
  },
  "antwort_text": "Kundenfreundliche Antwort für Mail...",
  "vertrauen": 0.75,
  "begründung": "Dieses Problem ist in KB vorhanden..."
}

  5. Filter nach Vertrauen:

    • Wenn vertrauen >= 0.6: Vorschlag in Freescout speichern
    • Wenn vertrauen < 0.6: Als "ESKALATION" markieren

  6. Speichere Vorschlag in Freescout:

    • Note (für Mensch zu lesen): 
      [KI-VORSCHLAG]
Kategorie: Hardware
Lösung: Baramundi-Job "Drucker-Treiber-Update"
Vertrauen: 75%
Begründung: ...
    • Custom Field AI_SUGGESTION: JSON serialisiert
    • Custom Field AI_SUGGESTION_STATUS: "PENDING"

  7. Markiere Ticket: processed_by_ai = true

Workflow B: Approval & Execution

Trigger: Freescout Custom Field AI_SUGGESTION_STATUS geändert

Schritte:

  1. Validiere: Status ist "APPROVED" oder "REJECTED"

  2. Wenn REJECTED:

    • Log in PostgreSQL: {ticket_id, rejected_at, reason}
    • Notify Mensch (optional): "KI-Vorschlag wurde abgelehnt"
    • STOP

  3. Wenn APPROVED:

    • Hole KI-Vorschlag aus Custom Field
    • Parse lösung_typ

  4. Branching:

    A) Wenn lösung_typ == "BARAMUNDI_JOB":

    • Call Baramundi API: 
      POST /api/jobs
{
  "name": "...",
  "parameter": {...}
}
    • Speichere Job-ID in Freescout
    • Schreibe Reply-Note: "✅ Baramundi-Job #123 ausgelöst"

    B) Wenn lösung_typ == "AUTOMATISCHE_ANTWORT":

    • Sende Email an Kunde: 
      To: customer_email
Subject: Re: [TICKET_SUBJECT]
Body: [antwort_text aus KI-Response]
    • Schreibe Note in Freescout: "✅ Automatische Antwort gesendet"
    • Markiere Ticket als gelöst

    C) Wenn lösung_typ == "ESKALATION":

    • Markiere für manuelles Review
    • Notify Manager

  5. Bei Success (A oder B):

    • Gehe zu Workflow C (KB-Update)

Workflow C: Knowledge Base Update

Trigger: Nach Workflow B bei Success

Schritte:

  1. Extracte Info:

    • Problem-Text: subject + body
    • Kategorie: aus KI-Response
    • Lösung: antwort_text oder baramundi_job.name
    • Timestamp: now

  2. LLM-Embedding generieren:

    • Call LLM API: /v1/embeddings
    • Input: category + problem_text
    • Output: embedding (vector)

  3. Vector DB Insert:

    {
  "id": "uuid()",
  "problem_text": "Drucker funktioniert nicht",
  "kategorie": "Hardware",
  "lösung": "Treiber neu installiert via Baramundi",
  "häufigkeit": 1,
  "embedding": [0.123, -0.456, ...],
  "timestamp": "2026-03-16T10:30:00Z",
  "baramundi_job_id": "123" (optional),
  "freescout_ticket_id": "999"
}

  4. Update bestehende KB-Einträge:

    • Query Vector DB: "Finde ähnliche Probleme"
    • Für jeden Hit mit Similarity > 0.85:
      • häufigkeit++
      • Update last_used_at

  5. Log in PostgreSQL:

    • knowledge_base_updates Tabelle
    • Track: wann, was, von welchem Ticket

  6. Cleanup (optional):

    • Einmal pro Woche: Archiviere alte Einträge (> 1 Jahr, häufigkeit = 0)

4. Data Structures

Freescout Custom Fields (zu erstellen)

1. AI_SUGGESTION (Text/JSON)
   - Speichert KI-Vorschlag als JSON

2. AI_SUGGESTION_STATUS (Dropdown)
   - Werte: PENDING, APPROVED, REJECTED, EXECUTED
   
3. PROCESSED_BY_AI (Boolean)
   - Markiert ob Mail schon analysiert wurde

Vector DB Schema (Milvus/Weaviate)

{
  "id": "uuid",
  "problem_text": "string",
  "kategorie": "string",
  "lösung": "string",
  "häufigkeit": "integer",
  "embedding": "vector[1024]",
  "timestamp": "datetime",
  "freescout_ticket_id": "integer",
  "baramundi_job_id": "string (optional)"
}

PostgreSQL Schema (optional, für Audit Trail)

CREATE TABLE knowledge_base_updates (
  id UUID PRIMARY KEY,
  ticket_id INTEGER,
  problem_text TEXT,
  kategorie VARCHAR,
  lösung TEXT,
  created_at TIMESTAMP,
  approved_at TIMESTAMP,
  executed_at TIMESTAMP,
  status VARCHAR -- APPROVED, REJECTED, EXECUTED
);

CREATE TABLE kb_feedback (
  id UUID PRIMARY KEY,
  kb_entry_id UUID REFERENCES milvus,
  feedback VARCHAR -- helpful, not_helpful
  created_at TIMESTAMP
);

5. Sicherheit & Governance

Mensch-in-the-Loop

  • ✅ Keine automatische Ausführung: Jede Aktion benötigt manuellen Approval
  • ✅ Vertrauen-Scoring: Nur Vorschläge mit vertrauen >= 0.6 werden angezeigt
  • ✅ Audit Trail: Alle Decisions werden gelogged (wer, wann, was)
  • ✅ Rejection-Tracking: Abgelehnte Vorschläge werden analysiert → Modell-Improvement

Fehlerbehandlung

  • LLM-Timeout: Fallback auf "ESKALATION"
  • Baramundi-API-Fehler: Retry 3x, dann manuelles Review
  • Vector DB Down: Ignoriere KB-Context, nutze LLM ohne Context
  • Mail-Parsing-Fehler: Markiere Ticket, notify Mensch

6. Phasen & Rollout

Phase 1: MVP (Woche 1-2)

  • ✅ n8n Workflows A (Mail-Processing) + B (Approval) einrichten
  • ✅ Freescout API Integration testen
  • ✅ LiteLLM Integration testen
  • ✅ Manuelle Approval-Flow testen

Phase 2: KB Integration (Woche 3)

  • ✅ Milvus in Docker deployen
  • ✅ Workflow C (KB-Update) einrichten
  • ✅ Vector DB Query in Workflow A integrieren

Phase 3: Production (Woche 4+)

  • ✅ Monitoring + Alerting
  • ✅ KB-Cleanup-Jobs
  • ✅ Reporting + Analytics

7. Success Metrics

Metrik Ziel Messung
Mail-Erkennungsrate > 50% (processed_by_ai = true) / total_tickets
Approval-Rate > 70% approved / total_suggested
Baramundi-Job-Success > 90% successful_jobs / total_jobs
KB-Größe > 100 Einträge count(*) from vector_db
Häufigkeits-Improvement > 20% weniger Manual-Work manual_processing_time t1 vs t2

8. Offene Fragen & Next Steps

  • Welche Baramundi-Jobs sind verfügbar?
  • Freescout API-Key vorhanden?
  • LiteLLM API-Key/Auth Setup?
  • PostgreSQL für Audit Trail gewünscht oder Optional?
  • Milvus oder Weaviate bevorzugt?
  • Wie oft soll KB-Cleanup laufen?

Status: Bereit für Implementation Plan

Reference in New Issue View Git Blame Copy Permalink