Gouverner un agent de bout en bout

Ce guide vous accompagne à travers la boucle complète du control plane sur un exemple unique et générique : un agent de triage des réclamations qui lit les réclamations entrantes et peut émettre des remboursements. À la fin, vous aurez enregistré l'agent, écrit une politique qui met en pause tout remboursement dépassant un seuil, exécuté un traitement qui déclenche ce point de contrôle, approuvé celui-ci en tant qu'humain, rejoué l'exécution et exporté un enregistrement inviolable destiné à un auditeur.

Le principe sous-jacent est celui de l'autonomie gouvernée : l'agent recommande une action, mais la politique conserve l'autorité sur sa réalisation effective. L'agent reste rapide sur les tâches à faible risque et se met en pause précisément là où les enjeux le justifient. KLA Control Plane est une couche de gouvernance en place : vous instrumentez votre agent existant au lieu de le replateformer, de sorte que cette boucle vient envelopper du code que vous possédez déjà.

Tout ce qui suit utilise l'hôte d'API en production https://api.kla.digital avec deux en-têtes : un jeton bearer et votre identifiant de tenant. Exportez-les une seule fois :

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

sequenceDiagram
  participant Dev as Développeur
  participant Agent as Agent de réclamations
  participant KLA as KLA Control Plane
  participant Desk as Decision Desk
  participant Room as Evidence Room
  Dev->>KLA: 1. Enregistrer l'agent
  Agent->>KLA: 3. Lancer l'exécution (remboursement de 1 250 $)
  KLA->>KLA: 2. Évaluer la politique
  KLA->>Desk: require_approval -> Escalation
  Desk->>KLA: 4. Le relecteur approuve
  KLA->>Agent: Reprendre l'exécution
  Dev->>KLA: 5. Rejouer dans Lineage Explorer
  KLA->>Room: 6. Exporter un Sealed Evidence Bundle

Étape 1 : enregistrer l'agent

Enregistrer un agent revient à le déclarer auprès du Control Plane et à lui donner une identité stable que chaque étape ultérieure référence. Le manifeste nomme l'agent, énumère les outils qu'il est autorisé à appeler et lui attribue un propriétaire. L'outil process_refund est celui que nous allons gouverner.

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 réponse renvoie un agentId (par exemple agt_9f81a7). L'agent apparaît désormais dans l'Agent Registry, l'inventaire de chaque agent gouverné, de son propriétaire et de son état de release actuel.

Étape 2 : rédiger une politique qui exige une approbation

La politique est déclarative et évaluée par le KLA Policy Engine au niveau de la couche applicative. Nous écrivons deux règles pour execute_refund : les petits remboursements passent, et les remboursements dépassant le seuil se mettent en pause pour intervention humaine. KLA résout une politique en quatre issues, par ordre de priorité : allow, warn, require_approval, block. Ici, la règle de montant élevé aboutit à require_approval (une pause en attente d'un relecteur) plutôt qu'à block (un arrêt net).

# 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

Rédigez ceci dans le Policy Builder, lancez une Simulation pour confirmer qu'une requête de test à $1,250 aboutit à require_approval, puis publiez. À la publication, la politique est compilée en un pack de politiques signé, afin que l'évaluation en production soit rapide et inviolable.

Étape 3 : exécuter un traitement gouverné qui déclenche le point de contrôle

Lancez maintenant l'agent sur une réclamation nécessitant un remboursement important. Votre agent instrumenté soumet une Decision Request (l'action assortie de son contexte métier) avant d'appeler process_refund. Comme le montant dépasse le seuil, la politique renvoie require_approval et ouvre une Escalation au lieu de laisser passer le remboursement.

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"
}

L'exécution est mise en pause, pas en échec. Traitez require_approval comme une attente asynchrone et faites remonter l'état « en attente » jusqu'à l'utilisateur final.

Étape 4 : approuver sur le Decision Desk

L'Escalation patiente désormais dans le Decision Desk, où un relecteur autorisé voit l'action, son montant, les codes de motif et les consignes de remédiation. L'approuver reprend l'exécution d'origine exactement là où elle s'était interrompue ; la rejeter l'arrête. Un relecteur peut agir dans l'UI ou via l'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." }'

Le remboursement s'exécute alors. L'humain a conservé l'autorité sur l'action lourde de conséquences, tandis que l'agent accomplissait tout le reste de façon autonome.

Étape 5 : rejouer l'exécution dans Lineage Explorer

Chaque exécution gouvernée devient un Lineage Record : l'arbre ordonné des étapes, du prompt déclencheur jusqu'à la sortie finale en passant par chaque appel d'outil. Ouvrez-le dans le Lineage Explorer pour rejouer exactement ce qui s'est produit : l'issue de la politique en ligne, les attributs GenAI (genai.tool.name, genai.tool.parameters, genai.cost.usd, genai.token.usage) et l'approbation. Vérifier un enregistrement consiste à remonter sa Merkle proof jusqu'à la racine du registre ancré.

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

Une correspondance confirme que l'enregistrement est, octet pour octet, ce qui a été scellé au moment de l'exécution. La vérification est indépendante de l'application qui l'a produit, ce qui fait de cet enregistrement une preuve plutôt qu'un simple journal.

Étape 6 : exporter un Sealed Evidence Bundle

Enfin, transmettez l'enregistrement (ou une fenêtre filtrée) à l'Evidence Room et conditionnez-le en un Sealed Evidence Bundle : enregistrements signés, lineage complet, état de la politique appliquée et journaux de vérification.

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" }'

Vous venez d'exécuter la boucle complète : enregistrer, gouverner, encadrer, approuver, rejouer, prouver. Ces six mêmes étapes s'appliquent à toute action conséquente d'un agent, qu'il s'agisse d'un document envoyé en relecture, d'un enregistrement mis à jour ou d'un appel à une API externe, partout où vous voulez que l'agent aille vite et que la politique conserve l'autorité.