使用说明

🔍 AgentLens

Open-source observability for AI agents — with a tamper-evident audit trail
_{Every event SHA-256 hash-chained & cryptographically verifiable — built for EU AI Act Article 12 record-keeping}

📖 Documentation · Quick Start · Dashboard · ☁️ Cloud

📑 目录

设计明显的篡改
快速开始
建筑
集成指南
主要特点
仪表盘
AgentLens云
包裹
API概述
命令行界面
发展
贡献
AgentKit 生态系统
许可证

AgentLens是一个 人工智能代理飞行记录仪.它捕获每个LLM调用、工具调用、批准决定和错误，然后通过可查询的API和实时web仪表板进行呈现。

🔒 设计明显存在篡改

AgentLens与其他可观察性工具的区别在于：每个事件都是 SHA-256哈希链 对于之前的版本，与git提交和区块链链接的方式相同。审核日志为 仅附加且可加密验证 --在事实和验证失败后，更改、删除或重新排序单个记录，并指出发生故障的确切事件。专为以下人员的记录保存义务而设计 欧盟人工智能法案第12条 以及新兴 IETF代理审计跟踪 工作。

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 ✅

该演示接收真实的跟踪，验证链（通过），直接在审计日志后面的数据库中编辑一条记录，然后重新验证（失败）。审计员从以下位置获取签名的、可验证的JSON快照 GET /api/audit/verify/export.

五种集成方式——选择适合您堆栈的方式：

整合	语言	努力	捕捉
🔭 开放遥测	任何	指向您的OTLP导出器	任何 `gen_ai.`-仪器化试剂-- 无AgentLens SDK*
🤖 OpenClaw插件	龙虾	复制并启用	每个Anthropic调用——提示、令牌、成本、工具——零代码
🐍 Python自动检测 python 1条线	每个OpenAI/Anthropic/LangChain调用——确定性
🔌 MCP服务器	任何（MCP）	配置块	来自Claude Desktop/Cursor的工具调用、会话、事件
📦 软件开发工具包	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、auth、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_... 响应中的键——它只显示一次。然后前往集成指南为你的代理人提供工具。

📖 完整设置指南→

🏗️ 建筑

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

🔧 集成指南

🔭 OpenTetry（任何GenAI代理——无SDK）

如果您的代理已经安装了 OpenTetry GenAI语义约定 --通过OpenLLMetric、OpenInference或官方OTel工具，只需将其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.* 跨越到其模型和防篡改审计日志中：

吉奈斯潘酒店(`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`	代理调用事件

每个OTel 痕迹映射到会话（或 gen_ai.conversation.id 如果存在），并且每个事件都像其他事件一样是哈希链的——因此来自任何GenAI框架的跟踪都会得到相同的可验证审计跟踪。集 OTLP_AUTH_TOKEN 要求在生产中的OTLP端点上使用承载令牌。

无SDK的成本： OTel GenAI仪器报告代币，但很少成本。AgentLens重建 costUsd 根据模型的每1M令牌定价（模型id上的模糊匹配），因此仅OTel代理可以获得与SDK仪器化代理相同的成本分析——不需要每次呼叫成本属性。

🤖 OpenClaw插件

如果你在跑步龙虾，AgentLens插件自动捕获每个Anthropic API调用-提示、完成、令牌使用、成本、延迟和工具调用。

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_URL 如果您的AgentLens实例未打开 localhost:3400。请参阅插件README 了解详情。

🐍 Python自动检测

一条线——每个LLM呼叫都会自动捕获 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个提供商之间的每个LLM呼叫。确定性——不依赖LLM行为。
🔌 MCP本地 --作为MCP服务器发货。适用于Claude Desktop、Cursor和任何MCP客户端。
🔭 开放遥测GenAI --摄入 gen_ai.* 来自任何OTel仪器化代理（OpenLLMetric、OpenInference、官方OTel）的OTLP跟踪——不需要AgentLens SDK。
🧠 LLM呼叫跟踪 --完整的提示/完成可见性、令牌使用、成本聚合、延迟测量和隐私编校。
📊 实时仪表板 --会话时间表、事件浏览器、LLM分析、成本跟踪和警报。
🔒 篡改证据审计追踪 --每个会话仅附加SHA-256哈希链的事件存储。
💰 成本跟踪 --跟踪令牌使用情况和每个会话、每个代理、每个模型的估计成本。警惕成本飙升。
🚨 告警 --错误率、成本阈值、延迟异常和不活动的可配置规则。
❤️‍🩹 健康评分 --采用趋势跟踪的5维健康评分。
💡 成本优化 --具有复杂性感知的模型推荐引擎，预计可节省成本。
📼 会话重放 --通过完整的上下文重建来逐步完成过去的任何会话。
⚖️ A/B基准测试 --使用Welch t检验和卡方分析对代理变体进行统计比较。
🛡️ 护栏 --自动安全规则，采用干运行模式进行安全测试。
🔌 框架插件 --LangChain、CrewAI、AutoGen、语义内核——自动检测、故障安全、非阻塞。
🔗 AgentKit 生态系统 --与集成代理门, 模板桥, 传说，以及代理.
🔒 租户隔离 -多对端支持，每个对端数据范围和API密钥绑定。
🏠 自托管 --默认情况下为SQLite，没有外部依赖关系。麻省理工学院许可。

📸 仪表盘

AgentLens附带了一个实时web仪表板，用于监控您的代理。

📸 Dashboard Screenshots (click to expand)

概述——概览指标

概述页面显示 实时指标 --会话、事件、错误和活动代理——带有24小时事件时间线图、带有状态徽章的最近会话和最近错误提要。

会话-跟踪每个代理运行

每个代理会话都有可排序的列：代理名称、状态、开始时间、持续时间、事件计数、错误计数和总成本。

会话详细信息——时间线和哈希链

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

事件资源管理器--搜索和筛选所有内容

所有会话中每个事件的可搜索、可过滤视图。

🧠 LLM分析——提示和成本跟踪

通过模型比较，所有代理的LLM调用总数、成本、延迟和令牌使用情况。

🧠 会话时间线——LLM呼叫配对

LLM在会话时间线中调用模型、令牌、成本和延迟。

💬 提示细节--聊天气泡查看器

带有元数据面板的聊天气泡式查看器中的完整提示和完成。

❤️‍🩹 健康概述——代理可靠性

每个代理的5维健康评分具有趋势跟踪功能。

💡 成本优化——模型建议

分析LLM调用模式，并推荐具有置信水平的更便宜的模型替代方案。

📼 会话回放--逐步调试调试器

通过完整的上下文重建，逐一处理过去的会话事件。

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

通过统计显著性检验创建和管理A/B实验。

🛡️ 护栏——自动安全规则

使用触发历史和活动提要创建和管理自动化安全规则。

☁️ AgentLens云

不想自己主持？ AgentLens云 是一个完全托管的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.agentens.ai

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

📦 包裹

Python（PyPI）

包	描述	PyPI
`agentlensai`	9个LLM提供者的Python SDK+自动检测

Types/Node.js（npm）

包	描述	npm
`@agentkitai/agentlens-server`	Hono API服务器+仪表板服务
`@agentkitai/agentlens-mcp`	用于代理检测的MCP服务器
`@agentkitai/agentlens-sdk`	程序化TypeScript客户端
`@agentkitai/agentlens-core`	共享类型、模式、哈希链实用程序
`@agentkitai/agentlens-cli`	命令行界面
`@agentkitai/agentlens-dashboard`	React web仪表板（与服务器捆绑）	私有

🔌 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

🤝 贡献

我们欢迎捐款！看 贡献.md 用于设置说明、编码标准和PR过程。

🧰 AgentKit 生态系统

项目	描述
Agent Lens	AI代理的可观察性和防篡改审计跟踪	⬅️ 你来了
代理门	人在环审批网关+反应式护栏
传说	跨代理记忆和课程共享
代理	测试与评估框架
模板桥	代理-人类混合模式形式

AI代理可观测性工具

使用说明

🔍 AgentLens

📑 目录

🔒 设计明显存在篡改

🚀 快速开始

创建API密钥

🏗️ 建筑

🔧 集成指南

🔭 OpenTetry（任何GenAI代理——无SDK）

🤖 OpenClaw插件

🐍 Python自动检测

🔌 MCP集成

📦 程序化SDK

✨ 主要特点

📸 仪表盘

概述——概览指标

会话-跟踪每个代理运行

会话详细信息——时间线和哈希链

事件资源管理器--搜索和筛选所有内容

🧠 LLM分析——提示和成本跟踪

🧠 会话时间线——LLM呼叫配对

💬 提示细节--聊天气泡查看器

❤️‍🩹 健康概述——代理可靠性

💡 成本优化——模型建议

📼 会话回放--逐步调试调试器

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

🛡️ 护栏——自动安全规则

☁️ AgentLens云

📦 包裹

Python（PyPI）

Types/Node.js（npm）

🔌 API概述

⌨️ CLI

🛠️ 发展

🤝 贡献

🧰 AgentKit 生态系统

📄 许可证

使用说明

🔍 AgentLens

📑 目录

🔒 设计明显存在篡改

🚀 快速开始

创建API密钥

🏗️ 建筑

🔧 集成指南

🔭 OpenTetry（任何GenAI代理——无SDK）

🤖 OpenClaw插件

🐍 Python自动检测

🔌 MCP集成

📦 程序化SDK

✨ 主要特点

📸 仪表盘

概述——概览指标

会话-跟踪每个代理运行

会话详细信息——时间线和哈希链

事件资源管理器--搜索和筛选所有内容

🧠 LLM分析——提示和成本跟踪

🧠 会话时间线——LLM呼叫配对

💬 提示细节--聊天气泡查看器

❤️‍🩹 健康概述——代理可靠性

💡 成本优化——模型建议

📼 会话回放--逐步调试调试器

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

🛡️ 护栏——自动安全规则

☁️ AgentLens云

📦 包裹

Python（PyPI）

Types/Node.js（npm）

🔌 API概述

⌨️ CLI

🛠️ 发展

🤝 贡献

🧰 AgentKit 生态 系统

📄 许可证

相关 MCP

Kubernetes集群管理MCP服务

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Prometheus MCP 服务器

Kubernetes MCP 服务器

🧰 AgentKit 生态系统