# Agentlens

> Open-source observability platform for AI agents. Trace every LLM call, tool use, and decision in real-time. Supports OpenAI, Anthropic, Gemini, LangChain, CrewAI, LiteLLM, MCP. Self-hosted. Zero dependencies.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nitin-100-agentlens`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Nitin-100](https://agentstack.voostack.com/s/nitin-100)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Nitin-100](https://github.com/Nitin-100)
- **Source:** https://github.com/Nitin-100/agentlens
- **Website:** https://github.com/Nitin-100/agentlens#readme

## Install

```sh
agentstack add mcp-nitin-100-agentlens
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

AgentLens

  Open-source observability for AI agents. Enterprise-grade security.
  Trace every LLM call, tool use, and decision — in real-time. HIPAA/SOC2/GDPR ready.

  
  
  
  
  
  
  

  Quick Start · Features · Architecture · Integrations · Security · vs Langfuse · Watch Demo

---

  
    
    
    ▶ Click to watch the full demo video
  

---

## What is AgentLens?

AgentLens is a **self-hosted observability platform** for AI agents. It captures every LLM call, tool invocation, agent step, and error across any framework — OpenAI, Anthropic, Gemini, LangChain, CrewAI, LiteLLM, MCP — and shows it all in a real-time dashboard with trace trees, execution graphs, cost anomaly detection, and prompt diffs.

**3 lines to instrument your existing agent:**

```python
from agentlens import AgentLens, auto_patch

lens = AgentLens(server_url="http://localhost:8340")
auto_patch()  # auto-detects & patches OpenAI, Claude, Gemini, LangChain, CrewAI, LiteLLM, MCP

# Your existing code — zero changes needed
response = openai.chat.completions.create(model="gpt-4o", messages=[...])
# ^ model, tokens, cost, latency, response — all captured automatically
```

> **🚀 [Get started in 2 minutes → Quick Start Guide](QUICKSTART.md)**

---

## How It Works

```
  Your Agent Code
  ┌──────────────────────────────────────────────────────────┐
  │  OpenAI · Anthropic · Gemini · LangChain · CrewAI · MCP │
  └──────────────────────────┬───────────────────────────────┘
                             │  auto_patch()
                             ▼
                    ┌─────────────────┐
                    │  AgentLens SDK  │  ← zero dependencies
                    │  Batch · Retry  │
                    │  Circuit Breaker│
                    └────────┬────────┘
                             │  HTTP POST (batched every 2s)
                             ▼
  ┌──────────────────────────────────────────────────────────┐
  │               AgentLens Backend (FastAPI)                │
  │                                                          │
  │  ┌────────────┐  ┌──────────┐  ┌───────────────────┐    │
  │  │ Processors │  │ Database │  │    Exporters      │    │
  │  │ PII Redact │  │ SQLite   │  │ S3 · Kafka        │    │
  │  │ Sampling   │→ │ Postgres │→ │ Webhook · File    │    │
  │  │ Filtering  │  │ ClickHse │  └───────────────────┘    │
  │  └────────────┘  └──────────┘                            │
  │                                                          │
  │  OTEL /v1/traces · WebSocket /ws/live · REST API         │
  │  Cost Anomaly Detection · Prompt Diff · Alert Webhooks   │
  └──────────────────────────┬───────────────────────────────┘
                             │
                             ▼
  ┌──────────────────────────────────────────────────────────┐
  │                   Dashboard (React)                      │
  │  Overview · Sessions · Trace Tree · Agent Graph (DAG)   │
  │  Live Feed · Cost Anomalies · Alerts · Prompt Diff      │
  └──────────────────────────────────────────────────────────┘
```

**Data flow:** SDK intercepts LLM calls → batches events → Backend runs through processor pipeline (PII redaction, sampling, filtering) → stores in pluggable DB → forwards to exporters → Dashboard renders in real-time via WebSocket.

---

## Features

| | Feature | Description |
|---|---|---|
| 📡 | **Live Event Feed** | See every LLM call, tool use, and decision as it happens (WebSocket) |
| 🌳 | **Trace Tree** | Collapsible parent→child span hierarchy with timing waterfall |
| 🔗 | **Agent Graph** | Visual DAG of agent execution flow, color-coded by status |
| 🔍 | **Prompt Replay & Diff** | Click any LLM call to see prompt/completion, diff against similar prompts |
| 📉 | **Cost Anomaly Detection** | Zero-config — auto-flags when daily cost exceeds 2× rolling average |
| 💰 | **Cost Tracking** | Automatic pricing for 20+ models (GPT-4o, Claude 4, Gemini Pro, etc.) |
| 🔌 | **Plugin System** | Swap DB (SQLite → Postgres → ClickHouse), add exporters (S3, Kafka, Webhook) |
| 🛡️ | **PII Redaction** | Auto-scrubs emails, phones, SSNs, credit cards, API keys before storage |
| 🔐 | **Encryption at Rest** | AES-128-CBC + HMAC-SHA256 (Fernet) field-level encryption (fail-closed) |
| 🔑 | **RBAC & API Keys** | Admin/Member/Viewer roles, key rotation with grace period, HMAC-SHA256 hashing |
| 🏥 | **HIPAA Compliance** | PHI auto-detection (SSN, MRN, diagnosis, medication), auto-masking, audit trail |
| 📋 | **SOC2 Type II Ready** | Access controls, encryption, logging, incident response, data retention |
| 🇪🇺 | **GDPR Compliant** | Data subject access, erasure, export APIs (Right to Access/Erasure/Portability) |
| 🚨 | **Breach Detection** | Auto IP lockout after brute force, webhook alerts, configurable thresholds |
| 🛡️ | **SSRF Protection** | Webhook URL validation blocks private/internal networks |
| 📊 | **Prometheus Metrics** | Native `/metrics` endpoint — plug into Grafana |
| 🤖 | **MCP Native** | MCP client monitoring + MCP server for Claude Desktop |
| 🧪 | **One-Click Demo** | Load 500+ events across 5 agent types to explore instantly |
| 🌐 | **OTEL Ingestion** | Accept traces from any OpenTelemetry-compatible tool |
| ⚡ | **Zero Dependencies** | Core SDK uses only Python stdlib — no conflicts, ever |

---

## Integrations

Works with **any** AI agent framework. One `auto_patch()` call instruments everything:

| Framework | Method | What's Captured |
|---|---|---|
| **OpenAI** | `auto_patch()` | model, tokens, cost, latency, response |
| **Anthropic / Claude** | `auto_patch()` | model, tokens, tool_use blocks, cost |
| **Google Gemini / ADK** | `auto_patch()` | model, tokens, cost |
| **LangChain / LangGraph** | Callback handler | chains, tools, agents, retries |
| **CrewAI** | `auto_patch()` | kickoff, task execution, agent actions |
| **LiteLLM** (100+ providers) | `auto_patch()` | all providers via unified API |
| **MCP** | `auto_patch()` | tool calls, resource reads |
| **Any language** | REST API | POST JSON to `/api/v1/events` |

See framework-specific code examples

### OpenAI
```python
from agentlens import AgentLens
from agentlens.integrations.openai import patch_openai
lens = AgentLens(server_url="http://localhost:8340")
patch_openai(lens)
response = openai.chat.completions.create(model="gpt-4o", messages=[...])
```

### Anthropic / Claude
```python
from agentlens.integrations.anthropic import patch_anthropic
patch_anthropic(lens)
response = client.messages.create(model="claude-sonnet-4-20250514", messages=[...])
```

### Google Gemini
```python
from agentlens.integrations.google_adk import patch_gemini, patch_google_adk
patch_gemini(lens)
patch_google_adk(lens)
```

### LangChain
```python
from agentlens.integrations.langchain import AgentLensCallbackHandler
handler = AgentLensCallbackHandler(lens)
chain = LLMChain(llm=ChatOpenAI(), prompt=prompt, callbacks=[handler])
```

### CrewAI
```python
from agentlens.integrations.crewai import patch_crewai
patch_crewai(lens)
crew = Crew(agents=[analyst], tasks=[task])
result = crew.kickoff()
```

### LiteLLM
```python
from agentlens.integrations.litellm import patch_litellm
patch_litellm(lens)
response = litellm.completion(model="ollama/llama3", messages=[...])
```

### Custom / Manual
```python
lens.record_llm_call(model="my-model", prompt="...", response="...", tokens_in=100, tokens_out=50)
lens.record_tool_call(tool_name="my-tool", args={"key": "value"}, result="success", duration_ms=150)
lens.record_step(step_name="process", data={"status": "done"})
```

---

## Multi-Language SDKs

| Language | Install | Status |
|---|---|---|
| Python | `pip install agentlens` | ✅ Full SDK + CLI + auto-patch |
| TypeScript | `npm install @agentlens/sdk` | ✅ Full types, OpenAI/Anthropic patch |
| JavaScript | `sdk/javascript/agentlens.js` | ✅ Node.js + Browser |
| Go | `sdk/go/agentlens.go` | ✅ Native SDK |
| Java | `sdk/java/` | ✅ Java 11+, zero deps |
| Any language | REST API | ✅ cURL examples in `sdk/rest-api/` |
| OpenTelemetry | `POST /v1/traces` | ✅ OTLP JSON ingestion |

See examples for each language

### TypeScript
```typescript
import { AgentLens, patchOpenAI } from '@agentlens/sdk';
const lens = new AgentLens({ serverUrl: 'http://localhost:8340', agentName: 'my-agent' });
const openai = new OpenAI();
patchOpenAI(openai, lens);
// All calls auto-tracked
```

### Go
```go
lens := agentlens.New("http://localhost:8340", "al_your_key")
defer lens.Shutdown()
sess := lens.StartSession("my-agent")
lens.TrackLLMCall(agentlens.LLMEvent{Model: "gpt-4o", Prompt: "Hello"})
lens.EndSession(sess, true, nil)
```

### Java
```java
AgentLens lens = new AgentLens("http://localhost:8340", "al_your_key");
String session = lens.startSession("my-agent");
lens.trackLLMCall("gpt-4o", "openai", "Hello", "Hi!", 5, 3, 0.001, 200);
lens.endSession(session, true, Map.of());
lens.shutdown();
```

### cURL (any language)
```bash
curl -X POST http://localhost:8340/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{"events": [{"event_type": "llm.response", "model": "gpt-4o", "prompt": "Hello"}]}'
```

---

## Plugin System

Extend every layer — databases, exporters, and event processors.

```
Events → [Processors: PII · Sample · Filter · Enrich] → [Database] → [Exporters: S3 · Kafka · Webhook · File]
```

Database plugins — swap storage without code changes

```python
from agentlens.plugins import PluginRegistry
from agentlens.builtin_plugins import PostgreSQLPlugin, ClickHousePlugin

registry = PluginRegistry.get_instance()

# PostgreSQL for production
registry.register_database(PostgreSQLPlugin(dsn="postgresql://user:pass@localhost:5432/agentlens"))

# ClickHouse for analytics at scale
registry.register_database(ClickHousePlugin(url="http://localhost:8123", database="agentlens"))
```

| Plugin | Best For | Scale |
|---|---|---|
| SQLite (built-in) | Development | 

Exporter plugins — send events to external systems

```python
from agentlens.builtin_plugins import S3Exporter, WebhookExporter, KafkaExporter, FileExporter

registry.register_exporter(S3Exporter(bucket="my-data", prefix="events/"))
registry.register_exporter(WebhookExporter(url="https://hooks.slack.com/...", filter_types=["error"]))
registry.register_exporter(KafkaExporter(bootstrap_servers="localhost:9092", topic="agentlens.events"))
registry.register_exporter(FileExporter(directory="./logs", max_file_mb=100))
```

Event processors — transform events before storage

```python
from agentlens.builtin_plugins import PIIRedactor, SamplingProcessor, FilterProcessor, EnrichmentProcessor

registry.register_processor(PIIRedactor())                                    # scrub emails, phones, SSNs
registry.register_processor(SamplingProcessor(rate=0.1))                      # keep 10% (always keeps errors)
registry.register_processor(FilterProcessor(drop_types=["custom.debug"]))     # drop noisy events
registry.register_processor(EnrichmentProcessor(metadata={"env": "prod"}))    # tag every event
```

Event hooks & custom plugins

```python
@registry.on("error")
def on_error(event):
    print(f"Error in {event['agent_name']}: {event.get('error_type')}")

@registry.on_async("session.end")
async def on_session_end(event):
    if event.get("total_cost_usd", 0) > 5.0:
        await send_alert(f"Expensive session: ${event['total_cost_usd']:.2f}")
```

Build your own by implementing `DatabasePlugin`, `ExporterPlugin`, or `EventProcessor` base classes.

---

## MCP Support

First-class Model Context Protocol support — both as a client monitor and as an MCP server.

MCP client monitoring

```python
from agentlens.integrations.mcp import patch_mcp
patch_mcp(lens)

async with ClientSession(read, write) as session:
    result = await session.call_tool("web_search", {"query": "AI agents"})
    # ^ automatically captured
```

MCP server — query AgentLens from Claude Desktop

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "agentlens": {
      "command": "agentlens-mcp",
      "args": ["--server-url", "http://localhost:8340"]
    }
  }
}
```

**Resources:** `agentlens://sessions` · `agentlens://analytics` · `agentlens://errors` · `agentlens://health`

**Tools:** `query_sessions` · `query_analytics` · `query_errors` · `get_session_detail` · `create_alert_rule` · `get_system_health`

> *"Show me all failed sessions from research-agent in the last 24 hours"*

---

## Security

> **See [SECURITY.md](SECURITY.md) for the full security policy, vulnerability reporting, and environment variables.**

| Capability | Details |
|---|---|
| **Encryption at rest** | AES-128-CBC + HMAC-SHA256 (Fernet) — fail-closed (rejects data on error, never stores plaintext) |
| **TLS** | Built-in uvicorn SSL, self-signed cert generator, HSTS headers |
| **RBAC** | Admin / Member / Viewer (14/7/4 permissions), per-project API key scoping |
| **API key security** | HMAC-SHA256 hashed (keyed, not plain SHA-256), auto-generated on first run |
| **Auth by default** | `AGENTLENS_REQUIRE_AUTH=true` by default. No-auth falls back to viewer (read-only) |
| **CORS locked** | No wildcard — must explicitly set `AGENTLENS_CORS_ORIGINS` |
| **PHI/PII detection** | Auto-scans for SSN, MRN, DOB, diagnosis, medication, email, phone, credit cards, Aadhaar, PAN, API keys |
| **Breach detection** | Auto IP lockout after brute force (default: 10 failed auths in 5 min), webhook notification |
| **SSRF protection** | Webhook URLs validated — blocks private IPs, localhost, cloud metadata endpoints |
| **Session timeout** | Configurable (default: 30 min) |
| **IP allowlisting** | Per-project IP restrictions |
| **PII redaction** | Emails, phones, SSNs, credit cards, API keys — auto-scrubbed |
| **Audit logging** | Every admin action: timestamp, IP, user-agent |
| **Data retention** | Per-project policies, automated background purge |
| **Multi-tenancy** | Project-level data isolation |
| **Self-hosted** | Your data never leaves your infrastructure |
| **Docker hardened** | Non-root container, multi-stage build, resource limits |

### Compliance

| Framework | Status | Key Controls |
|-----------|--------|--------------|
| **HIPAA** | Ready | Encryption at rest, PHI auto-detection, audit logs, access controls, breach notification, data retention |
| **SOC2 Type II** | Ready | RBAC, encryption, logging, incident response, data retention, network security |
| **GDPR** | Compliant | Data subject access/erasure/export APIs, data minimization, breach notification |

Configuration examples

```bash
# Authentication (enabled by default)
export AGENTLENS_REQUIRE_AUTH=true

# CORS — set to your dashboard URL
export AGENTLENS_CORS_ORIGINS=http://localhost:5173

# HMAC secret for API key hashing (generate: python -c "import secrets; print(secrets.token_hex(32))")
export AGENTLENS_HMAC_SECRET=your-secret-here

# Encryption at rest (generate: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
export AGENTLENS_ENCRYPTION_KEY="your-base64-fernet-key"

# TLS
export AGENTLENS_TLS_CERT=agentlens-cert.pem
export AGENTLENS_TLS_KEY=agentlens-key.pem

# Breach detection webhook (Slack/Discord/PagerDuty)
export AGENTLENS_BREACH_WEBHOOK=https://hooks.slack.com/services/...
export AGENTLENS_BREACH_THRESHOLD=10

# Session timeout (minutes)
export AGENTLENS_SESSION_TIMEOUT=30

# GDPR: Data subject erasure
curl -X DELETE http://localhost:8340/api/v1/gdpr/erase \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"user_id": "user_123"}'

# Compliance posture report
curl http://localhost:8340/api/v1/compliance/posture \
  -H "Authorization: Bearer $API_KEY"

# Key rotation (24h grace period)
curl -X POST http://localhost:8340/api/v1/keys/{key_id}/rotate \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"grace_period_hours": 24}'

# Data retention — 90 days
curl -X PUT http://localhost:8340/api/v1/retention \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"retention_days": 90, "delete_events": true, "delete_sessions": true}'
```

---

## Deployment

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Nitin-100](https://github.com/Nitin-100)
- **Source:** [Nitin-100/agentlens](https://github.com/Nitin-100/agentlens)
- **License:** MIT
- **Homepage:** https://github.com/Nitin-100/agentlens#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nitin-100-agentlens
- Seller: https://agentstack.voostack.com/s/nitin-100
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.