AgentLens

🔍 AgentLens

面向 AI Agent 的开源可观测性工具 — 提供防篡改审计记录
_{每个事件均通过 SHA-256 哈希链关联，并可进行加密验证 — 专为满足《欧盟 AI 法案》第 12 条的记录保存要求而构建}

📖 文档 · 快速开始 · 控制面板 · ☁️ 云服务

---

📑 目录

• 从设计上防止篡改
• 快速开始
• 架构
• 集成指南
• 主要功能
• 控制面板
• AgentLens 云服务
• 软件包
• API 概览
• 命令行界面
• 开发
• 参与贡献
• AgentKit 生态系统
• 许可证

---

AgentLens 是 AI Agent 的飞行记录仪。它会捕获每次大模型调用、工具调用、审批决定和错误，然后通过可查询的 API 和实时 Web 控制面板呈现这些信息。

🔒 设计上防篡改

AgentLens 与其他可观测性工具的不同之处在于：每个事件都会通过 SHA-256 哈希链与前一个事件相连，就像 git 提交和区块链的链接方式一样。审计日志采用仅追加写入，并且可通过密码学验证——事后修改、删除或重新排列任何一条记录都会导致验证失败，并指出具体出错的事件。它专为满足 《欧盟 AI 法案》第 12 条的记录保存义务，以及新兴的 IETF Agent 审计轨迹工作而打造。

30 秒亲自验证（需要 Docker）：

git clone https://github.com/agentkitai/agentlens && cd agentlens
./demo/aha.sh

1/5  Starting AgentLens (SQLite, zero-config)…   ✓ up at http://localhost:3400
2/5  Ingesting a 5-event agent trace…            ✓ 5 events ingested
3/5  Verifying the hash chain…                    ✓ CHAIN VALID — no tampering detected
4/5  Tampering with one event in the database…   ✓ altered llm_call (changed the logged model)
5/5  Re-verifying the hash chain…                 ✗ CHAIN BROKEN — tampering detected ✅

演示会摄取一条真实追踪记录，验证哈希链（通过），然后绕过审计日志直接编辑数据库中的一条记录，再次验证（失败）。审计员可通过 GET /api/audit/verify/export 获取带签名且可验证的 JSON 快照。

五种集成方式——选择适合你技术栈的方式：

集成方式	语言	工作量	捕获内容
🔭 OpenTelemetry	任意	配置 OTLP 导出器即可	任何使用 gen_ai.* 埋点的 Agent——无需 AgentLens SDK
🤖 OpenClaw 插件	OpenClaw	复制并启用	每次 Anthropic 调用——提示词、令牌、成本、工具——零代码
🐍 Python 自动埋点	Python	1 行代码	每次 OpenAI / Anthropic / LangChain 调用——确定性捕获
🔌 MCP 服务	任意（MCP）	配置块	来自 Claude Desktop / Cursor 的工具调用、会话和事件
📦 SDK	Python、TypeScript	编写代码	完全掌控——记录事件、查询分析数据、构建集成

🚀 快速开始

一条命令——使用 SQLite 启动服务和仪表板，零配置：

docker run -p 3400:3400 -e AUTH_DISABLED=true -e JWT_SECRET=dev-secret ghcr.io/agentkitai/agentlens
# Open http://localhost:3400

或不使用 Docker：

npx @agentkitai/agentlens-server
# http://localhost:3400 with SQLite — zero config

AUTH_DISABLED=true 适用于快速本地试用（加固版镜像仍要求设置 JWT_SECRET）。如需供多人使用，请移除 AUTH_DISABLED，设置真实的 JWT_SECRET，并创建 API 密钥（见下文）。

完整技术栈（Postgres + Redis、身份验证、TLS）——从源代码运行：

git clone https://github.com/agentkitai/agentlens && cd agentlens
cp .env.example .env
docker compose up
# production overlay (auth, restart policies):
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

创建 API 密钥

curl -X POST http://localhost:3400/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

保存响应中的 als_... 密钥——它只会显示一次。然后前往集成指南，为你的 Agent 添加埋点。

📖 完整设置指南 →

🏗️ 架构

graph TB
    subgraph Agents["Your AI Agents"]
        PY["Python App<br/>(OpenAI, Anthropic, LangChain)"]
        MCP_C["MCP Client<br/>(Claude Desktop, Cursor)"]
        TS["TypeScript App"]
        OC["OpenClaw Plugin"]
    end

    PY -->|"agentlensai.init()<br/>auto-instrumentation"| SERVER
    MCP_C -->|MCP Protocol| MCP_S["@agentkitai/agentlens-mcp"]
    MCP_S -->|HTTP| SERVER
    TS -->|"@agentkitai/agentlens-sdk"| SERVER
    OC -->|HTTP| SERVER

    subgraph Server["@agentkitai/agentlens-server"]
        direction TB
        INGEST[Ingest Engine]
        QUERY[Query Engine]
        ALERT[Alert Engine]
        LLM_A[LLM Analytics]
        HEALTH[Health Scoring]
        COST[Cost Optimizer]
        REPLAY[Session Replay]
        BENCH[Benchmark Engine]
        GUARD[Guardrails]
    end

    SERVER --> DB[(SQLite / Postgres)]
    SERVER --> DASH["Dashboard<br/>(React SPA)"]

    EXT["AgentGate / FormBridge"] -->|Webhook| SERVER

🔧 集成指南

🔭 OpenTelemetry（任意 GenAI Agent——无需 SDK）

如果你的 Agent 已通过 OpenLLMetry、OpenInference 或官方 OTel 埋点，使用 OpenTelemetry GenAI 语义约定 添加埋点，只需将其 OTLP 导出器指向 AgentLens。无需 AgentLens SDK。

# Send standard OTLP/HTTP to AgentLens (JSON or protobuf, /v1/traces)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3400
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:3400/v1/traces

AgentLens 会将 gen_ai.* 跨度映射到自身的数据模型，并写入防篡改审计日志：

OTel GenAI 跨度（gen_ai.operation.name）	转换为
chat / text_completion / generate_content	一对 llm_call + llm_response（模型、提供方、消息、usage.input_tokens/output_tokens、结束原因、延迟、成本）
execute_tool	tool_call（gen_ai.tool.name、gen_ai.tool.call.id、参数）
embeddings	包含令牌用量的嵌入事件
invoke_agent / create_agent	Agent 调用事件

每条 OTel 追踪记录都会映射到一个会话（如果存在 gen_ai.conversation.id，则使用该值），且每个事件都会像其他事件一样加入哈希链——因此，来自任何 GenAI 框架的追踪记录都能获得同样可验证的审计轨迹。在生产环境中，可设置 OTLP_AUTH_TOKEN，要求 OTLP 端点使用 bearer 令牌进行身份验证。

无需 SDK 也能计算成本： OTel GenAI 埋点会报告令牌用量，但很少报告成本。AgentLens 会根据模型每 100 万个令牌的定价（对模型 ID 进行模糊匹配）重建 costUsd，因此，仅使用 OTel 的 Agent 也能获得与使用 SDK 埋点的 Agent 相同的成本分析——无需为每次调用添加成本属性。

🤖 OpenClaw 插件

如果你正在运行 OpenClaw，AgentLens 插件会自动捕获每一次 Anthropic API 调用 —— 提示词、补全、token 用量、成本、延迟和工具调用。

cp -r packages/relay-plugin /usr/lib/node_modules/openclaw/extensions/agentlens-relay
openclaw config patch '{"plugins":{"entries":{"agentlens-relay":{"enabled":true}}}}'
openclaw gateway restart

如果你的 AgentLens 实例不在 localhost:3400 上，请设置 AGENTLENS_URL。详情请参阅插件 README。

🐍 Python 自动埋点

一行代码 —— 自动捕获跨 9 个提供商（OpenAI、Anthropic、LiteLLM、AWS Bedrock、Google Vertex AI、Google Gemini、Mistral AI、Cohere、Ollama）的每一次大模型调用：

pip install agentlensai[all-providers]

import agentlensai

agentlensai.init(
    url="http://localhost:3400",
    api_key="als_your_key",
    agent_id="my-agent",
)
# Every LLM call is now captured automatically

关键保证： ✅ 确定性 · ✅ 故障安全 · ✅ 非阻塞 · ✅ 隐私保护（init(redact=True)）

📖 Python SDK 完整文档 →

🔌 MCP 集成

适用于 Claude Desktop、Cursor 或任何 MCP 客户端 —— 添加到你的配置中：

{
  "mcpServers": {
    "agentlens": {
      "command": "npx",
      "args": ["@agentkitai/agentlens-mcp"],
      "env": {
        "AGENTLENS_API_URL": "http://localhost:3400",
        "AGENTLENS_API_KEY": "als_your_key_here"
      }
    }
  }
}

AgentLens 提供 22 个 MCP 工具 —— 涵盖核心可观测性、智能与分析，以及运维。完整 MCP 工具参考 →

📖 MCP 设置指南 →

📦 编程式 SDK

Python：

pip install agentlensai

from agentlensai import AgentLensClient
client = AgentLensClient("http://localhost:3400", api_key="als_your_key")
sessions = client.get_sessions()
analytics = client.get_llm_analytics()

TypeScript：

npm install @agentkitai/agentlens-sdk

import { AgentLensClient } from '@agentkitai/agentlens-sdk';
const client = new AgentLensClient({ baseUrl: 'http://localhost:3400', apiKey: 'als_your_key' });
const sessions = await client.getSessions();

📖 SDK 参考 →

✨ 核心特性

• 🐍 Python 自动埋点 —— agentlensai.init() 自动捕获跨 9 个提供商的每一次大模型调用。确定性 —— 不依赖大模型行为。
• 🔌 MCP 原生 —— 以 MCP 服务形式提供。适用于 Claude Desktop、Cursor 以及任何 MCP 客户端。
• 🔭 OpenTelemetry GenAI —— 从任何经过 OTel 埋点的 Agent（OpenLLMetry、OpenInference、官方 OTel）摄取 gen_ai.* OTLP 追踪 —— 无需 AgentLens SDK。
• 🧠 大模型调用追踪 —— 完整的提示词/补全可见性、token 用量、成本聚合、延迟测量和隐私脱敏。
• 📊 实时仪表盘 —— 会话时间线、事件浏览器、大模型分析、成本追踪和告警。
• 🔒 防篡改审计追踪 —— 仅追加的事件存储，每个会话配备 SHA-256 哈希链。
• 💰 成本追踪 —— 按会话、按 Agent、按模型追踪 token 用量和预估成本。在成本激增时告警。
• 🚨 告警 —— 可配置的规则，涵盖错误率、成本阈值、延迟异常和不活跃状态。
• ❤️‍🩹 健康评分 —— 5 个维度的健康评分，带有趋势追踪。
• 💡 成本优化 —— 感知复杂度的模型推荐引擎，附带预期节省。
• 📼 会话回放 —— 逐步回放任何过往会话，完整重建上下文。
• ⚖️ A/B 基准测试 —— 使用 Welch t 检验和卡方分析对 Agent 变体进行统计比较。
• 🛡️ 护栏 —— 自动化安全规则，带干跑模式以便安全测试。
• 🔌 框架插件 —— LangChain、CrewAI、AutoGen、Semantic Kernel —— 自动检测、故障安全、非阻塞。
• 🔗 AgentKit 生态系统 —— 与 AgentGate、FormBridge、Lore 和 AgentEval 集成。
• 🔒 租户隔离 —— 多租户支持，按租户进行数据范围限定和 API 密钥绑定。
• 🏠 可自托管 —— 默认使用 SQLite，无外部依赖。MIT 许可。

📸 仪表盘

AgentLens 附带一个实时 Web 仪表盘，用于监控你的 Agent。

📸 仪表盘截图（点击展开）

概览 —— 一目了然的指标

概览页面展示实时指标 —— 会话、事件、错误和活跃 Agent —— 配有 24 小时事件时间线图表、带状态徽章的最近会话，以及最近错误信息流。

会话 —— 追踪每一次 Agent 运行

每个 Agent 会话都有可排序列：Agent 名称、状态、开始时间、时长、事件数、错误数和总成本。

会话详情 — 时间线与哈希链

完整的事件时间线，支持防篡改哈希链验证。可按事件类型筛选，并查看成本明细。

事件浏览器 — 搜索与筛选所有内容

可搜索、可筛选的视图，展示所有会话中的每个事件。

🧠 大模型分析 — 提示词与成本跟踪

查看所有 Agent 的大模型调用总数、成本、延迟和令牌用量，并进行模型比较。

🧠 会话时间线 — 大模型调用配对

在会话时间线中查看大模型调用，以及模型、令牌、成本和延迟信息。

💬 提示词详情 — 聊天气泡查看器

以聊天气泡样式的查看器展示完整提示词和补全内容，并附带元数据面板。

❤️‍🩹 健康概览 — Agent 可靠性

为每个 Agent 提供 5 维健康评分，并跟踪趋势。

💡 成本优化 — 模型推荐

分析大模型调用模式，根据置信度等级推荐成本更低的替代模型。

📼 会话回放 — 逐步调试器

逐个查看任意历史会话中的事件，并完整重建上下文。

⚖️ 基准测试 — Agent A/B 测试

创建和管理 A/B 实验，并进行统计显著性检验。

🛡️ 防护规则 — 自动化安全规则

创建和管理自动化安全规则，并查看触发历史和活动动态。

☁️ AgentLens Cloud

不想自行托管？AgentLens Cloud 是一项全托管 SaaS 服务，使用相同的 SDK，无需管理基础设施：

import agentlensai
agentlensai.init(cloud=True, api_key="als_cloud_your_key_here", agent_id="my-agent")

• 相同的 SDK，只需更改一个参数 — 将 url= 切换为 cloud=True
• 托管式 Postgres — 支持多租户，并提供行级安全
• 团队功能 — 组织、RBAC、审计日志
• 无需运行服务端 — 可通过 app.agentlens.ai 使用仪表板

📖 Cloud 设置指南 · 迁移指南 · 故障排除

📦 软件包

Python（PyPI）

软件包	描述	PyPI
agentlensai	Python SDK + 面向 9 个大模型提供商的自动插桩

TypeScript / Node.js（npm）

软件包	描述	npm
@agentkitai/agentlens-server	Hono API 服务端 + 仪表板服务
@agentkitai/agentlens-mcp	用于 Agent 插桩的 MCP 服务
@agentkitai/agentlens-sdk	用于编程的 TypeScript 客户端
@agentkitai/agentlens-core	共享类型、架构、哈希链工具
@agentkitai/agentlens-cli	命令行界面
@agentkitai/agentlens-dashboard	React Web 仪表板（与服务端捆绑）	private

🔌 API 概览

端点	描述
POST /api/events	接收事件（批量）
GET /api/events	使用筛选条件查询事件
GET /api/sessions	列出会话
GET /api/sessions/:id/timeline	会话时间线及哈希链验证
GET /api/analytics	按时间分桶的指标

完整 API 参考 →

⌨️ CLI

npx @agentkitai/agentlens-cli health                          # Overview of all agents
npx @agentkitai/agentlens-cli health --agent my-agent          # Detailed health with dimensions
npx @agentkitai/agentlens-cli optimize                          # Cost optimization recommendations

两个命令都支持 --format json，以输出机器可读的结果。查看 agentlens health --help 了解所有选项。

🛠️ 开发

git clone https://github.com/agentkitai/agentlens.git
cd agentlens
pnpm install

pnpm typecheck && pnpm test && pnpm lint  # Run all checks
pnpm dev                                   # Start dev server

要求： Node.js ≥ 20.0.0 · pnpm ≥ 10.0.0

🤝 贡献

欢迎贡献！有关设置说明、编码规范和 PR 流程，请参阅 CONTRIBUTING.md。

🧰 AgentKit 生态系统

项目	描述
AgentLens	AI Agent 的可观测性与防篡改审计追踪	⬅️ 你在这里
AgentGate	人在环路的审批网关 + 响应式防护措施
Lore	跨 Agent 记忆与经验分享
AgentEval	测试与评估框架
FormBridge	Agent 与人类混合模式表单

📄 许可证

MIT © Amit Paz