Eine menschliche Freigabeschranke hinzufügen

Manche Agentenaktionen benötigen eine verantwortliche menschliche Freigabe: ein Konto löschen, eine Zahlung verarbeiten oder ein Dokument freigeben. Diese Anleitung leitet eine solche Aktion über das KLA Control Plane SDK. KLA wertet die Decision Request aus, leitet eine erforderliche Escalation an das Decision Desk weiter, führt nach der Autorisierung über den registrierten Connector aus und gibt das aufgezeichnete Ergebnis zurück.

So funktioniert eine Schranke

executeAction in Node.js und execute_action in Python übermitteln eine Decision Request mit Aktion und Kontext. Die KLA Policy Engine löst sie zu allow, warn, require_approval oder block auf. Ein Ergebnis require_approval öffnet eine Escalation, eine pausierte Arbeitseinheit, die auf eine menschliche Entscheidung wartet. Das Decision Desk leitet sie an einen autorisierten Prüfer weiter. Das SDK bewahrt beim Polling und Fortsetzen eine Proposal-Identität. KLA führt die genehmigte Aktion genau einmal über den registrierten Connector aus und gibt execution.result zurück.

sequenceDiagram
  participant App as Ihr Agent
  participant KLA as KLA-Checkpoint
  participant Desk as Decision Desk
  App->>KLA: executeAction("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->>KLA: Registrierten Connector einmal ausführen
  KLA-->>App: execution.result oder typisierte Ablehnung

Den Checkpoint hinzufügen

Im Folgenden verwendet eine risikoreiche process_payment-Aktion kla-governance für Python und @kla-digital/governance für Node.js. Das SDK pollt, bis das Decision Desk die Escalation auflöst. Die Freigabe bindet Konto, Betrag, Agent-Release, Mandat, Tool, Vorgang und Ziel an eine Proposal.

Python

from kla_governance import ActionRequest, AgentIdentity, DecisionDenied, KLAClient

client = KLAClient(
    base_url="https://api.kla.digital",
    credential=get_access_token,
    agent=AgentIdentity(agent_id="agt_9f81a7", release_version="1.4.2"),
    mandate_id="mnd_payments",
)

def process_payment(account_id: str, amount: float):
    try:
        return client.execute_action(
            ActionRequest(
                tool="payments",
                operation="charge",
                destination="gateway:acct_main",
                parameters={"account_id": account_id, "amount": amount},
            ),
            proposal_id=stable_id_for(account_id, amount),
        )
    except DecisionDenied as denial:
        raise PaymentNotAuthorized(
            f"Payment not authorized: {denial.reason_codes} ({denial.remediation})"
        )

TypeScript

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

const client = new KLAClient({
  baseUrl: 'https://api.kla.digital',
  credential: () => getAccessToken(),
  agent: { agentId: 'agt_9f81a7', releaseVersion: '1.4.2' },
  mandateId: 'mnd_payments',
});

async function processPayment(accountId: string, amount: number) {
  try {
    return await client.executeAction(
      {
        tool: 'payments',
        operation: 'charge',
        destination: 'gateway:acct_main',
        parameters: { accountId, amount },
      },
      { proposalId: stableIdFor(accountId, amount) }
    );
  } catch (error) {
    if (error instanceof DecisionDenied) {
      throw new PaymentNotAuthorizedError(
        `Payment not authorized: ${error.reasonCodes} (${error.remediation})`
      );
    }
    throw error;
  }
}

Konfigurieren Sie den Client beim Start mit der Basis-URL der Control Plane, einem Client-Credentials-Access-Token, der registrierten Agent-ID, der angehefteten Release-Version und einer aktiven Mandats-ID. Registrieren Sie Tool und Connector im Tool Catalog. Das Mandat muss Tool, Vorgang und Ziel abdecken. Die Tenant-Identität stammt aus dem verifizierten Token. Das SDK sendet bei jeder Aktionsanfrage Authorization: Bearer <token>.

Verwenden Sie resolve_binding() in Python oder resolveBinding() in Node.js als schreibgeschützte Startprüfung. Sie bestätigt das aktuell genehmigte Release und die aktive Mandatsrevision einschließlich Gültigkeitszeitraum und erlaubter Aktionen, bevor der Worker gesteuerte Aufgaben annimmt.

Governance mit OpenTelemetry verbinden

Verwenden Sie beide SDKs in einem instrumentierten Agenten. Sie haben getrennte Zuständigkeiten:

Initialisieren Sie das OpenTelemetry SDK beim Start der Anwendung und rufen Sie das Governance SDK an jeder Grenze einer konsequenten Aktion auf. Übergeben Sie verfügbare aktive OpenTelemetry-Trace- und Span-Kennungen über die trace-Option des Governance-Aufrufs. So werden Decision Request und serverseitige Ausführung mit dem umgebenden Lineage Record korreliert. Ein aufgelöster Governance-Aufruf autorisiert die Ausführung des registrierten Connectors. Span-Export zeichnet Aktivität auf und hat keine Autorisierungswirkung.

Für Node.js:

npm install @kla-digital/governance @kla-digital/otel-node @opentelemetry/api

import '@kla-digital/otel-node';
import { trace } from '@opentelemetry/api';

const activeSpan = trace.getActiveSpan()?.spanContext();
const result = await client.executeAction(action, {
  proposalId,
  trace: activeSpan
    ? { traceId: activeSpan.traceId, spanId: activeSpan.spanId }
    : undefined,
});

Für Python:

pip install kla-governance kla-otel-python

from opentelemetry import trace

span_context = trace.get_current_span().get_span_context()
correlation = None
if span_context.is_valid:
    correlation = {
        "trace_id": format(span_context.trace_id, "032x"),
        "span_id": format(span_context.span_id, "016x"),
    }

result = client.execute_action(
    action,
    proposal_id=proposal_id,
    trace=correlation,
)

Siehe den Node.js-OpenTelemetry-SDK-Leitfaden oder den Python-OpenTelemetry-SDK-Leitfaden für Framework-Instrumentierung und Collector-Einrichtung.

Eine Ablehnung sauber behandeln

Ein Prüfer kann die Escalation ablehnen, oder die Policy kann einen harten block zurückgeben. Beide Fälle werden aus dem Ausführungshelfer als DecisionDenied mit der aufgelösten Entscheidung sichtbar. Das Ergebnis wird aufgezeichnet. Behandeln Sie die Ausnahme als erwarteten Zweig:

• Reason Codes lesen. Jede Entscheidung außer allow enthält maschinenlesbare reason_codes (zum Beispiel PAYMENT_OVER_THRESHOLD) und eine menschenlesbare remediation. Verzweigen Sie nach Codes; parsen Sie niemals die Prosa.
• Ablehnung sichtbar machen. Geben Sie dem aufrufenden Nutzer oder vorgelagerten Agenten eine klare Meldung zurück („Zahlung erfordert die Genehmigung eines Managers und wurde abgelehnt“). Die Ablehnung ist bereits als Lineage Record aufgezeichnet, daher müssen Sie sie nicht zusätzlich für das Audit protokollieren.
• Nicht blind wiederholen. Eine abgelehnte Aktion darf nicht automatisch in denselben Checkpoint zurückspringen. Eskalieren Sie in Ihrem eigenen Produkt zu einem menschlichen Pfad.

Wenn das Versiegeln der Nachweise nach dem Connector-Lauf unvollständig bleibt, wirft der Ausführungshelfer ExecutionEvidencePending und hält jedes von diesem Zustand getragene Ergebnis zurück. Der Fehler bewahrt Entscheidungs- und Receipt-Referenzen der Proposal zur Abstimmung. Bewahren Sie diese Proposal-Identität; eine neue Identität stellt eine neue logische Aktion dar.

Beide SDKs validieren die vollständige Ingress-Antwort, bevor sie Entscheidung oder Ergebnis freigeben. Schema-Version, Proposal- und Aktionsidentität, Lebenszykluszustände, Ergebnishash und Receipt-Referenzen müssen übereinstimmen. Eine fehlerhafte Antwort löst KLATransportError mit response_schema_invalid aus.

Vor dem Ausliefern

Erstellen Sie die Sperrpolicy 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 und eine geringwertige zu allow aufgelöst wird. Nach der Validierung wird die Policy in ein signiertes Policy Pack kompiliert und live geschaltet. Danach erzeugt jeder geschützte Aufruf eine belastbare Spur: Anfrage, Ergebnis, Prüferurteil und resultierende Aktion, alles als Lineage Record erfasst und später als Sealed Evidence Bundle exportierbar.