Guida rapida | Developer Docs | KLA Control Plane

Questa guida ti permette di iniziare a usare KLA Digital. Installerai un SDK di telemetria nativo, registrerai un agente governato, eseguirai un'esecuzione con checkpoint umani ed esporterai un pacchetto di prove sigillato crittograficamente.

Passo 1: installa un SDK di telemetria

KLA si integra con i framework standard tramite strumentazione OpenTelemetry nativa. Scegli il tuo linguaggio:

Node.js

pnpm add @kla-digital/otel-node

Python

pip install kla-otel-python

ℹ️ Note

L'SDK si aggancia automaticamente alle librerie più comuni come Express, FastAPI, LangChain e OpenAI, catturando i prompt di input, i vincoli di sistema, i costi in token e i parametri degli strumenti.

Passo 2: indirizza OTLP verso KLA

Configura le variabili d'ambiente del tuo servizio per instradare gli span di telemetria attraverso il KLA Collector. Puoi recuperare l'endpoint API specifico e i token del tuo tenant dalla KLA Console.

OTEL_SERVICE_NAME=claims-triage-agent
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.kla.digital/collector
KLA_TENANT_ID=kpmg-reporting
KLA_API_KEY=kla_sec_prod_8f2d89a2
KLA_PII_MASK=true

💡 Tip

Impostare `KLA_PII_MASK=true` garantisce che eventuali stringhe sensibili, password o dati personali vengano oscurati prima di lasciare il container di esecuzione.

Passo 3: registra il tuo agente

Registra la dichiarazione di un nuovo agente inviando un manifest al KLA Control Plane. Questo definisce il nome dell'agente, la descrizione, i parametri e l'elenco degli strumenti consentiti:

curl -X POST https://api.kla.digital/execution/v1/agents \
  -H "Authorization: Bearer $KLA_API_KEY" \
  -H "x-tenant-id: $KLA_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claims-bot",
    "description": "Triages inbound customer claims with human-approval gates",
    "model": "gpt-4o-mini",
    "temperature": 0.2,
    "tools": ["search_claims_db", "process_refund"]
  }'

La risposta del server restituirà un agentId stabile (ad esempio agt_9f81a7) e un manifestHash compilato che rappresenta lo stato della tua configurazione.

Passo 4: avvia un'esecuzione governata

Avvia una nuova esecuzione di workflow instradando la richiesta di esecuzione attraverso il KLA Engine. KLA valuta le policy attive in tempo reale. Se il prompt di input attiva una regola di sicurezza (ad esempio l'avvio di un rimborso superiore a 1000 $), KLA mette in pausa l'esecuzione e colloca l'attività nel Decision Desk per la revisione.

curl -X POST https://api.kla.digital/execution/v1/executions \
  -H "Authorization: Bearer $KLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_9f81a7",
    "input": { "prompt": "Process refund for claim #9921 for $1250.00" },
    "budgets": { "maxSteps": 50, "maxTokens": 20000, "maxCostUsd": 5 },
    "flags": { "euOnly": true }
  }'

Puoi rimanere in ascolto degli aggiornamenti dell'esecuzione e delle decisioni human-in-the-loop sottoscrivendoti allo stream WebSocket all'indirizzo: wss://api.kla.digital/execution/ws

Passo 5: esporta le prove firmate

Al termine delle esecuzioni, puoi scaricare i fogli di prova utilizzando l'utility da riga di comando kla. Questi pacchetti contengono Merkle proof firmate e voci di audit corrispondenti alle tracce esatte del workflow.

# Esporta gli ultimi 30 giorni come PDF
kla export evidence --tenant $KLA_TENANT_ID --days 30 --format pdf

# Filtra per uno specifico framework di conformità
kla export evidence --tenant $KLA_TENANT_ID --frameworks "SOC 2 Type II" --format csv

Il Sealed Evidence Bundle risultante è pronto per essere consegnato ad auditor o responsabili della conformità.