Gobierne un agente de extremo a extremo | Developer Docs

Esta guía le acompaña por el ciclo completo del control plane sobre un único ejemplo genérico: un agente de clasificación de reclamaciones que lee las reclamaciones entrantes y puede emitir reembolsos. Al terminar habrá registrado el agente, escrito una política que pausa cualquier reembolso por encima de un umbral, ejecutado el agente de forma que active ese control, aprobado la acción usted mismo como persona, reproducido la ejecución y exportado un registro a prueba de manipulaciones para un auditor.

El principio que guía todo el proceso es la autonomía gobernada: el agente recomienda una acción, pero la política mantiene la autoridad sobre si esa acción se ejecuta. El agente conserva su rapidez en el trabajo de bajo riesgo y se pausa para que intervenga una persona justo cuando lo que está en juego lo justifica. KLA Control Plane es una capa de gobierno en el propio lugar: usted instrumenta su agente existente en lugar de migrarlo a otra plataforma, de modo que este ciclo envuelve el código que ya tiene.

Todo lo que sigue utiliza el host de API en producción https://api.kla.digital con dos encabezados: un token bearer y el ID de su tenant. Expórtelos una sola vez:

export KLA_TOKEN="<paste access_token>"
export KLA_TENANT="acme-claims"

sequenceDiagram
  participant Dev as Desarrollador
  participant Agent as Agente de reclamaciones
  participant KLA as KLA Control Plane
  participant Desk as Decision Desk
  participant Room as Evidence Room
  Dev->>KLA: 1. Registrar el agente
  Agent->>KLA: 3. Ejecutar (reembolso $1,250)
  KLA->>KLA: 2. Evaluar la política
  KLA->>Desk: require_approval -> Escalation
  Desk->>KLA: 4. El revisor aprueba
  KLA->>Agent: Reanudar la ejecución
  Dev->>KLA: 5. Reproducir en Lineage Explorer
  KLA->>Room: 6. Exportar Sealed Evidence Bundle

Paso 1: registrar el agente

Registrar un agente lo declara ante el Control Plane y le otorga una identidad estable a la que hacen referencia todos los pasos posteriores. El manifiesto nombra al agente, enumera las herramientas que tiene permitido invocar y le asigna un propietario. La herramienta process_refund es la que vamos a gobernar.

curl -X POST https://api.kla.digital/v1/agents \
  -H "Authorization: Bearer $KLA_TOKEN" \
  -H "x-tenant-id: $KLA_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claims-triage",
    "description": "Triages inbound claims and issues refunds",
    "owner": "claims-ops",
    "tools": ["lookup_claim", "process_refund"]
  }'

La respuesta devuelve un agentId (por ejemplo, agt_9f81a7). El agente aparece ahora en el Agent Registry, el inventario de todos los agentes gobernados, su propietario y su estado de release actual.

Paso 2: redactar una política que requiera aprobación

La política es declarativa y la evalúa el KLA Policy Engine en la capa de aplicación. Escribimos dos reglas para execute_refund: los reembolsos pequeños siguen adelante y los reembolsos por encima del umbral se pausan para que intervenga una persona. KLA resuelve la política en cuatro resultados según un orden de precedencia: allow, warn, require_approval, block. Aquí la regla de alto valor se resuelve en require_approval (una pausa para un revisor) y no en block (una detención total).

# claims-triage policy (illustrative): refunds over $100 pause for review
- rule: low-value-refund
  when:
    tool: execute_refund
    amount: "<= 100.00"
  then:
    decision: allow
    reasonCode: REFUND_WITHIN_THRESHOLD

- rule: high-value-refund
  when:
    tool: execute_refund
    amount: "> 100.00"
  then:
    decision: require_approval
    reasonCode: REFUND_OVER_THRESHOLD
    route: Decision Desk

Redáctela en el Policy Builder, ejecute una Simulation para confirmar que una solicitud de prueba de $1,250 se resuelve en require_approval y luego publíquela. Al publicar, se compila en un paquete de políticas firmado, de modo que la evaluación en vivo es rápida y a prueba de manipulaciones.

💡 Tip

Simule siempre antes de publicar. Una Simulation reproduce solicitudes representativas contra el borrador para que confirme que cada una se resuelve en el resultado que espera, sin afectar a los agentes en ejecución.

Paso 3: lanzar una ejecución gobernada que active el control

Ahora ejecute el agente contra una reclamación que requiere un reembolso elevado. Su agente instrumentado envía una Decision Request (la acción más su contexto de negocio) antes de invocar process_refund. Como el importe supera el umbral, la política devuelve require_approval y abre una Escalation en lugar de dejar pasar el reembolso.

curl -X POST https://api.kla.digital/v1/decisions.evaluate \
  -H "Authorization: Bearer $KLA_TOKEN" \
  -H "x-tenant-id: $KLA_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claims-triage",
    "action": "execute_refund",
    "attributes": { "amount": 1250.00, "claim_id": "clm_9921" }
  }'

{
  "outcome": "require_approval",
  "reasonCodes": ["REFUND_OVER_THRESHOLD"],
  "remediation": "Refunds above $100 require a reviewer. Routed to the Decision Desk.",
  "escalationId": "esc_01HZ8K"
}

La ejecución está pausada, no ha fallado. Trate require_approval como una espera asíncrona y muestre el estado pendiente al usuario final.

Paso 4: aprobar en el Decision Desk

La Escalation espera ahora en el Decision Desk, donde un revisor autorizado ve la acción, su importe, los códigos de razón y la guía de remediación. Aprobar reanuda la ejecución original exactamente donde se pausó; rechazar la detiene. Un revisor puede actuar desde la UI o a través de la API.

curl -X POST https://api.kla.digital/v1/escalations/esc_01HZ8K/approve \
  -H "Authorization: Bearer $KLA_TOKEN" \
  -H "x-tenant-id: $KLA_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Verified claim documentation; refund authorized." }'

El reembolso se ejecuta ahora. La persona conservó la autoridad sobre la acción de consecuencias mientras el agente hizo todo lo demás de forma autónoma.

Paso 5: reproducir la ejecución en Lineage Explorer

Cada ejecución gobernada se convierte en un Lineage Record: el árbol ordenado de pasos desde el prompt que la desencadena, pasando por cada llamada a herramienta, hasta la salida final. Ábralo en el Lineage Explorer para reproducir exactamente lo que ocurrió: el resultado de la política en línea, los atributos de GenAI (genai.tool.name, genai.tool.parameters, genai.cost.usd, genai.token.usage) y la aprobación. Verificar un registro recorre su Merkle proof hasta la raíz del ledger anclada.

curl https://api.kla.digital/v1/lineage/lr_8f21/verify \
  -H "Authorization: Bearer $KLA_TOKEN" \
  -H "x-tenant-id: $KLA_TENANT"

Una coincidencia confirma que el registro es byte por byte lo que se selló en el momento de la ejecución. La verificación es independiente de la aplicación que lo produjo, y eso es lo que convierte al registro en evidencia y no en un simple log.

Paso 6: exportar un Sealed Evidence Bundle

Por último, reenvíe el registro (o una ventana filtrada) al Evidence Room y empaquételo como un Sealed Evidence Bundle: registros firmados, lineage completo, el estado de la política que se aplicó y los logs de verificación.

curl -X POST https://api.kla.digital/v1/evidence/bundles \
  -H "Authorization: Bearer $KLA_TOKEN" \
  -H "x-tenant-id: $KLA_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "lineageRecords": ["lr_8f21"], "format": "pdf" }'

ℹ️ Note

Un Sealed Evidence Bundle es una prueba portable. Entréguelo a un auditor o adjúntelo a un **Control Pack** (una exportación de cumplimiento que mapea sus acciones gobernadas a controles específicos de un marco normativo) y podrá verificar la integridad sin ningún acceso a sus sistemas.

Ya ha ejecutado el ciclo completo: registrar, gobernar, controlar, aprobar, reproducir, probar. Los mismos seis pasos se aplican a cualquier acción de un agente con consecuencias, ya sea un documento enviado a revisión, un registro actualizado o una API externa invocada, allí donde desee que el agente avance rápido y que la política conserve la autoridad.