Lineage Explorer | Developer Docs

Il Lineage Explorer (/trace-explorer) è il punto in cui ricostruisci con precisione cosa ha fatto un agente AI, in quale ordine e con quali dati. Trasforma gli span OpenTelemetry emessi dai tuoi agenti strumentati in una timeline di esecuzione leggibile, per poi consentirti di verificare quella timeline rispetto a un registro crittografico, così da poterne dimostrare l'integrità a un auditor. Un Lineage Record è il nome che KLA assegna a una singola traccia: l'albero completo e ordinato di tutti i passaggi di un'esecuzione di un agente, dal prompt che la innesca, attraverso ogni chiamata a uno strumento, fino all'output finale.

L'Explorer si rivolge a due lettori contemporaneamente. Uno sviluppatore lo usa per fare il debug di un'esecuzione anomala. Un responsabile della compliance, del rischio o dell'audit lo usa per ricostruire a posteriori esattamente cosa è accaduto e per dimostrare che nulla è stato alterato. Entrambi lavorano sullo stesso record.

Timeline di esecuzione

Ogni esecuzione governata produce un albero di span. L'Explorer rappresenta quell'albero come una timeline, così da poter cogliere a colpo d'occhio la forma e la durata dell'esecuzione, per poi approfondire qualsiasi passaggio.

Passaggi annidati: costruzione del prompt, completamenti del modello, letture di recupero, query al database e chiamate HTTP in uscita, con orario di inizio, durata e relazioni padre-figlio.
Attributi semantici GenAI: ogni passaggio porta con sé i campi GenAI standard di OpenTelemetry, tra cui genai.agent.name, genai.system.instructions, genai.tool.name, genai.tool.parameters, genai.token.usage e genai.cost.usd.
Esiti delle policy in linea: nei punti in cui un passaggio ha interpellato il policy engine, la timeline mostra la decisione (allow, warn, require_approval o block), così da vedere governance ed esecuzione fianco a fianco.

ℹ️ Note

Gli span passano attraverso il **KLA Collector**, che oscura le informazioni personali (PII) prima che qualsiasi dato venga archiviato. L'Explorer mostra il record già oscurato, in modo che l'analisi non riesponga gli input sensibili.

flowchart TD
  A["Prompt di innesco"] --> B["Passaggio di pianificazione"]
  B --> C["Tool: lookup_claim"]
  B --> D["Tool: fetch_policy_doc"]
  C --> E{"Decisione di policy"}
  D --> E
  E -->|allow| F["Completamento del modello"]
  E -->|require_approval| G["Decision Desk"]
  F --> H["Output finale"]

Lineage dei dati lungo le catene di agenti

I sistemi moderni concatenano gli agenti: l'output di un agente diventa l'input di un altro. L'Explorer segue un valore attraverso quei confini, così da poter rispondere alla domanda "da dove proviene questo campo?". Quando un orchestratore passa a un sub-agente un riferimento cliente, e quel sub-agente recupera un documento usato per redigere una risposta finale, il lineage collega l'input di origine a ogni passaggio a valle che lo ha consumato. Per uno sviluppatore alle prese con un output errato, questo riduce ore di grep nei log a un singolo percorso da seguire. Per un auditor, stabilisce la provenienza: quali dati di origine hanno influenzato quale decisione.

Verifica tramite Merkle proof

Una timeline costituisce una prova solo se puoi dimostrare che non è stata modificata. Man mano che gli span vengono registrati, i loro hash vengono ancorati in un registro crittografico ImmuDB, un archivio append-only che mantiene un albero di Merkle su ogni voce. Per verificare un Lineage Record, l'Explorer ricalcola l'hash del record e percorre il path di Merkle fino alla radice ancorata.

Corrispondenza conferma che il record è byte per byte identico a quanto sigillato al momento dell'esecuzione.
Mancata corrispondenza segnala una manomissione o una corruzione da indagare.

🛡️ Important

La verifica è indipendente. La prova regge anche se non ti fidi più dell'applicazione che ha generato il record: è proprio questo a rendere un Lineage Record una prova difendibile e non un semplice log.

sequenceDiagram
  participant U as Revisore
  participant LE as Lineage Explorer
  participant L as Registro ImmuDB
  U->>LE: Apri il Lineage Record
  LE->>LE: Ricalcola l'hash del record
  LE->>L: Richiedi il Merkle proof
  L-->>LE: Path fino alla radice ancorata
  LE->>U: Verificato o Manomesso

Puoi recuperare lo stato di verifica di un record tramite l'API:

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

Esportazione verso l'Evidence Room

Quando un record (o un insieme filtrato di record relativi a un incidente o a una finestra di audit) deve uscire dall'Explorer come artefatto formale, lo inoltri all'Evidence Room. Lì viene impacchettato in un Sealed Evidence Bundle: record firmati, lineage completo, stato delle policy e log di verifica, pronti per essere condivisi con un'autorità di regolamentazione o allegati a un Control Pack. L'Explorer è il luogo in cui indaghi; l'Evidence Room è il luogo in cui certifichi ed esporti.