Añadir una compuerta de aprobación humana

Algunas acciones de los agentes son demasiado trascendentales para ejecutarse sin supervisión: eliminar una cuenta, procesar un pago, publicar un documento. Esta guía muestra cómo envolver una de esas llamadas en una compuerta de aprobación humana usando el SDK de KLA Control Plane. KLA Control Plane es una capa de seguridad, auditoría y gobernanza en tiempo de ejecución que gobierna sobre el terreno (govern-in-place): usted instrumenta el código de su agente existente en lugar de migrarlo a otra plataforma. Un único checkpoint basta para que una llamada de herramienta se detenga a la espera de una persona, se enrute a un revisor y se reanude solo tras una aprobación explícita.

Cómo funciona una compuerta

Usted envuelve la llamada de riesgo en un checkpoint. El checkpoint envía un Decision Request (la acción junto con su contexto) al KLA policy engine, que lo resuelve en uno de cuatro resultados, según el orden de precedencia: allow, warn, require_approval o block. Cuando la política devuelve require_approval, la ejecución se pausa. KLA abre una Escalation (una unidad de trabajo pausada a la espera de una persona) y la enruta al Decision Desk, el espacio de trabajo donde los revisores autorizados aprueban o deniegan las acciones pendientes. La llamada del SDK se bloquea hasta que un revisor decide y, entonces, devuelve el control a su código.

sequenceDiagram
  participant App as Su agente
  participant KLA as Checkpoint de KLA
  participant Desk as Decision Desk
  App->>KLA: checkpoint("process_payment", context)
  KLA->>KLA: Evaluar Decision Request
  Note over KLA: outcome = require_approval
  KLA->>Desk: Abrir Escalation
  Desk-->>KLA: El revisor aprueba o deniega
  KLA-->>App: Decisión resuelta
  App->>App: Ejecutar o gestionar la denegación

Añadir el checkpoint

A continuación, se aplica una compuerta a una llamada de alto riesgo process_payment. El SDK se bloquea en el checkpoint hasta que la Escalation se resuelve en el Decision Desk. Usted adjunta atributos de negocio (importe, nivel del cliente) para que la política pueda decidir y para que el revisor vea el contexto real.

Python

from kla_otel import KLACheckpoint, DecisionDenied

checkpoint = KLACheckpoint(agent_id="agt_9f81a7")

def process_payment(account_id: str, amount: float):
    # Se bloquea aquí si la política devuelve require_approval, hasta que un
    # revisor resuelva la Escalation en el Decision Desk.
    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 que fue denegada, o un block estricto.
    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) {
  // Espera el veredicto del revisor si la política devuelve require_approval.
  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})`,
  );
}

Configure el SDK una sola vez, al iniciar, con su tenant y un token de acceso. Cada llamada de checkpoint envía Authorization: Bearer <token> y x-tenant-id: <tenant> a https://api.kla.digital en su nombre.

Gestionar una denegación con elegancia

Un revisor puede denegar la Escalation, o la política puede devolver un block estricto. Ambos casos llegan como una decisión resuelta y no aprobada, no como un error de red. Trátelos como una rama esperada:

• Lea los reason codes. Cada decisión distinta de allow lleva reason_codes legibles por máquina (por ejemplo PAYMENT_OVER_THRESHOLD) y remediation legible por personas. Ramifique en función de los códigos; nunca analice el texto descriptivo.
• Comunique, no deje que falle. Devuelva un mensaje claro al usuario que realiza la llamada o al agente que está más arriba ("El pago requiere la aprobación de un responsable y fue rechazado"). La denegación ya queda registrada como un Lineage Record, así que no necesita registrarla por separado para la auditoría.
• No reintente a ciegas. Una acción denegada no debe volver automáticamente al mismo checkpoint en bucle. En su lugar, escale a una vía humana dentro de su propio producto.

Antes de pasar a producción

Redacte la política de la compuerta en el Policy Builder y ejecute una Simulation: reproduzca Decision Requests representativos contra el borrador y confirme que un pago de alto valor se resuelve en require_approval mientras que uno de bajo valor se resuelve en allow. Una vez validada, la política se compila en un policy pack firmado y entra en producción. A partir de ese momento, cada llamada con compuerta genera un rastro defendible: la solicitud, el resultado, el veredicto del revisor y la acción resultante, todo capturado como un Lineage Record que podrá exportar más adelante como un Sealed Evidence Bundle.