agentkitai/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
---
📑 Table of Contents
- Tamper-Evident by Design
- Quick Start
- Architecture
- Integration Guides
- Key Features
- Dashboard
- AgentLens Cloud
- Packages
- API Overview
- CLI
- Development
- Contributing
- AgentKit Ecosystem
- License
---
AgentLens is a **flight recorder for AI agents**. It captures every LLM call, tool invocation, approval decision, and error — then presents it through a queryable API and real-time web dashboard.
🔒 Tamper-evident by design
What sets AgentLens apart from other observability tools: every event is **SHA-256 hash-chained** to the one before it, the same way git commits and blockchains are linked. The audit log is **append-only and cryptographically verifiable** — alter, delete, or reorder a single record after the fact and verification fails, pointing at the exact event that broke. Purpose-built for the record-keeping obligations of **EU AI Act Article 12** and the emerging **IETF Agent Audit Trail** work.
**See it for yourself in 30 seconds** (needs Docker):
The demo ingests a real trace, verifies the chain (passes), edits one record directly in the database behind the audit log's back, then re-verifies (fails). Auditors get a signed, verifiable JSON snapshot from GET /api/audit/verify/export.
**Five ways to integrate — pick what fits your stack:**
| Integration | Language | Effort | Capture |
|---|---|---|---|
| 🔭 **OpenTelemetry** | Any | **Point your OTLP exporter** | Any gen_ai.*-instrumented agent — **no AgentLens SDK** |
| 🤖 **OpenClaw Plugin** | OpenClaw | **Copy & enable** | Every Anthropic call — prompts, tokens, cost, tools — zero code |
| 🐍 **Python Auto-Instrumentation** | Python | **1 line** | Every OpenAI / Anthropic / LangChain call — deterministic |
| 🔌 **MCP Server** | Any (MCP) | Config block | Tool calls, sessions, events from Claude Desktop / Cursor |
| 📦 **SDK** | Python, TypeScript | Code | Full control — log events, query analytics, build integrations |
🚀 Quick Start
**One command** — server + dashboard on SQLite, zero config:
Or without Docker:
> AUTH_DISABLED=true is for a quick local trial (JWT_SECRET is still required by the hardened image). For anything shared, drop AUTH_DISABLED, set a real JWT_SECRET, and create an API key (below).
**Full stack** (Postgres + Redis, auth, TLS) — runs from source:
Create an API Key
Save the als_... key from the response — it's shown only once. Then head to the Integration Guides to instrument your agent.
📖 Full setup guide →
🏗️ Architecture
🔧 Integration Guides
🔭 OpenTelemetry (any GenAI agent — no SDK)
If your agent is already instrumented with the **OpenTelemetry GenAI semantic conventions** — via OpenLLMetry, OpenInference, or the official OTel instrumentations — just point its OTLP exporter at AgentLens. **No AgentLens SDK required.**
AgentLens maps gen_ai.* spans into its model and into the tamper-evident audit log:
| OTel GenAI span (gen_ai.operation.name) | Becomes |
|---|---|
| chat / text_completion / generate_content | a paired llm_call + llm_response (model, provider, messages, usage.input_tokens/output_tokens, finish reason, latency, **cost**) |
| execute_tool | tool_call (gen_ai.tool.name, gen_ai.tool.call.id, arguments) |
| embeddings | embedding event with token usage |
| invoke_agent / create_agent | agent-invocation event |
Each OTel **trace** maps to a session (or gen_ai.conversation.id if present), and every event is hash-chained like any other — so traces from any GenAI framework get the same verifiable audit trail. Set OTLP_AUTH_TOKEN to require a bearer token on the OTLP endpoints in production.