KI-Ticket-Triage-Agent — LangGraph + MCP

Ein produktionsreifer Support-Workflow, der unstrukturierte Anfragen klassifiziert, Belege aus PDF-Anhängen extrahiert, über MCP zwei interne Systeme aufruft, eine fundierte Antwort entwirft und unsichere Fälle an einen Menschen weiterleitet, statt zu raten.

Bewertungsübersicht

Dies sind reproduzierbare Ergebnisse aus dem fest eingecheckten synthetischen Korpus, gemessen auf einem lokalen Windows-Entwicklungsrechner. Die Latenz variiert je nach Hardware; der Evaluator meldet jedes Einzelfallergebnis in artifacts/scorecard.json. Die fünf schwierigen Fälle umfassen fehlende Belege, widersprüchliche Kennungen, einen unlesbaren Anhang, eine mehrdeutige Anfrage und einen Datensatz, der im internen System nicht vorhanden ist. Das Artefakt erfasst außerdem seinen Erstellungszeitpunkt, den Korpus-Hash, die Python-Version, den Commit-Bezeichner und den Tool-Transport, sodass veraltete Ergebnisse sichtbar sind.

Warum dieses Projekt existiert

Die meisten Agenten-Demos zeigen nur den Happy Path. Diese hier macht die Enthaltung zu einem getesteten Verhalten. Der Agent kann eines von zwei begrenzten Ergebnissen zurückgeben:

• drafted — die erforderlichen Kennungen wurden extrahiert, beide schreibgeschützten MCP-Prüfungen wurden abgeschlossen und die angegebenen Referenzen wurden verifiziert.

• escalated — Konfidenz oder Belege verfehlen die Policy, daher gibt der Agent eine unverbindliche Zwischenantwort, eine menschliche Warteschlange, die fehlenden Belege und einen prüfbaren Grund aus.

Diese Entscheidung ist nicht in einem Prompt versteckt. Sie ist eine explizite bedingte Kante in der LangGraph-Zustandsmaschine und eine Kennzahl in CI.

Was es tut

Email + PDF
    │
    ▼
classify ──► extract ──► intake safety gate
                              │
                    unsafe ───┴─── safe
                       │              │
                       ▼              ▼
                  human queue    MCP tool 1: customer account
                                      │
                                 MCP tool 2: billing / incident
                                      │
                                post-tool safety gate
                                  │              │
                             unverified       verified
                                  │              │
                                  ▼              ▼
                             human queue   grounded draft

Die beiden MCP-Tools sind bewusst eng begrenzt und schreibgeschützt:

1. lookup_customer_account führt einen exakten Konto-/E-Mail-Abgleich durch.

2. lookup_billing_or_incident prüft Abrechnung, Servicevorfälle oder begrenzten Support-Kontext.

Der Graph verwendet immer einen transportneutralen MCP-Tool-Vertrag. Die Offline-Bewertung nutzt den schnellen In-Process-Adapter; Docker Compose führt die Portfolio-UI gegen einen persistenten, echten JSON-RPC-über-stdio-MCP-Server aus. Beide Transporte sind integrationstestet, sodass die Orchestrierung nie von der Bereitstellungswahl abhängt.

Lokal ausführen

Voraussetzungen: Python 3.11–3.13 und uv.

git clone https://github.com/Mohemed-Amine-Chalhy/ai-ticket-triage.git
cd ai-ticket-triage
uv sync --extra dev --locked
uv run uvicorn ai_ticket_triage.web:app --reload

Öffnen Sie http://127.0.0.1:8000. Die Web-UI enthält alle 20 beschrifteten Beispiele, einen PDF-Uploader, die Graph-Trace, extrahierte Felder, MCP-Aufrufbelege, die endgültige Entscheidung und die Bewertungsübersicht.

Der obige Befehl verwendet den schnellen In-Process-Adapter. Um genau die UI aus der MCP-Demo auszuführen, starten Sie stattdessen den gesperrten Container; Compose aktiviert den persistenten stdio-Server standardmäßig:

docker compose up --build

Alle vier Portfolio-Nachweisbilder aus der aktuellen Bewertungsübersicht und einem tatsächlichen ausführlichen Testlauf neu generieren:

make proof

Es ist kein API-Schlüssel erforderlich. Alle Namen, E-Mail-Adressen, Konten, Rechnungen, Dienste und Vorfälle sind erfunden; E-Mails verwenden die reservierte example.test-Domäne.

CLI-Demo

Ein beantwortbares Fixture ausführen:

uv run ticket-triage triage --case billing_duplicate_charge

Einen Fehlerfall ausführen und die menschliche Übergabe prüfen:

uv run ticket-triage triage --case failure_unreadable_attachment

Eine echte PDF ausführen:

uv run ticket-triage triage \
  --text "I was charged twice; details are attached." \
  --pdf data/sample_attachments/duplicate-charge.pdf

Die tatsächliche stdio-MCP-Grenze testen:

uv run ticket-triage triage \
  --case billing_duplicate_charge \
  --transport stdio

Bewertungsübersicht reproduzieren

uv run ticket-triage-eval \
  --output artifacts/scorecard.json \
  --markdown-output artifacts/scorecard.md \
  --fail-on-runtime-error \
  --enforce-portfolio-targets

Der Evaluator bewertet jede Stufe unabhängig: exakte Kategorieübereinstimmung, Mikro-F1 auf Feldebene, deklarative Entwurfsprüfungen, semantische Fundierung des Übergabegrunds, Eskalationspräzision/-Recall, Fehleskalationen, Laufzeitfehler und p50/p95/max-Latenz. Siehe Bewertungsmethodik.

Den MCP-Server unabhängig verwenden

Den gebündelten offiziellen SDK-Server über stdio starten:

uv run ticket-triage-mcp

Beispielkonfiguration für einen lokalen stdio-MCP-Host:

{
  "mcpServers": {
    "ticket-triage-tools": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ai-ticket-triage",
        "run",
        "ticket-triage-mcp"
      ]
    }
  }
}

Dies ist eine transportneutrale Tool-Grenze: Ein anderer kompatibler Agent oder Desktop-Host kann dieselben beiden Verträge verwenden, ohne die LangGraph-Anwendung zu importieren. Für entfernte Hosts platzieren Sie den Server hinter einer authentifizierten Streamable-HTTP-Bereitstellung; die Portfolio-Demo setzt absichtlich nur lokale stdio- und In-Process-Transporte ein.

Technische Entscheidungen

Deterministisch by design

Der Standard-Klassifikator, -Extraktor und -Entwurfskomponist sind deterministisch. Das macht Sicherheitsregressionen reproduzierbar, hält die öffentliche Demo ohne Anmeldedaten und trennt Workflow-Qualität von Modellvarianz. Ein gehostetes Modell kann diese Knoten hinter denselben typisierten Verträgen ersetzen; in einem echten Rollout sollten seine Kandidatenausgaben weiterhin dieselben Beleg- und Tool-Gates durchlaufen. Dieses Repository behauptet nicht, dass ein synthetischer 20-Fälle-Benchmark die Qualität mit echten Daten vorhersagt.

Repository-Übersicht

src/ai_ticket_triage/
├── agent.py          # LangGraph state machine and tool orchestration
├── classifier.py     # deterministic category scoring with evidence
├── extractor.py      # PDF/text extraction and conflict detection
├── confidence.py     # bounded-failure policy gates
├── drafting.py       # grounded replies and safe holding responses
├── mcp_server.py     # official MCP server; exactly two tools
├── mcp_client.py     # in-process and real stdio MCP gateways
├── internal_api.py   # mock read-only service adapters
├── evaluation.py     # corpus runner and scorecard metrics
├── web.py            # FastAPI application
└── static/           # responsive portfolio UI
data/cases/           # 20 synthetic labelled fixtures
tests/                # unit, API, workflow, evaluator, and MCP integration tests
artifacts/            # committed scorecard and proof outputs
assets/               # portfolio-ready architecture and result images
docs/                 # architecture, evaluation, security, runbook, portfolio copy

Qualitätsbefehle

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest --cov=ai_ticket_triage --cov-report=term-missing
uv run ticket-triage-eval --fail-on-runtime-error --enforce-portfolio-targets
docker compose up --build

Dokumentation

• Architektur und Entscheidungsfluss

• Bewertungsmethodik und Falldesign

• Sicherheits- und Vertrauensgrenzen

• Betriebs-Runbook

• Portfolio-Listing, Nachweis-Checkliste und 55-Sekunden-Skript

Bekannte Grenzen

• Nur textbasierte PDFs; gescannte Dokumente benötigen OCR und eine Malware-Scan-Pipeline.

• Synthetische Exaktabgleich-Internalsysteme, kein echtes CRM oder Abrechnungssystem.

• Englische Fixtures und eine Taxonomie mit vier Klassen.

• Keine dauerhafte Warteschlange, Authentifizierung, Ratenbegrenzung oder verteilte Ablaufverfolgung in dieser lokalen Demo.

• Deterministische Sprachlogik ist eine Zuverlässigkeitsbasis, kein Ersatz für die Bewertung an einem repräsentativen, datenschutzgeprüften Produktionsdatensatz.

Diese Auslassungen sind bewusste Wochenendprojekt-Grenzen. Die Schnittstellen isolieren jedes fehlende Produktionsanliegen, sodass es ohne Umschreiben des Graphen hinzugefügt werden kann.

Lizenz

MIT