helpdesk-agent

Vad modulen gör

helpdesk-agent tar emot ett inkommande supportärende (mejlformat), klassificerar det i en av fem kategorier, beslutar prioritet och eskaleringsnivå, och formulerar ett komplett svarsutkast på svenska i kundens röst-profil. Varje körning producerar ett kryptografiskt signerat audit-bundle som dokumenterar varje steg från input till slutligt utkast. Modulen är designad för att köras både som batch-jobb mot en mejlinkorg och som live-widget inbäddad i kundens supportgränssnitt.

Hur den fungerar

Modulen ärver från BaseModule och kör en deterministisk pipeline. För varje körning skapas en audit-trail med följande block i denna ordning:

1. input_received – det räa ärendet loggas tillsammans med modul-id.
2. context_loaded – intern eskaleringspolicy och FAQ-mönster injiceras som källdokument.
3. agent_call – modellanrop med voice-profil injicerad i system-prompten. Standard är claude-haiku-4-5 för hastighet och kostnad.
4. output_generated – modellens räa utdata, med längd och svars-tid.
5. voice_validated – utdata skannas mot voice-profilens banlista (förbjudna ord, tankstreck).
6. output_validated – modulen parsar den strukturerade utdatan och bekräftar att alla fem sektioner finns och att klassificering, prioritet och eskalering har giltiga värden.
7. audit_sealed – chain-link slutförd, Ed25519-signaturer applicerade på varje block.

Varje block länkas via prev_hash och signeras separat. Det går att verifiera hela kedjan offline med verifyBundle() från lib/audit-chain.mjs.

Input-schema

| Fält | Typ | Krävs | Beskrivning | |------|-----|-------|-------------| | ticket_id | string | ja | Unik identifierare från supportsystemet | | sender.email | string | ja | E-post (valideras mot RFC-likt mönster) | | sender.name | string | nej | Fullt namn, används för personlig tilltal | | subject | string | ja | Ämnesrad, icke-tom | | body | string | ja | Meddelandekropp, icke-tom | | received_at | ISO timestamp | nej | Tidpunkt för mottagande | | customer_brand | string | nej | Identifierare för voice-anpassning, standard "default" |

Exempel:

{
  ticket_id: "tkt-2026-05-19-001",
  sender: { email: "anna@nordbygg.se", name: "Anna Lindqvist" },
  subject: "Frågor om faktura 240518",
  body: "Hej, jag har fått en faktura...",
  received_at: "2026-05-19T08:30:00Z",
  customer_brand: "default"
}

Output-format

Modellen producerar strikt strukturerad text. Modulen parsar denna till ett objekt med fem fält. Schemat är:

KLASSIFICERING: <faktura | teknisk-support | klagomal | leveransfraga | annat>
PRIORITET: <hog | normal | lag>
ESKALERING: <ingen | tier-2 | manager>
SVARSUTKAST:
<100-300 ord svenska>
INTERNA NOTERINGAR:
- <punkt 1>
- <punkt 2>

Parsat resultat (från validateCheck.parsed):

{
  classification: "faktura",
  priority: "normal",
  escalation: "ingen",
  draft: "Hej Anna,\n\nTack för ditt ärende...",
  internalNotes: "- Verifiera faktura 240518...\n- Kontrollera tidigare ärenden..."
}

Integrationsguide

Modulen är ett standard ES-modul med en default-export.

import HelpdeskAgent from "kapaciti-modules/modules/helpdesk-agent.mjs";

const agent = new HelpdeskAgent();
const result = await agent.run({
  ticket_id: "tkt-001",
  sender: { email: "kund@exempel.se", name: "Erik" },
  subject: "Leveransfraga",
  body: "Hej, var ar mitt paket?",
}, { writeBundle: "./bundles/tkt-001.json" });

if (result.error === "usage_cap") {
  // Kö om för retry senare
  return;
}

console.log(result.validateCheck.parsed.classification); // "leveransfraga"
console.log(result.validateCheck.parsed.draft);          // Svensk text

Begränsningar

Modulen löser inte ärenden, den föreslår svar. Det går inte att skicka mejl direkt från modulen, integration mot mejl-gateway sker via wrapper. Modulen läser inte kundhistorik från CRM, den behandlar varje ärende isolerat. Voice-validering är prompt-baserad plus regex-skanning, det är inte semantisk djup-analys. Klassificeringen är en mappning till fem fasta kategorier, det finns ingen fri-text-tagg. Modulen anropar inte externa system för att verifiera fakturor eller leveransspårning, den dokumenterar bara vad teamet behöver kontrollera.

Voice-profile

Standard är customer (Pilot-kund-rost). Profilen är neutral och professionell. Det går att byta vid instansiering:

const agent = new HelpdeskAgent({ voice: "kapaciti" });

För kundspecifika röster läggs nya profiler till i lib/voice-profile.mjs. Profilen skickas in i system-prompten och alla utgående drafts skannas mot banlistan innan de loggas till audit-trail.

Test-coverage

Test-suiten i tests/helpdesk-agent.test.mjs täcker:

1. validateInput avvisar saknade fält
2. validateInput accepterar giltigt ärende
3. buildPrompt inkluderar alla nyckelfält och policy
4. validateOutput parsar välformad respons korrekt
5. validateOutput fångar saknad eller ogiltig sektion
6. End-to-end-körning med riktigt anrop till Claude CLI
7. Producerat bundle verifierar via verifyBundle
8. Manipulation av output_generated-blocket bryter kedjan

Totalt 10 testfall, alla godkända. Test 6 till 8 anropar claude-CLI och tar omkring 50 sekunder.

Audit-bundle exempel

Ett komplett signerat bundle från en exempel-körning finns i examples/helpdesk-agent.bundle.json. Bundlet innehåller 7 block, är signerat med kapaciti-modules privata nyckel och kan verifieras offline. Fingerprint sha256:9eb469d4....

Roadmap

För v1.1 planeras:

• Multi-sprak: engelska och norska som alternativa output-sprak.
• CRM-pull: läs kundhistorik före klassificering för bättre prioritetsbedömning.
• Auto-action: tier-1 ärenden av typ leveransfraga ska kunna skicka svar utan manuell granskning.
• Cluster-detection: identifiera när flera ärenden inkommer om samma underliggande incident.
• Inbäddad widget: drop-in <helpdesk-agent> web component som live-streamar förslag medan operatören skriver.

Belopps-tröskeln för hög prioritet (50 000 SEK) ska bli konfigurerbar per kund. Voice-profil-bytet ska kunna ske per ärende baserat på customer_brand-fältet utan att modulen behöver instansieras om.