bkuan001/halo-recordTrilhas de auditoria à prova de adulteração para agentes de IA: Registros de Runtime encadeados por hash, sem dependências, verificáveis por qualquer pessoa.
Trilhas de auditoria à prova de adulteração para agentes de IA — Runtime Records encadeados por hash, renderizados como um Runtime Report que seus clientes podem verificar por conta própria.
Cada ação que seu agente executa (chamadas de ferramentas, chamadas de modelo, acesso a dados, aprovações) torna-se um Runtime Record em um log somente-anexável, encadeado por hash; o Runtime Report é essa cadeia renderizada como uma página HTML autoverificável. Qualquer parte que detenha um checkpoint da cadeia pode verificar que os registros por trás dele nunca foram alterados, sem confiar em quem os produziu — esse checkpoint é a peça fundamental: a cadeia sozinha é à prova de adulteração contra todos, exceto a parte que opera o gravador (LIMITS.md §1). Quando a equipe de segurança de um cliente pergunta "o que seu agente fez com nossos dados?", você entrega um link em vez de um parágrafo. As revisões de segurança já fazem perguntas sobre IA ao lado do checklist SOC 2 — e, cada vez mais, essas perguntas vêm da ISO 42001, dos artigos de manutenção de registros do EU AI Act e dos próprios questionários dos clientes. Hoje, uma garantia por escrito ainda passa. A aposta por trás deste projeto é que isso não durará muito.
Destaque em Help Net Security (agosto de 2026).
O formato de registro é aberto e livre para implementar. Este pacote é a implementação de referência: gravador, verificador, cliente de testemunha e servidor de relatórios.
Usando o halo-record, ou pensando nisso? Diga quem você é e para quê → Quem está usando o halo-record?
Estão pedindo que você coloque um gravador dentro do seu agente. Você não deveria aceitar isso pela fé:
pip install halo-record instala exatamente um pacote.summaries=False) não mantém resumo algum. A redação é feita na melhor medida possível (regex sobre formatos comuns de segredos e PII, além de uma captura genérica por entropia): trate-a como defesa em profundidade, não como garantia. Campos de resultado que você fornece além de summary são selados como estão (LIMITS §13).O que cada camada prova — a distinção fundamental neste projeto (LIMITS.md §1): uma cadeia que você mesmo detém prova que os registros não foram editados, em relação a um head que alguém já detém; apenas checkpoints mantidos fora do operador provam que nenhum foi removido; e nenhum hash prova que toda ação foi capturada.
| Alegação | Cadeia própria | + Checkpoints externos | + Captura confiável |
|---|---|---|---|
| Detectar edições em um artefato estabelecido | ✔ | ✔ | ✔ |
| Detectar reescrita de histórico consolidado | — | ✔ | ✔ |
| Detectar checkpoints ausentes/atrasados | — | ✔ (cadência acordada) | ✔ |
| Provar que toda ação foi registrada | — | — | depende do limite de captura |
Veja um antes de instalar: um Runtime Report de exemplo — dados fictícios, cadeia real, e ele se reverifica no seu navegador enquanto você observa.
Nenhum agente necessário. Com uv, nada para instalar:``` uvx --from halo-record halo demo --serve
ou da forma clássica:```
pip install halo-record
halo demo --serve
Qualquer um dos dois cria um fornecedor fictício de agente de suporte com dois clientes, testemunha as cadeias (com um arquivo de testemunha local representando uma fora do operador — consulte LIMITS.md §1), serve seus Runtime Reports com acesso restrito e abre o console do operador no seu navegador. Em seguida, experimente o teste de adulteração: exclua uma linha de um dos arquivos .jsonl e recarregue. O relatório detecta isso.
Uma linha no limite:```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
Um shim de conveniência `from halo import ...` também é fornecido — mas o nome `halo` no PyPI pertence a um pacote de spinner de terminal não relacionado, e se esse pacote estiver instalado, ele vence a importação. `halo_record` é inequívoco, então os exemplos o utilizam.
Sem `log=`, os registros vão para `~/.halo/my-agent.jsonl` (uma cadeia por agente). O wrapper sela o limite da execução; a evidência vive nos registros por chamada. Capture-os com um adaptador de framework (matriz abaixo) — ou explicitamente, o que também mostra como a delegação se vincula:```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)
Em seguida, renderize o relatório:``` halo report audit.jsonl -o report.html # one chain -> self-verifying HTML halo serve ./records --port 8721 # all tenants, gated per customer
O quickstart termina quando você está olhando o Runtime Report do seu próprio agente em um navegador. Se você obteve um arquivo JSONL e nenhum relatório, algo está errado: abra uma issue.
### O bloco de verificação
Se uma camada de guardrail ou de política verificou a ação, seu veredito pode acompanhar o registro — um bloco opcional que registra o que o gate decidiu, selado na cadeia de hash como qualquer outro campo:```python
from halo_record import build