{"id":46566594,"url":"https://github.com/agentkitai/agentlens","last_synced_at":"2026-03-07T07:12:03.758Z","repository":{"id":337191911,"uuid":"1152641248","full_name":"agentkitai/agentlens","owner":"agentkitai","description":"Open-source observability and audit trail platform for AI agents. MCP-native, tamper-evident event logging, real-time dashboard.","archived":false,"fork":false,"pushed_at":"2026-02-13T15:43:25.000Z","size":10431,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T00:27:31.385Z","etag":null,"topics":["agent-observability","ai-agents","ai-safety","hono","mcp","model-context-protocol","observability","react","typescript"],"latest_commit_sha":null,"homepage":"https://amitpaz1.github.io/agentlens/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentkitai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T07:24:18.000Z","updated_at":"2026-02-13T15:43:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentkitai/agentlens","commit_stats":null,"previous_names":["amitpaz1/agentlens","agentkitai/agentlens"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/agentkitai/agentlens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentkitai%2Fagentlens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentkitai%2Fagentlens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentkitai%2Fagentlens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentkitai%2Fagentlens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentkitai","download_url":"https://codeload.github.com/agentkitai/agentlens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentkitai%2Fagentlens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-observability","ai-agents","ai-safety","hono","mcp","model-context-protocol","observability","react","typescript"],"created_at":"2026-03-07T07:12:03.221Z","updated_at":"2026-03-07T07:12:03.731Z","avatar_url":"https://github.com/agentkitai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e🔍 AgentLens\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eOpen-source observability \u0026 audit trail for AI agents\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/agentlensai/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/agentlensai?label=pypi\" alt=\"PyPI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@agentlensai/server\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@agentlensai/server?label=npm\" alt=\"npm server\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@agentlensai/mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@agentlensai/mcp?label=mcp\" alt=\"npm mcp\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/agentkitai/agentlens/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/agentkitai/agentlens/ci.yml?branch=main\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003c!-- TODO: Add Docker badge when image is published to GHCR/Docker Hub --\u003e\n    \u003c!-- \u003ca href=\"https://ghcr.io/agentkitai/agentlens\"\u003e\u003cimg src=\"https://img.shields.io/docker/v/agentkitai/agentlens?label=docker\" alt=\"Docker\"\u003e\u003c/a\u003e --\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"./docs/\"\u003e📖 Documentation\u003c/a\u003e · \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e · \u003ca href=\"#-dashboard\"\u003eDashboard\u003c/a\u003e · \u003ca href=\"https://app.agentlens.ai\"\u003e☁️ Cloud\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n## 📑 Table of Contents\n\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**Four ways to integrate — pick what fits your stack:**\n\n| Integration | Language | Effort | Capture |\n|---|---|---|---|\n| 🤖 **[OpenClaw Plugin](#-openclaw-plugin)** | [OpenClaw](https://github.com/openclaw/openclaw) | **Copy \u0026 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### Docker (recommended)\n\n```bash\ngit clone https://github.com/agentkitai/agentlens\ncd agentlens\ncp .env.example .env\ndocker compose up\n# Open http://localhost:3000\n```\n\nFor production (auth enabled, Stripe, TLS):\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up\n```\n\n### Without Docker\n\n```bash\nnpx @agentlensai/server\n# Opens on http://localhost:3400 with SQLite — zero config\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\u003cbr/\u003e(OpenAI, Anthropic, LangChain)\"]\n        MCP_C[\"MCP Client\u003cbr/\u003e(Claude Desktop, Cursor)\"]\n        TS[\"TypeScript App\"]\n        OC[\"OpenClaw Plugin\"]\n    end\n\n    PY --\u003e|\"agentlensai.init()\u003cbr/\u003eauto-instrumentation\"| SERVER\n    MCP_C --\u003e|MCP Protocol| MCP_S[\"@agentlensai/mcp\"]\n    MCP_S --\u003e|HTTP| SERVER\n    TS --\u003e|\"@agentlensai/sdk\"| SERVER\n    OC --\u003e|HTTP| SERVER\n\n    subgraph Server[\"@agentlensai/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 --\u003e DB[(SQLite / Postgres)]\n    SERVER --\u003e DASH[\"Dashboard\u003cbr/\u003e(React SPA)\"]\n\n    EXT[\"AgentGate / FormBridge\"] --\u003e|Webhook| SERVER\n```\n\n## 🔧 Integration Guides\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/openclaw-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:3000`. See the [plugin README](./packages/openclaw-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\": [\"@agentlensai/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 **12 MCP tools** — 5 core observability, 3 intelligence \u0026 analytics, 4 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 @agentlensai/sdk\n```\n```typescript\nimport { AgentLensClient } from '@agentlensai/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- **🧠 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\u003cdetails\u003e\n\u003csummary\u003e📸 Dashboard Screenshots (click to expand)\u003c/summary\u003e\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 \u0026 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 \u0026 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 \u0026 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\u003c/details\u003e\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, usage billing\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| [`@agentlensai/server`](./packages/server) | Hono API server + dashboard serving | [![npm](https://img.shields.io/npm/v/@agentlensai/server)](https://npmjs.com/package/@agentlensai/server) |\n| [`@agentlensai/mcp`](./packages/mcp) | MCP server for agent instrumentation | [![npm](https://img.shields.io/npm/v/@agentlensai/mcp)](https://npmjs.com/package/@agentlensai/mcp) |\n| [`@agentlensai/sdk`](./packages/sdk) | Programmatic TypeScript client | [![npm](https://img.shields.io/npm/v/@agentlensai/sdk)](https://npmjs.com/package/@agentlensai/sdk) |\n| [`@agentlensai/core`](./packages/core) | Shared types, schemas, hash chain utilities | [![npm](https://img.shields.io/npm/v/@agentlensai/core)](https://npmjs.com/package/@agentlensai/core) |\n| [`@agentlensai/cli`](./packages/cli) | Command-line interface | [![npm](https://img.shields.io/npm/v/@agentlensai/cli)](https://npmjs.com/package/@agentlensai/cli) |\n| [`@agentlensai/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 @agentlensai/cli health                          # Overview of all agents\nnpx @agentlensai/cli health --agent my-agent          # Detailed health with dimensions\nnpx @agentlensai/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 \u0026\u0026 pnpm test \u0026\u0026 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 \u0026 audit trail for AI agents | ⬅️ you are here |\n| [Lore](https://github.com/agentkitai/lore) | Cross-agent memory and lesson sharing | |\n| [AgentGate](https://github.com/agentkitai/agentgate) | Human-in-the-loop approval gateway | |\n| [FormBridge](https://github.com/agentkitai/formbridge) | Agent-human mixed-mode forms | |\n| [AgentEval](https://github.com/agentkitai/agenteval) | Testing \u0026 evaluation framework | |\n| [agentkit-mesh](https://github.com/agentkitai/agentkit-mesh) | Agent discovery \u0026 delegation | |\n| [agentkit-cli](https://github.com/agentkitai/agentkit-cli) | Unified CLI orchestrator | |\n| [agentkit-guardrails](https://github.com/agentkitai/agentkit-guardrails) | Reactive policy guardrails | |\n\n## 📄 License\n\n[MIT](LICENSE) © [Amit Paz](https://github.com/amitpaz)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentkitai%2Fagentlens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentkitai%2Fagentlens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentkitai%2Fagentlens/lists"}