{
  "markdown": "<p align=\"center\">\n  <h1 align=\"center\">🔍 AgentLens</h1>\n  <p align=\"center\">\n    <strong>Open-source observability for AI agents — with a tamper-evident audit trail</strong>\n    <br/>\n    <sub>Every event SHA-256 hash-chained &amp; cryptographically verifiable — built for EU AI Act Article 12 record-keeping</sub>\n  </p>\n  <p align=\"center\">\n    <a href=\"https://pypi.org/project/agentlensai/\"><img src=\"https://img.shields.io/pypi/v/agentlensai?label=pypi\" alt=\"PyPI\"></a>\n    <a href=\"https://www.npmjs.com/package/@agentkitai/agentlens-server\"><img src=\"https://img.shields.io/npm/v/@agentkitai/agentlens-server?label=npm\" alt=\"npm server\"></a>\n    <a href=\"https://www.npmjs.com/package/@agentkitai/agentlens-mcp\"><img src=\"https://img.shields.io/npm/v/@agentkitai/agentlens-mcp?label=mcp\" alt=\"npm mcp\"></a>\n    <a href=\"https://opensource.org/licenses/MIT\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"></a>\n    <a href=\"https://github.com/agentkitai/agentlens/actions\"><img src=\"https://img.shields.io/github/actions/workflow/status/agentkitai/agentlens/ci.yml?branch=main\" alt=\"Build Status\"></a>\n    <a href=\"https://github.com/agentkitai/agentlens/pkgs/container/agentlens\"><img src=\"https://img.shields.io/badge/ghcr.io-agentkitai%2Fagentlens-2496ED?logo=docker&logoColor=white\" alt=\"Container: ghcr.io/agentkitai/agentlens\"></a>\n  </p>\n  <p align=\"center\">\n    <a href=\"./docs/\">📖 Documentation</a> · <a href=\"#-quick-start\">Quick Start</a> · <a href=\"#-dashboard\">Dashboard</a> · <a href=\"https://app.agentlens.ai\">☁️ Cloud</a>\n  </p>\n</p>\n\n---\n\n## 📑 Table of Contents\n\n- [Tamper-Evident by Design](#-tamper-evident-by-design)\n- [Quick Start](#-quick-start)\n- [Architecture](#-architecture)\n- [Integration Guides](#-integration-guides)\n- [Key Features](#-key-features)\n- [Dashboard](#-dashboard)\n- [AgentLens Cloud](#-agentlens-cloud)\n- [Packages](#-packages)\n- [API Overview](#-api-overview)\n- [CLI](#-cli)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [AgentKit Ecosystem](#-agentkit-ecosystem)\n- [License](#-license)\n\n---\n\nAgentLens 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.\n\n## 🔒 Tamper-evident by design\n\nWhat 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.\n\n**See it for yourself in 30 seconds** (needs Docker):\n\n```bash\ngit clone https://github.com/agentkitai/agentlens && cd agentlens\n./demo/aha.sh\n```\n\n```text\n1/5  Starting AgentLens (SQLite, zero-config)…   ✓ up at http://localhost:3400\n2/5  Ingesting a 5-event agent trace…            ✓ 5 events ingested\n3/5  Verifying the hash chain…                    ✓ CHAIN VALID — no tampering detected\n4/5  Tampering with one event in the database…   ✓ altered llm_call (changed the logged model)\n5/5  Re-verifying the hash chain…                 ✗ CHAIN BROKEN — tampering detected ✅\n```\n\nThe 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`.\n\n**Five ways to integrate — pick what fits your stack:**\n\n| Integration | Language | Effort | Capture |\n|---|---|---|---|\n| 🔭 **[OpenTelemetry](#-opentelemetry-any-genai-agent--no-sdk)** | Any | **Point your OTLP exporter** | Any `gen_ai.*`-instrumented agent — **no AgentLens SDK** |\n| 🤖 **[OpenClaw Plugin](#-openclaw-plugin)** | [OpenClaw](https://github.com/openclaw/openclaw) | **Copy & enable** | Every Anthropic call — prompts, tokens, cost, tools — zero code |\n| 🐍 **[Python Auto-Instrumentation](#-python-auto-instrumentation)** | Python | **1 line** | Every OpenAI / Anthropic / LangChain call — deterministic |\n| 🔌 **[MCP Server](#-mcp-integration)** | Any (MCP) | Config block | Tool calls, sessions, events from Claude Desktop / Cursor |\n| 📦 **[SDK](#-programmatic-sdk)** | Python, TypeScript | Code | Full control — log events, query analytics, build integrations |\n\n## 🚀 Quick Start\n\n**One command** — server + dashboard on SQLite, zero config:\n\n```bash\ndocker run -p 3400:3400 -e AUTH_DISABLED=true -e JWT_SECRET=dev-secret ghcr.io/agentkitai/agentlens\n# Open http://localhost:3400\n```\n\nOr without Docker:\n\n```bash\nnpx @agentkitai/agentlens-server\n# http://localhost:3400 with SQLite — zero config\n```\n\n> `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).\n\n**Full stack** (Postgres + Redis, auth, TLS) — runs from source:\n\n```bash\ngit clone https://github.com/agentkitai/agentlens && cd agentlens\ncp .env.example .env\ndocker compose up\n# production overlay (auth, restart policies):\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up\n```\n\n### Create an API Key\n\n```bash\ncurl -X POST http://localhost:3400/api/keys \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-agent\"}'\n```\n\nSave the `als_...` key from the response — it's shown only once. Then head to the [Integration Guides](#-integration-guides) to instrument your agent.\n\n📖 [Full setup guide →](./docs/guide/)\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TB\n    subgraph Agents[\"Your AI Agents\"]\n        PY[\"Python App<br/>(OpenAI, Anthropic, LangChain)\"]\n        MCP_C[\"MCP Client<br/>(Claude Desktop, Cursor)\"]\n        TS[\"TypeScript App\"]\n        OC[\"OpenClaw Plugin\"]\n    end\n\n    PY -->|\"agentlensai.init()<br/>auto-instrumentation\"| SERVER\n    MCP_C -->|MCP Protocol| MCP_S[\"@agentkitai/agentlens-mcp\"]\n    MCP_S -->|HTTP| SERVER\n    TS -->|\"@agentkitai/agentlens-sdk\"| SERVER\n    OC -->|HTTP| SERVER\n\n    subgraph Server[\"@agentkitai/agentlens-server\"]\n        direction TB\n        INGEST[Ingest Engine]\n        QUERY[Query Engine]\n        ALERT[Alert Engine]\n        LLM_A[LLM Analytics]\n        HEALTH[Health Scoring]\n        COST[Cost Optimizer]\n        REPLAY[Session Replay]\n        BENCH[Benchmark Engine]\n        GUARD[Guardrails]\n    end\n\n    SERVER --> DB[(SQLite / Postgres)]\n    SERVER --> DASH[\"Dashboard<br/>(React SPA)\"]\n\n    EXT[\"AgentGate / FormBridge\"] -->|Webhook| SERVER\n```\n\n## 🔧 Integration Guides\n\n### 🔭 OpenTelemetry (any GenAI agent — no SDK)\n\nIf your agent is already instrumented with the **[OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)** — via OpenLLMetry, OpenInference, or the official OTel instrumentations — just point its OTLP exporter at AgentLens. **No AgentLens SDK required.**\n\n```bash\n# Send standard OTLP/HTTP to AgentLens (JSON or protobuf, /v1/traces)\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3400\nexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:3400/v1/traces\n```\n\nAgentLens maps `gen_ai.*` spans into its model and into the tamper-evident audit log:\n\n| OTel GenAI span (`gen_ai.operation.name`) | Becomes |\n|---|---|\n| `chat` / `text_completion` / `generate_content` | a paired `llm_call` + `llm_response` (model, provider, messages, `usage.input_tokens`/`output_tokens`, finish reason, latency, **cost**) |\n| `execute_tool` | `tool_call` (`gen_ai.tool.name`, `gen_ai.tool.call.id`, arguments) |\n| `embeddings` | embedding event with token usage |\n| `invoke_agent` / `create_agent` | agent-invocation event |\n\nEach 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.\n\n> **Cost with no SDK:** OTel GenAI instrumentation reports tokens but rarely cost. AgentLens reconstructs `costUsd` from the model's per-1M-token pricing (fuzzy-matched on the model id), so OTel-only agents get the same cost analytics as SDK-instrumented ones — no per-call cost attribute required.\n\n### 🤖 OpenClaw Plugin\n\nIf you're running [OpenClaw](https://github.com/openclaw/openclaw), the AgentLens plugin captures every Anthropic API call automatically — prompts, completions, token usage, costs, latency, and tool calls.\n\n```bash\ncp -r packages/relay-plugin /usr/lib/node_modules/openclaw/extensions/agentlens-relay\nopenclaw config patch '{\"plugins\":{\"entries\":{\"agentlens-relay\":{\"enabled\":true}}}}'\nopenclaw gateway restart\n```\n\nSet `AGENTLENS_URL` if your AgentLens instance isn't on `localhost:3400`. See the [plugin README](./packages/relay-plugin/README.md) for details.\n\n### 🐍 Python Auto-Instrumentation\n\nOne line — every LLM call captured automatically across **9 providers** (OpenAI, Anthropic, LiteLLM, AWS Bedrock, Google Vertex AI, Google Gemini, Mistral AI, Cohere, Ollama):\n\n```bash\npip install agentlensai[all-providers]\n```\n\n```python\nimport agentlensai\n\nagentlensai.init(\n    url=\"http://localhost:3400\",\n    api_key=\"als_your_key\",\n    agent_id=\"my-agent\",\n)\n# Every LLM call is now captured automatically\n```\n\n**Key guarantees:** ✅ Deterministic · ✅ Fail-safe · ✅ Non-blocking · ✅ Privacy (`init(redact=True)`)\n\n📖 [Python SDK full docs →](./docs/guide/)\n\n### 🔌 MCP Integration\n\nFor Claude Desktop, Cursor, or any MCP client — add to your config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentlens\": {\n      \"command\": \"npx\",\n      \"args\": [\"@agentkitai/agentlens-mcp\"],\n      \"env\": {\n        \"AGENTLENS_API_URL\": \"http://localhost:3400\",\n        \"AGENTLENS_API_KEY\": \"als_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nAgentLens ships **22 MCP tools** — covering core observability, intelligence & analytics, and operations. [Full MCP tool reference →](./docs/reference/api.md)\n\n📖 [MCP setup guide →](./docs/guide/)\n\n### 📦 Programmatic SDK\n\n**Python:**\n```bash\npip install agentlensai\n```\n```python\nfrom agentlensai import AgentLensClient\nclient = AgentLensClient(\"http://localhost:3400\", api_key=\"als_your_key\")\nsessions = client.get_sessions()\nanalytics = client.get_llm_analytics()\n```\n\n**TypeScript:**\n```bash\nnpm install @agentkitai/agentlens-sdk\n```\n```typescript\nimport { AgentLensClient } from '@agentkitai/agentlens-sdk';\nconst client = new AgentLensClient({ baseUrl: 'http://localhost:3400', apiKey: 'als_your_key' });\nconst sessions = await client.getSessions();\n```\n\n📖 [SDK reference →](./docs/reference/api.md)\n\n## ✨ Key Features\n\n- **🐍 Python Auto-Instrumentation** — `agentlensai.init()` captures every LLM call across 9 providers automatically. Deterministic — no reliance on LLM behavior.\n- **🔌 MCP-Native** — Ships as an MCP server. Works with Claude Desktop, Cursor, and any MCP client.\n- **🔭 OpenTelemetry GenAI** — Ingests `gen_ai.*` OTLP traces from any OTel-instrumented agent (OpenLLMetry, OpenInference, official OTel) — no AgentLens SDK required.\n- **🧠 LLM Call Tracking** — Full prompt/completion visibility, token usage, cost aggregation, latency measurement, and privacy redaction.\n- **📊 Real-Time Dashboard** — Session timelines, event explorer, LLM analytics, cost tracking, and alerting.\n- **🔒 Tamper-Evident Audit Trail** — Append-only event storage with SHA-256 hash chains per session.\n- **💰 Cost Tracking** — Track token usage and estimated costs per session, per agent, per model. Alert on cost spikes.\n- **🚨 Alerting** — Configurable rules for error rate, cost threshold, latency anomalies, and inactivity.\n- **❤️‍🩹 Health Scores** — 5-dimension health scoring with trend tracking.\n- **💡 Cost Optimization** — Complexity-aware model recommendation engine with projected savings.\n- **📼 Session Replay** — Step-through any past session with full context reconstruction.\n- **⚖️ A/B Benchmarking** — Statistical comparison of agent variants using Welch's t-test and chi-squared analysis.\n- **🛡️ Guardrails** — Automated safety rules with dry-run mode for safe testing.\n- **🔌 Framework Plugins** — LangChain, CrewAI, AutoGen, Semantic Kernel — auto-detection, fail-safe, non-blocking.\n- **🔗 AgentKit Ecosystem** — Integrations with [AgentGate](https://github.com/agentkitai/agentgate), [FormBridge](https://github.com/agentkitai/formbridge), [Lore](https://github.com/agentkitai/lore), and [AgentEval](https://github.com/agentkitai/agenteval).\n- **🔒 Tenant Isolation** — Multi-tenant support with per-tenant data scoping and API key binding.\n- **🏠 Self-Hosted** — SQLite by default, no external dependencies. MIT licensed.\n\n## 📸 Dashboard\n\nAgentLens ships with a real-time web dashboard for monitoring your agents.\n\n<details>\n<summary>📸 Dashboard Screenshots (click to expand)</summary>\n\n### Overview — At-a-Glance Metrics\n\n![Dashboard Overview](demo/dashboard-overview.jpg)\n\nThe overview page shows **live metrics** — sessions, events, errors, and active agents — with a 24-hour event timeline chart, recent sessions with status badges, and a recent errors feed.\n\n### Sessions — Track Every Agent Run\n\n![Sessions List](demo/dashboard-sessions.jpg)\n\nEvery agent session with sortable columns: agent name, status, start time, duration, event count, error count, and total cost.\n\n### Session Detail — Timeline & Hash Chain\n\n![Session Detail](demo/dashboard-session-detail.jpg)\n\nFull event timeline with tamper-evident hash chain verification. Filter by event type, view cost breakdown.\n\n### Events Explorer — Search & Filter Everything\n\n![Events Explorer](demo/dashboard-events.jpg)\n\nSearchable, filterable view of every event across all sessions.\n\n### 🧠 LLM Analytics — Prompt & Cost Tracking\n\n![LLM Analytics](demo/dashboard-llm-analytics.jpg)\n\nTotal LLM calls, cost, latency, and token usage across all agents with model comparison.\n\n### 🧠 Session Timeline — LLM Call Pairing\n\n![LLM Timeline](demo/dashboard-llm-timeline.jpg)\n\nLLM calls in session timeline with model, tokens, cost, and latency.\n\n### 💬 Prompt Detail — Chat Bubble Viewer\n\n![LLM Call Detail](demo/dashboard-llm-detail.jpg)\n\nFull prompt and completion in a chat-bubble style viewer with metadata panel.\n\n### ❤️‍🩹 Health Overview — Agent Reliability\n\n![Health Overview](demo/dashboard-health.jpg)\n\n5-dimension health score for every agent with trend tracking.\n\n### 💡 Cost Optimization — Model Recommendations\n\n![Cost Optimization](demo/dashboard-cost-optimization.jpg)\n\nAnalyzes LLM call patterns and recommends cheaper model alternatives with confidence levels.\n\n### 📼 Session Replay — Step-Through Debugger\n\n![Session Replay](demo/dashboard-session-replay.jpg)\n\nStep through any past session event by event with full context reconstruction.\n\n### ⚖️ Benchmarks — A/B Testing for Agents\n\n![Benchmarks](demo/dashboard-benchmarks.jpg)\n\nCreate and manage A/B experiments with statistical significance testing.\n\n### 🛡️ Guardrails — Automated Safety Rules\n\n![Guardrails](demo/dashboard-guardrails.jpg)\n\nCreate and manage automated safety rules with trigger history and activity feed.\n\n</details>\n\n## ☁️ AgentLens Cloud\n\nDon't want to self-host? **AgentLens Cloud** is a fully managed SaaS — same SDK, zero infrastructure:\n\n```python\nimport agentlensai\nagentlensai.init(cloud=True, api_key=\"als_cloud_your_key_here\", agent_id=\"my-agent\")\n```\n\n- **Same SDK, one parameter change** — switch `url=` to `cloud=True`\n- **Managed Postgres** — multi-tenant with row-level security\n- **Team features** — organizations, RBAC, audit logs\n- **No server to run** — dashboard at [app.agentlens.ai](https://app.agentlens.ai)\n\n📖 [Cloud Setup Guide](./docs/guide/cloud-setup.md) · [Migration Guide](./docs/guide/cloud-migration.md) · [Troubleshooting](./docs/guide/troubleshooting.md)\n\n## 📦 Packages\n\n### Python (PyPI)\n\n| Package | Description | PyPI |\n|---|---|---|\n| [`agentlensai`](./packages/python-sdk) | Python SDK + auto-instrumentation for 9 LLM providers | [![PyPI](https://img.shields.io/pypi/v/agentlensai)](https://pypi.org/project/agentlensai/) |\n\n### TypeScript / Node.js (npm)\n\n| Package | Description | npm |\n|---|---|---|\n| [`@agentkitai/agentlens-server`](./packages/server) | Hono API server + dashboard serving | [![npm](https://img.shields.io/npm/v/@agentkitai/agentlens-server)](https://npmjs.com/package/@agentkitai/agentlens-server) |\n| [`@agentkitai/agentlens-mcp`](./packages/mcp) | MCP server for agent instrumentation | [![npm](https://img.shields.io/npm/v/@agentkitai/agentlens-mcp)](https://npmjs.com/package/@agentkitai/agentlens-mcp) |\n| [`@agentkitai/agentlens-sdk`](./packages/sdk) | Programmatic TypeScript client | [![npm](https://img.shields.io/npm/v/@agentkitai/agentlens-sdk)](https://npmjs.com/package/@agentkitai/agentlens-sdk) |\n| [`@agentkitai/agentlens-core`](./packages/core) | Shared types, schemas, hash chain utilities | [![npm](https://img.shields.io/npm/v/@agentkitai/agentlens-core)](https://npmjs.com/package/@agentkitai/agentlens-core) |\n| [`@agentkitai/agentlens-cli`](./packages/cli) | Command-line interface | [![npm](https://img.shields.io/npm/v/@agentkitai/agentlens-cli)](https://npmjs.com/package/@agentkitai/agentlens-cli) |\n| [`@agentkitai/agentlens-dashboard`](./packages/dashboard) | React web dashboard (bundled with server) | private |\n\n## 🔌 API Overview\n\n| Endpoint | Description |\n|---|---|\n| `POST /api/events` | Ingest events (batch) |\n| `GET /api/events` | Query events with filters |\n| `GET /api/sessions` | List sessions |\n| `GET /api/sessions/:id/timeline` | Session timeline with hash chain verification |\n| `GET /api/analytics` | Bucketed metrics over time |\n\n[Full API Reference →](./docs/reference/api.md)\n\n## ⌨️ CLI\n\n```bash\nnpx @agentkitai/agentlens-cli health                          # Overview of all agents\nnpx @agentkitai/agentlens-cli health --agent my-agent          # Detailed health with dimensions\nnpx @agentkitai/agentlens-cli optimize                          # Cost optimization recommendations\n```\n\nBoth commands support `--format json` for machine-readable output. See `agentlens health --help` for all options.\n\n## 🛠️ Development\n\n```bash\ngit clone https://github.com/agentkitai/agentlens.git\ncd agentlens\npnpm install\n\npnpm typecheck && pnpm test && pnpm lint  # Run all checks\npnpm dev                                   # Start dev server\n```\n\n**Requirements:** Node.js ≥ 20.0.0 · pnpm ≥ 10.0.0\n\n## 🤝 Contributing\n\nWe welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for setup instructions, coding standards, and the PR process.\n\n## 🧰 AgentKit Ecosystem\n\n| Project | Description | |\n|---------|-------------|-|\n| **AgentLens** | Observability & tamper-evident audit trail for AI agents | ⬅️ you are here |\n| [AgentGate](https://github.com/agentkitai/agentgate) | Human-in-the-loop approval gateway + reactive guardrails | |\n| [Lore](https://github.com/agentkitai/lore) | Cross-agent memory and lesson sharing | |\n| [AgentEval](https://github.com/agentkitai/agenteval) | Testing & evaluation framework | |\n| [FormBridge](https://github.com/agentkitai/formbridge) | Agent-human mixed-mode forms | |\n\n## 📄 License\n\n[MIT](LICENSE) © [Amit Paz](https://github.com/amitpaz)\n",
  "bytes": 19326,
  "sha": "dd4e0e431311be5f835ad3a90bd9d7bd544950519cd293e8fdd0ea20d003c6ed",
  "repo_slug": "agentkitai/agentlens",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agentkitai_agentlens_b68f00a1/readme"
}