Halo Record 代理审计轨迹

这个 Agent 能做什么，适合哪些场景？

Halo Record 是一个零运行时依赖的 Python 参考实现，用哈希链记录 AI 代理的工具调用、模型调用、数据访问、审批及运行边界。它提供 Recorder、trace、record_call、框架适配器、验证器、见证客户端、报告服务器和 CLI，并可接入 MCP、LangChain/LangGraph、OpenAI Agents SDK、Claude Agent SDK、OpenTelemetry GenAI、LiteLLM、Langfuse及网关日志。记录以追加式 JSONL 链保存在本地文件系统，可渲染成在浏览器内重新校验的 Runtime Report，也可导出 CSV 与绑定源链头的清单。外部见证检查点可发现已提交历史被重写或预期检查点缺失，RFC 3161 时间戳还能证明某个链头不晚于特定时间存在。它是证据层而非认证或执行网关：哈希不能证明每个动作都被捕获，验证状态也只是集成代码所报告的结果。核心功能可在本地运行；网络仅用于主动调用的远程见证、读取检查点或时间戳服务。

应用在动作边界调用 Recorder、trace()、record_call() 或框架适配器，将调用输入的规范哈希、经过尽力脱敏且最多 200 字符的摘要、结果、主体、来源、父记录以及可选的 verification 和 authority 块封入记录。每条记录使用 RFC 8785 规范化后计算 SHA-256，并通过 integrity.prev_hash 连接前一条记录；halo verify 会重新计算哈希并检查格式和链接。halo report 生成自校验 HTML，halo serve 按客户提供受控报告，halo export 输出日期范围内的 CSV 和清单，halo policy 对声明式策略包给出通过、违规或证据缺口。halo anchor 将链头、链根、记录数和主体 ID 提交给本地或远程见证，并可附加 RFC 3161 时间戳；记录正文不会随见证请求发出。现有系统还可通过 MCP 客户端拦截、LangChain 回调、OpenTelemetry GenAI spans、LiteLLM 回调、Langfuse 导出、网关日志以及 Claude Code 或 Codex 的 PostToolUse 事件写入同一记录格式。

1. 向客户安全团队交付 AI 代理处理其数据的可校验 Runtime Report，而不是仅提供文字说明的软件供应商。
2. 需要为 SOC 2、AIUC-1、AICM、ISO 42001、EU AI Act 或 NIST AI RMF 评审准备日志证据和日期范围导出的合规团队。
3. 运行 LangChain、LangGraph、MCP 或 OpenTelemetry GenAI 工作负载，并希望把不同来源的动作统一封入一条链的平台团队。
4. 希望记录 Claude Code 或 Codex 文件修改、Shell 命令和 MCP 调用，又不想修改代理代码的工程团队。
5. 需要由客户或其他外部方持有周期性检查点，以发现已提交历史被改写或检查点中断的高信任场景。
6. 需要把特定工具调用范围导出成 CSV 和校验清单，再上传至 Vanta、Drata 等 GRC 平台的审计团队。

如何安装或部署这个 Agent？

本地演示不需要代理、账户或 API 凭据。使用 uv 可直接运行：

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

也可以通过 pip 安装后启动：

pip install halo-record
halo demo --serve

演示会创建虚构供应商及两个客户的记录，使用本地见证文件建立检查点，启动 Runtime Report 服务并打开操作台。Apache-2.0 包本身可免费使用；只有主动选择远程见证或 RFC 3161 时间戳时才需要网络。

如何使用这个 Agent？

在自己的 Python 代理入口记录运行边界：

from halo_record import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")

要捕获具体工具调用，需要在每个工具边界增加 record_call() 或使用适配器：

from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:
    call.result = payments.refund(120)

随后验证并生成报告：

halo verify audit.jsonl
halo report audit.jsonl -o report.html

如需浏览一个目录内按客户隔离的报告，可运行：

halo serve ./records --port 8721

Claude Code 可将以下内容加入 ~/.claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

Codex 可将以下内容加入 ~/.codex/hooks.json：

{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

两种钩子默认写入 ~/.halo/audit.jsonl，可用 HALO_LOG 改写路径；HALO_HASH_ONLY=1 可关闭摘要。若要承诺已提交历史，可建立并检查见证点：

halo anchor audit.jsonl witness.jsonl
halo anchor audit.jsonl witness.jsonl --check

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题