agent-behavior-reporting

把一次 Agent 会话的过程（用户消息 / 工具调用 / 模型与工具输出）结构化上报为 JSONL 事件， 沉淀成可分析的行为轨迹（telemetry / trajectory）。协议 agent.collection.v2 极简， 只有 4 类事件：trace（开场）/ turn（用户介入）/ tool.request（用工具）/ result（一次输出）。

• 纯 Python 标准库，零第三方依赖（Python 3.8+；EVM 签名 keccak/secp256k1/EIP-191 均自带实现）。
• 本地落库是权威（WAL），推送到后端是尽力而为，绝不阻塞 Agent、绝不改退出码。
• 默认脱敏：payload 中的疑似密钥 / 私钥 / token / --password 等命令行凭证自动打码。

安装

把整个 agent-behavior-reporting/ 目录放进对应 runtime 的 skills 目录：

Runtime	安装位置
Claude Code	skill 安装目录（由加载器给出）
Hermes	~/.hermes/skills/<分类>/agent-behavior-reporting/
Codex	~/.codex/skills/agent-behavior-reporting/

零配置即可用：事件默认写到 ~/.agent_report/（AGENT_REPORT_DIR 可覆盖），不推送任何后端。

三种接入方式

1. CLI（通用兜底）：在会话关键节点调用 scripts/report_event.py 发事件（用法见 SKILL.md）。
2. Hermes 插件（自动）：把 hermes_plugin/ 装为 Hermes 插件，按会话生命周期零提示自动上报。
3. Codex（自动）：codex_hook/ 下两版二选一——codex_notify.py（headless+交互，推荐）或 codex_hook.py（仅交互、含 per-tool 细节）。详见 codex_hook/README.md。

三者共用同一套 scripts/（校验 / 补齐 event_id·seq·ts / 脱敏 / 落库 / 推送）。

上传到后端（可选）

要把多个 agent 的事件汇总展示才需要。在存储目录写 config.json（0600），支持两种模式：

① ingest —— 自建后端，Bearer 令牌批量上传

python3 scripts/report_event.py register --backend http://<host>:8788 --name <agent名>
# 成功后写好 config.json，之后正常上报即自动带令牌推送

② direct —— 正式后端，EVM 签名单条直传（对齐 agent_marketplace，详见 references/agent-reports-api.md）

config.json 示例（私钥绝不写进 config，只放路径或用环境变量）：

{
  "backend": {
    "mode": "direct",
    "base_url": "https://<marketplace-backend>",
    "agent_address": "0x<合约地址>",
    "chain_id": 998,
    "executor_key_file": "/path/to/executor.key"
  }
}

• executor 私钥：放 executor_key_file（权限 0600）或环境变量 AGENT_REPORT_EXECUTOR_KEY（优先）。
• 签名由 scripts/evm_signer.py 读取文件/环境变量完成，调用方无需接触私钥明文。
• 临时关闭上传：环境变量 AGENT_REPORT_NO_UPLOAD=1。

目录

SKILL.md                  # 用法权威（何时发、怎么发、四类事件字段）
README.md                 # 本文件（安装 / 配置 / 接入）
scripts/                  # 运行时：report_event / event_store / uploader / redaction / evm_signer 等
references/               # 协议速查、reporting-playbook、direct-submit 接口文档
schema/envelope.schema.json
hermes_plugin/            # Hermes 自动上报插件
codex_hook/               # Codex 自动上报（notify / hook 两版）

协议速览

trace          开场：每个 trace 第一条，带 agent / channel / goal
turn           用户打字介入（text）
tool.request   用了哪个工具（tool_request_id / tool / input）
result         一次输出：模型回答(source=model) 或 工具结果(source=tool)

一段独立工作 = 一个会话 = 一个 trace_id；同一 trace_id 下事件按 seq 自增排成一条流。 长跑 / 定时 bot 用稳定 trace_id（如 bot_<jobid>）累积成一条连续 trace。

更多：SKILL.md、references/reporting-playbook.md、references/agent-reports-api.md。