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.

Eseguire la CLI KLA

La CLI KLA viene attualmente eseguita da questo monorepo. Dalla radice del repository, compilala con Node.js 20.x:

pnpm install --frozen-lockfile
pnpm exec turbo run build --filter=@kla/cli
alias kla='node /absolute/path/to/monolith/cli/dist/index.js'
kla --help

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 ricevere aggiornamenti sull'esecuzione e sulle decisioni con supervisione umana tramite lo 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.

# Export the last 30 days to a local directory
kla evidence export --tenant $KLA_TENANT_ID --days 30 --out ./evidence

# Export an exact time window
kla evidence export --tenant $KLA_TENANT_ID \
  --start-date 2026-07-01 \
  --end-date 2026-07-31 \
  --out ./evidence

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