Governare un agente end-to-end | Developer Docs

Questa guida ti accompagna attraverso l'intero ciclo del control plane su un singolo esempio generico: un agente di triage dei sinistri che legge i sinistri in entrata e può emettere rimborsi. Alla fine avrai registrato l'agente, scritto una policy che mette in pausa qualsiasi rimborso oltre una soglia, eseguito un'esecuzione che attiva quel gate, approvato l'azione come operatore umano, rieseguito il run ed esportato un record a prova di manomissione per un revisore.

Il principio di fondo è quello dell'autonomia governata: l'agente raccomanda un'azione, ma è la policy a mantenere l'autorità sul fatto che venga eseguita. L'agente resta veloce sulle attività a basso rischio e si ferma per un intervento umano esattamente dove la posta in gioco lo giustifica. KLA Control Plane è un livello di governance in loco: applichi la strumentazione al tuo agente esistente invece di ricostruirlo su una nuova piattaforma, quindi questo ciclo avvolge codice che già possiedi.

Tutto quanto segue utilizza l'host API live https://api.kla.digital con due header: un bearer token e il tuo tenant ID. Esportali una volta sola:

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

sequenceDiagram
  participant Dev as Sviluppatore
  participant Agent as Agente sinistri
  participant KLA as KLA Control Plane
  participant Desk as Decision Desk
  participant Room as Evidence Room
  Dev->>KLA: 1. Registra l'agente
  Agent->>KLA: 3. Esegui esecuzione (rimborso $1.250)
  KLA->>KLA: 2. Valuta la policy
  KLA->>Desk: require_approval -> Escalation
  Desk->>KLA: 4. Il revisore approva
  KLA->>Agent: Riprendi esecuzione
  Dev->>KLA: 5. Riesegui in Lineage Explorer
  KLA->>Room: 6. Esporta Sealed Evidence Bundle

Passo 1: registra l'agente

Registrare un agente lo dichiara al Control Plane e gli assegna un'identità stabile a cui fa riferimento ogni passo successivo. Il manifest dà un nome all'agente, elenca i tool che gli è consentito chiamare e assegna un proprietario. Il tool process_refund è quello che governeremo.

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 risposta restituisce un agentId (ad esempio agt_9f81a7). L'agente ora compare nell'Agent Registry, l'inventario di ogni agente governato, del suo proprietario e del suo stato di release corrente.

Passo 2: scrivi una policy che richiede l'approvazione

La policy è dichiarativa e viene valutata dal KLA Policy Engine a livello applicativo. Scriviamo due regole per execute_refund: i rimborsi piccoli procedono, mentre i rimborsi oltre la soglia si fermano in attesa di un intervento umano. KLA risolve la policy in quattro esiti, in ordine di precedenza: allow, warn, require_approval, block. Qui la regola sui rimborsi di alto valore si risolve in require_approval (una pausa per un revisore) anziché in block (uno stop definitivo).

# 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

Scrivi questa policy nel Policy Builder, esegui una Simulation per confermare che una richiesta di prova da $1.250 si risolva in require_approval, poi pubblica. Al momento della pubblicazione viene compilata in un policy pack firmato, in modo che la valutazione live sia veloce e a prova di manomissione.

💡 Tip

Simula sempre prima di pubblicare. Una Simulation riesegue richieste rappresentative sulla bozza, così confermi che ciascuna si risolva nell'esito che ti aspetti, senza alcun effetto sugli agenti in esecuzione.

Passo 3: esegui un'esecuzione governata che attiva il gate

Ora esegui l'agente su un sinistro che richiede un rimborso elevato. Il tuo agente strumentato invia una Decision Request (l'azione più il suo contesto di business) prima di chiamare process_refund. Poiché l'importo supera la soglia, la policy restituisce require_approval e apre un'Escalation invece di lasciar passare il rimborso.

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'esecuzione è in pausa, non è fallita. Tratta require_approval come un'attesa asincrona e mostra lo stato in sospeso all'utente finale.

Passo 4: approva sul Decision Desk

L'Escalation ora attende nel Decision Desk, dove un revisore autorizzato vede l'azione, il suo importo, i reason code e le indicazioni di remediation. Approvare riprende l'esecuzione originale esattamente nel punto in cui si era fermata; rifiutare la interrompe. Un revisore può agire nell'interfaccia o tramite 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." }'

Il rimborso ora viene eseguito. L'operatore umano ha mantenuto l'autorità sull'azione rilevante, mentre l'agente ha svolto in autonomia tutto il resto.

Passo 5: riesegui il run in Lineage Explorer

Ogni run governato diventa un Lineage Record: l'albero ordinato dei passaggi, dal prompt scatenante fino a ogni chiamata di tool e all'output finale. Aprilo nel Lineage Explorer per riprodurre esattamente ciò che è accaduto: l'esito della policy inline, gli attributi GenAI (genai.tool.name, genai.tool.parameters, genai.cost.usd, genai.token.usage) e l'approvazione. Verificare un record ne percorre il Merkle proof fino alla radice del ledger ancorato.

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

Una corrispondenza conferma che il record è byte per byte identico a quello sigillato al momento dell'esecuzione. La verifica è indipendente dall'applicazione che lo ha prodotto, ed è proprio questo a rendere il record una prova anziché un semplice log.

Passo 6: esporta un Sealed Evidence Bundle

Infine, inoltra il record (o una finestra filtrata) alla Evidence Room e impacchettalo come Sealed Evidence Bundle: record firmati, lineage completo, lo stato della policy applicato e i log di verifica.

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 è una prova portabile. Consegnalo a un revisore o allegalo a un **Control Pack** (un export di conformità che mappa le tue azioni governate su specifici controlli di un framework) e potranno verificarne l'integrità senza alcun accesso ai tuoi sistemi.

Hai ora eseguito il ciclo completo: registra, governa, regola con gate, approva, riesegui, dimostra. Gli stessi sei passi si applicano a qualsiasi azione rilevante di un agente, che si tratti di un documento inviato per revisione, di un record aggiornato o di una API esterna chiamata, ovunque tu voglia che l'agente proceda rapidamente e che la policy mantenga l'autorità.