Riferimento API

KLA Control Plane espone una REST API per governare in loco gli agenti AI aziendali. Usala per registrare gli agenti che già esegui, valutare una decisione di policy prima che un'azione venga eseguita e recuperare la prova crittografica che un'esecuzione sia stata registrata nel registro a prova di manomissione. Questa pagina documenta i tre endpoint principali, oltre ad autenticazione, gestione degli errori e header operativi. KLA Control Plane è il livello di sicurezza, audit e governance a runtime che affianca i tuoi agenti esistenti invece di sostituirli.

Tutte le richieste sono delimitate per tenant e usano JSON su HTTPS. L'URL di base è:

https://api.kla.digital/v1

Autenticazione

Ogni richiesta deve includere un token bearer e un identificatore di tenant. Il token è un access token OAuth 2.0 di breve durata; l'header del tenant delimita la richiesta alla tua organizzazione. Consulta il documento Autenticazione per sapere come generare i token (accesso browser PKCE per gli utenti, oppure un client secret di un service account per l'accesso programmatico).

curl https://api.kla.digital/v1/agents \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod" \
  -H "Content-Type: application/json"

Registrare un agente

Dichiara un agente affinché KLA possa tracciarne identità, proprietà e versione nell'Agent Registry. La registrazione restituisce un agentId stabile e un hash firmato del manifest che puoi referenziare da span e decisioni di policy.

• Endpoint: POST /agents

Corpo della richiesta

{
  "name": "claims-triage",
  "description": "Triages inbound insurance claims",
  "model": "gpt-4.1",
  "temperature": 0.2,
  "tools": ["lookup_policy", "flag_for_review"]
}

Risposta: 201 Created

{
  "agentId": "agt_9f81a7",
  "manifestHash": "sha256:d8a29fbc81d293...",
  "registeredAt": "2026-06-01T10:48:00Z"
}

Valutare una decisione di policy

Invia un'azione di un agente e il relativo contesto al motore di policy. KLA valuta le tue policy pubblicate (YAML dichiarativo compilato in policy pack firmati) e restituisce uno tra quattro esiti, in ordine di precedenza: allow, warn, require_approval, block. Una decisione require_approval mette in pausa l'esecuzione e instrada un'Escalation al Decision Desk per la revisione umana, condizione che la risposta segnala con requiresDeskApproval: true.

• Endpoint: POST /decisions.evaluate

Corpo della richiesta

{
  "agentId": "agt_9f81a7",
  "action": "execute_refund",
  "context": {
    "amount": 1250.00,
    "user_id": "usr_22"
  }
}

Risposta: 200 OK

{
  "decision": "require_approval",
  "reasonCodes": ["AMOUNT_OVER_THRESHOLD"],
  "requiresDeskApproval": true,
  "decisionId": "dec_8f29e12"
}

Recuperare una prova di audit

Recupera la proof del registro per un determinato Lineage Record (trace). La proof ti consente di ricalcolare la catena di hash del record per confermare che sia internamente coerente con la root riportata da KLA. Per una verifica indipendente e offline che non si affidi a una risposta attiva di KLA, esporta e verifica un Sealed Evidence Bundle dall'Evidence Room.

• Endpoint: GET /lineage/{lineageId}/verify

Risposta: 200 OK

{
  "lineageId": "lr_99a1287fbc",
  "anchored": true,
  "ledgerIndex": 128994,
  "rootHash": "sha256:9f8d2e8ab219d...",
  "merklePath": [
    "sha256:bc892a76f...",
    "sha256:e829dc76a..."
  ]
}

Ricalcola la root a partire dall'hash della foglia e da merklePath e confrontala con il rootHash qui restituito per confermare che la catena di hash del record sia internamente coerente. Nota: il rootHash di questo endpoint è riportato da KLA; per una verifica offline e autosufficiente che non richieda una connessione attiva a KLA, verifica un Sealed Evidence Bundle dell'Evidence Room con kla evidence verify.

Errori e codici di stato

Gli errori restituiscono un corpo JSON con code e message. Usa lo stato HTTP per decidere il comportamento di retry.

{
  "code": "invalid_request",
  "message": "field 'amount' must be a number"
}

Limiti di frequenza e idempotenza

Le richieste sono soggette a un limite di frequenza per tenant; in caso di 429, applica un backoff e riprova dopo il valore di Retry-After. Per le chiamate in scrittura (POST /agents, POST /decisions.evaluate), invia un header Idempotency-Key con un valore univoco per rendere sicuri i retry. Riproporre la stessa chiave restituisce il risultato originale invece di creare un duplicato.