App öffnen
Moonborn — Developers

Voice Drift handhaben

Schwellen tunen, den `persona.audit_failed`-Webhook in deine QA-Queue verdrahten und (optional) Auto-Recovery aktivieren, damit geflaggte Antworten den Nutzer nie erreichen.

Drift ist die Lücke zwischen dem Voice Fingerprint einer Persona und dem, was sie gerade gesagt hat. Jede Chat-Antwort trägt diese Lücke als Score. Dieses Tutorial verdrahtet den Score in etwas Operatives: eine getunte Schwelle, ein Webhook-Abo und einen optionalen Auto-Recovery-Pfad.

1. Die Schwelle tunen

Der Default engine.pipeline.drift_detection.threshold = 0.30 ist eine Mittelweg-Wahl. Für markenkritische Oberflächen verengen:

curl -X POST https://api.moonborn.co/v1/config/engine.pipeline.drift_detection.threshold \
  -H "Authorization: Bearer $MOONBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 0.20, "scope": "workspace", "scopeId": "ws_..." }'
await client.config.setItem({
  key: 'engine.pipeline.drift_detection.threshold',
  value: 0.2,
  scope: 'workspace',
  scopeId: 'ws_...',
});

Per-Persona-Overrides leben im Runtime-Contract der Persona — nützlich, wenn eine Persona in der Org ein strikter Support-Agent ist und eine andere ein lockerer kreativer Begleiter.

2. Eine Alert-Aktion wählen

engine.pipeline.drift_detection.action_on_alert akzeptiert:

  • warn (Standard) — Antwort wird versendet, Alert wird geloggt, Webhook feuert.
  • auto_recover — Moonborn regeneriert einmal mit re-injiziertem Fingerprint, versendet die Antwort mit dem niedrigeren Score.
  • block — Caller bekommt 409 Conflict mit dem Drift-Envelope; Downstream entscheidet.

Für Customer Support ist auto_recover plus Webhook-Eskalation das gängige Muster. Für Creative Play reicht warn plus UI-Badge.

3. Den Webhook abonnieren

persona.audit_failed feuert, wann immer die Drift-Schwelle trippt (unter anderen Audit-Failures). Abonniere mit POST /v1/webhooks:

const hook = await client.webhooks.createWebhook({
  url: 'https://your-app.com/webhooks/moonborn',
  events: ['persona.audit_failed'],
  description: 'Drift escalations → CX QA queue',
});
 
console.log('Speichere dieses Secret einmal:', hook.signingSecret);

Der Signing-Secret wird genau einmal zurückgegeben. Speichere ihn; nachfolgende Deliveries sind HMAC-signiert (Header X-Moonborn-Signature).

4. Verifizieren und handeln

import crypto from 'node:crypto';
 
export function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature),
  );
}

Der Payload für ein Drift-Alert sieht so aus:

{
  "id": "evt_01H...",
  "type": "persona.audit_failed",
  "occurredAt": "2026-05-16T12:00:00Z",
  "data": {
    "personaId": "persona_01H...",
    "sessionId": "sess_01H...",
    "messageId": "msg_01H...",
    "driftScore": 0.41,
    "driftThreshold": 0.30,
    "reason": "voice_drift"
  }
}

Schiebe das in deine QA-Queue, deinen Ops-Slack-Channel oder dein Incident-Runbook — welche Pipeline auch immer dein Team besitzt.

5. Deliveries bei Outages replayen

Webhooks retryen bis zu fünf Mal mit exponential backoff (1m → 2m → 5m → 30m → 2h), danach gehts in die Dead-Letter-Queue. Manuelles Replay aus dem Dashboard oder per API:

const deliveries = await client.webhooks.listDeliveries({
  webhookId: hook.id,
  status: 'failed',
});
for (const d of deliveries) {
  await client.webhooks.replayDelivery({
    webhookId: hook.id,
    deliveryId: d.id,
  });
}

Weiter