agentlens-audit

AgentLens Audit

多 Agent 协作审计 CLI —— 成本治理 · 决策审计 · 证据链 · 影子智能体 · 决策权限合规

AgentLens Audit 让任何多 Agent 系统（Hermes / CrewAI / AutoGen / LangGraph）的协作过程可见、可审、可复盘。一条命令产出完整审计报告：谁拆的任务、为什么这么派、调了哪些工具、花了多少钱、出了事能否追责。

与观测工具（Langfuse / LangSmith / OpenTelemetry）定位不同：观测回答「发生了什么」，审计回答「该不该发生、谁负责、怎么改」。两者解决不同层次的问题，可以共存。

对齐中国网信办《智能体规范应用与创新发展实施意见》(2026-05) 的核心合规要求：行为可验证可追溯、影子智能体管控、决策权限分层。

👉 在线预览示例审计报告（内置样例数据生成，30 秒了解报告长什么样）

✨ 功能特性（七层审计）

🚀 快速开始

新手先看 docs/QUICKSTART.md —— 30 分钟从安装到完整审计报告。

pip install agentlens-audit

# 一键生成演示报告（内置样例数据）
agentlens-audit demo --output report.html

# 对任意事件流做完整审计（JSON 输出）
agentlens-audit audit --input events.jsonl --json

# 生成 HTML 审计报告
agentlens-audit audit --input events.jsonl --format html --output report.html

# 成本专项
agentlens-audit cost --input events.jsonl --json

# 两次审计对比（月度治理）
agentlens-audit diff --baseline last_month.jsonl --current this_month.jsonl

# CI 门禁：high 级违规数 > 0 即失败
agentlens-audit audit --input events.jsonl --gate --fail-on high

# 验报告完整性（防篡改哈希链）
agentlens-audit verify --report report.html

# 查询法规映射 / 修复建议
agentlens-audit regs --title approval
agentlens-audit remediations --title shadow

🔍 Watchdog — 持续审计 / 漂移监控

审计不是一次性行为。Watchdog 子命令用于定期复检，对比当前审计结果与基线，发现新问题漂移。

建立基线（首次）

agentlens-audit watchdog --input events.jsonl --write-baseline baseline.json

对比报警

agentlens-audit watchdog --input events.jsonl --baseline baseline.json

漂移趋势历史（可选）

# 每次对比后追加一条当日记录（high 总数 / 新增 / 增长 / 成本），供 Web 趋势图使用
agentlens-audit watchdog --input events.jsonl --baseline baseline.json --history drift-history.json

退出码语义

cron 调度示例

# 每 24 小时跑一次，输出到日志
0 0 * * * /usr/local/bin/agentlens-audit watchdog --input /data/events.jsonl --baseline /data/baseline.json >> /var/log/agentlens-watchdog.log 2>&1

📥 支持的输入

• Hermes：gateway.log 直接解析（协作/流程审计）；agent.log 直接解析（成本/调用明细，兼容新旧日志格式）
• CrewAI / AutoGen / LangGraph：日志/追踪 → 统一事件流（见 converters/）
• 统一事件流 JSONL：{type, timestamp, source, payload, evidence_ref, event_id}

📤 输出

• --json：结构化审计结果（七层）
• --format html：自包含 HTML 报告（无外链资源，可离线打开、可归档；SHA-256 哈希链防篡改）
• diff：基线对比 JSON/HTML
• verify：报告完整性验真（篡改 → exit 1）
• regs：法规映射查询（--unknown 聚合未映射 / --annotate 人工标注 / --annotations 列出）
• remediations：修复建议查询
• budget：成本预算告警（超阈值走 notify 通道）
• --gate：CI 退出码

🌐 Web 服务

内置 FastAPI Web 平台：仪表盘 KPI + 趋势图、报告列表/详情/对比、触发审计、修复跟踪（标记已修复 + 回归验证）、合规标注、预算告警历史、Watchdog 漂移趋势图。

pip install agentlens-audit[web]

# 启动（默认 127.0.0.1:8000；生产建议加 Basic Auth 环境变量）
agentlens-audit serve --host 0.0.0.0 --port 8010

• 认证：设置 AGENTLENS_WEB_USERNAME / AGENTLENS_WEB_PASSWORD 环境变量后启用 Basic Auth；未设置则放行（仅限内网）
• 报告目录：AGENTLENS_REPORT_DIR 环境变量覆盖（默认 ~/.hermes/agentlens-reports）
• 关键 API：/api/reports / /api/audit/run / /api/findings/* / /api/watchdog(+/history) / /api/budget/alerts / /api/annotations

🧪 测试

python -m pytest tests/ -v   # 325 用例全绿

📦 发布

• PyPI: https://pypi.org/project/agentlens-audit/
• GitHub: https://github.com/waiky-github/agentlens-cli
• License: MIT

🔌 MCP Server

AgentLens Audit 支持作为 MCP server 运行，任何 MCP 客户端（Claude / Cursor / Hermes）均可接入。

安装

pip install agentlens-audit[mcp]

客户端配置

stdio 模式（推荐）：

{
  "mcpServers": {
    "agentlens-audit": {
      "command": "python",
      "args": ["-m", "agentlens_cli.mcp_server"]
    }
  }
}

HTTP 模式：

{
  "mcpServers": {
    "agentlens-audit": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

启动 HTTP 服务端：

python -m agentlens_cli.mcp_server --transport http --port 8765 --host 127.0.0.1

可用工具

---

📮 关注我们

公众号：AI Aperture —— 分享 AI 工程实践、多 Agent 系统与开源项目经验。

扫码关注，获取项目更新与更多技术内容。