Agentlens

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:

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

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

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

Google Gemini

from agentlens.integrations.google_adk import patch_gemini, patch_google_adk
patch_gemini(lens)
patch_google_adk(lens)

LangChain

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

CrewAI

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

LiteLLM

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

Custom / Manual

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

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

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

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)

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

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

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

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

@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

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:

{
  "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

# 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
• Source: Nitin-100/agentlens
• License: MIT
• Homepage: https://github.com/Nitin-100/agentlens#readme

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