# 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:
   ```json
   {
     "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):
   ```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:**
   ```json
   {
     "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)

```json
{
  "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)

```sql
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