Eine menschliche Freigabe-Schranke hinzufügen

Manche Agentenaktionen sind zu folgenschwer, um sie unbeaufsichtigt auszuführen: das Löschen eines Kontos, die Verarbeitung einer Zahlung, die Freigabe eines Dokuments. Diese Anleitung zeigt, wie Sie einen solchen Aufruf in einer menschlichen Freigabe-Schranke mit dem KLA Control Plane SDK kapseln. KLA Control Plane ist eine Govern-in-Place-Schicht für Laufzeitsicherheit, Audit und Governance: Sie instrumentieren Ihren bestehenden Agentencode, anstatt ihn auf eine neue Plattform umzustellen. Ein einziger Checkpoint genügt, um einen Tool-Aufruf für einen Menschen anzuhalten, ihn an einen Prüfer weiterzuleiten und erst nach ausdrücklicher Freigabe fortzusetzen.

So funktioniert eine Schranke

Sie kapseln den riskanten Aufruf in einem Checkpoint. Der Checkpoint reicht eine Decision Request (die Aktion samt Kontext) an die KLA Policy Engine ein, die sie zu einem von vier Ergebnissen in Vorrangreihenfolge auflöst: allow, warn, require_approval oder block. Gibt die Policy require_approval zurück, wird die Ausführung pausiert. KLA eröffnet eine Escalation (eine pausierte Arbeitseinheit, die auf einen Menschen wartet) und leitet sie an das Decision Desk weiter, den Arbeitsbereich, in dem autorisierte Prüfer ausstehende Aktionen genehmigen oder ablehnen. Der SDK-Aufruf blockiert, bis ein Prüfer entscheidet, und gibt die Kontrolle anschließend an Ihren Code zurück.

sequenceDiagram
  participant App as Ihr Agent
  participant KLA as KLA-Checkpoint
  participant Desk as Decision Desk
  App->>KLA: checkpoint("process_payment", context)
  KLA->>KLA: Decision Request auswerten
  Note over KLA: outcome = require_approval
  KLA->>Desk: Escalation eröffnen
  Desk-->>KLA: Prüfer genehmigt oder lehnt ab
  KLA-->>App: Aufgelöste Entscheidung
  App->>App: Ausführen oder Ablehnung behandeln

Den Checkpoint hinzufügen

Im Folgenden wird ein risikoreicher process_payment-Aufruf durch eine Schranke gesichert. Das SDK blockiert am Checkpoint, bis die Escalation am Decision Desk aufgelöst ist. Sie hängen Geschäftsattribute an (Betrag, Kundenstufe), damit die Policy entscheiden kann und der Prüfer den realen Kontext sieht.

Python

from kla_otel import KLACheckpoint, DecisionDenied

checkpoint = KLACheckpoint(agent_id="agt_9f81a7")

def process_payment(account_id: str, amount: float):
    # Blockiert hier, falls die Policy require_approval zurückgibt, bis ein
    # Prüfer die Escalation am Decision Desk auflöst.
    decision = checkpoint.evaluate_action(
        action="process_payment",
        context={"account_id": account_id, "amount": amount},
        idempotency_key=f"pay-{account_id}-{amount}",
    )

    if decision.is_approved():
        receipt = gateway.charge(account_id, amount)
        checkpoint.log_success(receipt_id=receipt.id)
        return receipt

    # require_approval, das abgelehnt wurde, oder ein harter Block.
    raise DecisionDenied(
        f"Payment not authorized: {decision.reason_codes} ({decision.remediation})"
    )

TypeScript

import { KLAClient, DecisionDenied } from '@kla-digital/otel-node';

const client = new KLAClient({ agentId: 'agt_9f81a7' });

async function processPayment(accountId: string, amount: number) {
  // Wartet auf das Urteil des Prüfers, falls die Policy require_approval zurückgibt.
  const decision = await client.checkpoint('process_payment', {
    context: { accountId, amount },
    idempotencyKey: `pay-${accountId}-${amount}`,
  });

  if (decision.approved) {
    const receipt = await gateway.charge(accountId, amount);
    await decision.logSuccess({ receiptId: receipt.id });
    return receipt;
  }

  throw new DecisionDenied(
    `Payment not authorized: ${decision.reasonCodes} (${decision.remediation})`,
  );
}

Konfigurieren Sie das SDK einmalig beim Start mit Ihrem Tenant und einem Access Token. Jeder Checkpoint-Aufruf sendet in Ihrem Namen Authorization: Bearer <token> und x-tenant-id: <tenant> an https://api.kla.digital.

Eine Ablehnung sauber behandeln

Ein Prüfer kann die Escalation ablehnen, oder die Policy kann einen harten block zurückgeben. Beides trifft als aufgelöste, nicht genehmigte Entscheidung ein, nicht als Netzwerkfehler. Behandeln Sie dies als erwarteten Zweig:

• Lesen Sie die Reason Codes. Jede Entscheidung außer allow führt maschinenlesbare reason_codes (zum Beispiel PAYMENT_OVER_THRESHOLD) und eine menschenlesbare remediation mit sich. Verzweigen Sie anhand der Codes, parsen Sie niemals den Fließtext.
• Zeigen Sie es an, stürzen Sie nicht ab. Geben Sie dem aufrufenden Nutzer oder dem vorgelagerten Agenten eine klare Meldung zurück ("Zahlung erfordert die Genehmigung eines Managers und wurde abgelehnt"). Die Ablehnung ist bereits als Lineage Record erfasst, sodass Sie sie nicht separat für das Audit protokollieren müssen.
• Wiederholen Sie nicht blind. Eine abgelehnte Aktion sollte nicht automatisch in denselben Checkpoint zurückgeführt werden. Eskalieren Sie stattdessen in Ihrem eigenen Produkt an einen menschlichen Pfad.

Vor dem Ausliefern

Verfassen Sie die Schranken-Policy im Policy Builder und führen Sie eine Simulation aus: Spielen Sie repräsentative Decision Requests gegen den Entwurf ab und bestätigen Sie, dass eine hochwertige Zahlung zu require_approval aufgelöst wird, während eine geringwertige zu allow aufgelöst wird. Nach der Validierung wird die Policy in ein signiertes Policy Pack kompiliert und geht live. Von da an erzeugt jeder über eine Schranke abgesicherte Aufruf eine belastbare Spur: die Anfrage, das Ergebnis, das Urteil des Prüfers und die resultierende Aktion, allesamt als Lineage Record erfasst, den Sie später als Sealed Evidence Bundle exportieren können.