halo-record 

halo-record 是一个开源、轻量级的 Python 库，旨在为 AI 智能体（Agent）提供不可篡改的操作日志记录功能。它通过构建一个仅追加（Append-only）的哈希链日志，确保智能体执行的每一步操作都可被独立验证，且无法被服务提供商或开发者事后修改。这对于满足企业级安全合规要求（如 SOC 2）、建立用户信任以及解决“黑盒”焦虑至关重要。

核心设计理念：零信任与可验证性

在 AI 应用日益普及的今天，客户和安全团队不再满足于口头保证，他们需要确凿的证据来回答：“你的智能体对我的数据做了什么？” halo-record 通过以下机制提供数学级别的信任保障：

1. 哈希链结构：每条操作记录都包含前一条记录的哈希值，形成一条不可断裂的链条。任何对历史记录的篡改都会导致后续所有哈希校验失败。
2. 隐私优先：原始输入参数不会直接存入日志，而是经过哈希处理或以脱敏摘要形式存储，确保敏感数据不泄露。
3. 零运行时依赖：仅依赖 Python 标准库，无外部网络调用（除可选的见证服务外），代码量仅约 4,300 行，便于人工审计。
4. 开放格式：日志采用开放的 JSONL 格式，任何人都可以编写验证器重新计算哈希链，无需依赖特定厂商的工具。

快速开始

1. 体验演示

无需安装，直接使用 uv 运行交互式演示，模拟智能体操作并尝试篡改日志以观察验证失败的效果：

uvx --from halo-record halo demo --serve

2. 集成到现有智能体

只需在智能体的入口函数处添加一行装饰器代码，即可自动记录所有工具调用和执行步骤：

from halo import trace

# 包装你的智能体入口函数
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")

3. 生成审计报告

将生成的 .jsonl 日志文件转换为自验证的 HTML 报告，或直接启动报告服务器供客户查阅：

# 生成单个 HTML 报告
halo report audit.jsonl -o report.html

# 启动多租户报告服务器
halo serve ./records --port 8721

广泛的生态兼容性

halo-record 提供了灵活的接入方式，既能作为原生记录器嵌入新开发的应用，也能从现有遥测系统中摄取数据：

• 原生支持：MCP 拦截器、LangChain/LangGraph 回调、OpenAI Agents SDK、Claude Code/Agent SDK。
• 遥测摄取：兼容 OpenTelemetry GenAI 跨度、LiteLLM 回调、Langfuse 导出以及各类网关日志。
• 多语言适配：除了 Python 参考实现，还提供了 TypeScript 包，支持 Vercel AI SDK 及 JS 智能体生态。

适用场景

• 企业级 AI 应用：需要向客户证明数据处理合规性，满足 SOC 2、ISO 27001 等审计要求。
• 金融与医疗领域：对操作留痕有严格法律监管要求的行业，确保每一笔 AI 决策都有据可查。
• 开源智能体项目：通过提供透明的审计日志，增强社区对用户隐私保护的信任。