halo-record

Audit trail a prova di manomissione per agenti AI — Runtime Record concatenati tramite hash, visualizzati come Runtime Report che i tuoi clienti possono verificare autonomamente.

Ogni azione compiuta dal tuo agente (chiamate a strumenti, chiamate a modelli, accesso ai dati, approvazioni) diventa un Runtime Record in un log append-only concatenato tramite hash; il Runtime Report è quella catena visualizzata come pagina HTML auto-verificante. Qualsiasi parte in possesso di un checkpoint della catena può verificare che i record sottostanti non siano mai stati alterati, senza fidarsi di chi li ha prodotti — quel checkpoint è il pezzo portante: la sola catena è a prova di manomissione contro tutti tranne che contro chi gestisce il registratore (LIMITS.md §1). Quando il team di sicurezza di un cliente chiede "cosa ha fatto il tuo agente con i nostri dati?", gli consegni un link invece di un paragrafo. Le revisioni di sicurezza pongono già domande sull'AI accanto alla checklist SOC 2 — e sempre più spesso quelle domande provengono da ISO 42001, dagli articoli sulla conservazione dei registri dell'EU AI Act e dai questionari dei clienti stessi. Oggi un'assicurazione scritta passa ancora. La scommessa dietro questo progetto è che non durerà a lungo.

Segnalato su Help Net Security (agosto 2026).

Il formato dei record è aperto e libero da implementare. Questo pacchetto è l'implementazione di riferimento: registratore, verificatore, client witness e server di report.

Stai usando halo-record o ci stai pensando? Dimmi chi sei e per cosa → Chi sta usando halo-record?

Verificalo tu stesso

Ti viene chiesto di inserire un registratore dentro il tuo agente. Non dovresti accettarlo sulla fiducia:

• Zero dipendenze a runtime. Solo libreria standard. pip install halo-record installa esattamente un pacchetto.
• Nessuna chiamata di rete, tranne tre opt-in — ancoraggio a un witness (invia l'id del soggetto, un conteggio dei record e due impronte della catena — la testa e la radice della catena), lettura dei checkpoint di un witness (invia l'id del soggetto) e il timestamp RFC 3161 (invia solo l'hash di stato di un checkpoint a una Timestamp Authority). Tutte disattivate a meno che tu non le invochi; il contenuto dei record non lascia mai la tua infrastruttura.
• Gli argomenti grezzi degli strumenti vengono hashati, con un riepilogo redatto a fianco. Gli argomenti sono memorizzati come hash canonico più un riepilogo: il testo dell'argomento con i pattern noti di segreti e PII mascherati, limitato a 200 caratteri. Un input breve che non corrisponde ad alcun pattern appare per intero nel riepilogo; la modalità solo-hash (summaries=False) non conserva alcun riepilogo. La redazione è best-effort (regex sui formati comuni di segreti e PII più un catch-all basato sull'entropia): trattala come difesa in profondità, non come garanzia. I campi di esito che fornisci oltre a summary vengono sigillati così come sono (LIMITS §13).
• Abbastanza piccolo da poter essere verificato. ~5.300 righe di Python (righe di codice, escludendo righe vuote e commenti). Leggile tutte in un pomeriggio.
• Apache-2.0.
• La documentazione è di prim'ordine. LIMITS.md (cosa la catena non può dimostrare), PRIVACY.md (cosa contengono i record e cosa lascia la tua macchina), RETENTION.md (operare sotto una policy di conservazione) e REVIEWERS.md — il controllo indipendente in quattro comandi più un formato di citazione per i risultati della revisione.

Cosa dimostra ciascun livello — la distinzione portante in questo progetto (LIMITS.md §1): una catena che possiedi tu stesso dimostra che i record non sono stati modificati, rispetto a una testa che qualcuno già possiede; solo i checkpoint detenuti al di fuori dell'operatore dimostrano che nessuno è stato rimosso; e nessun hash dimostra che ogni azione sia stata catturata.

Affermazione	Catena auto-detentua	+ Checkpoint esterni	+ Cattura attendibile
Rilevare modifiche a un artefatto stabilito	✔	✔	✔
Rilevare la riscrittura della storia consolidata	—	✔	✔
Rilevare checkpoint mancanti/in ritardo	—	✔ (cadenza concordata)	✔
Dimostrare che ogni azione è stata registrata	—	—	dipende dal confine di cattura

Vedine uno prima di installare: un Runtime Report di esempio — dati fittizi, catena reale, e si ri-verifica da solo nel tuo browser mentre guardi.

Demo in 60 secondi

Nessun agente richiesto. Con uv, niente da installare:``` uvx --from halo-record halo demo --serve

o nel modo classico:```
pip install halo-record
halo demo --serve

Either one scaffolds a fictional support-agent vendor with two customers, witnesses the chains (with a local witness file standing in for one outside the operator — see LIMITS.md §1), serves their gated Runtime Reports, and opens the operator console in your browser. Then try the tamper test: delete a line from one of the .jsonl files and reload. The report catches it.

Registra il tuo agente

Una riga al confine:```python from halo_record import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls

Anche uno shim di comodo `from halo import ...` viene fornito — ma il nome `halo` su PyPI appartiene a un pacchetto terminal-spinner non correlato, e se quel pacchetto è installato vince l'import. `halo_record` è inequivocabile, quindi gli esempi lo usano.

Senza `log=`, i record vanno in `~/.halo/my-agent.jsonl` (una catena per agente). Il wrapper sigilla il confine di esecuzione; l'evidenza risiede nei record per chiamata. Catturali con un adattatore di framework (matrice sotto) — oppure esplicitamente, il che mostra anche come si collegano le deleghe:```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:            # one sealed record per tool call
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:                      # child links to the action that spawned it
    call.result = payments.refund(120)

Poi genera il report:``` halo report audit.jsonl -o report.html # one chain -> self-verifying HTML halo serve ./records --port 8721 # all tenants, gated per customer

Il quickstart termina quando stai guardando il Runtime Report del tuo agente in un browser. Se hai ottenuto un file JSONL e nessun report, qualcosa non va: apri una issue.

### Il blocco di verifica

Se un guardrail o un livello di policy ha controllato l'azione, il suo verdetto può viaggiare sul record — un blocco opzionale che registra ciò che il gate ha deciso, sigillato nella catena di hash come ogni altro campo:```python
from halo_record import build