Chrome DevTools for AI Agents. Capture, replay, and inspect every LLM call, tool invocation, and decision in your multi-agent workflows.
🎯 The Problem: Multi-agent AI systems are a black box. When an agent fails, burns money in a loop, or makes a bad decision — you have no way to see why.
💡 The Solution: AgentLens captures every step and lets you replay, inspect, and debug the entire execution like a video player with a timeline scrubber.
Scrub through your agent's entire execution timeline. Click any step to see exactly what happened — the full prompt, response, tokens, cost, and decision rationale.
Real-time token & cost tracking per agent, per step, per model. Know exactly where your money is going.
Automatic detection of:
- Infinite loops — Agent stuck in fix→test→fail cycles
- Token escalation — Context window growing out of control
- Repeated prompts — 85%+ similarity with previous prompts
- Empty responses — Model returned nothing useful
Dedicated panel for Model Context Protocol tool invocations. See which MCP servers were called, with what params, and what they returned.
Color-coded agent badges, agent flow trees, and per-agent cost breakdowns. See your entire orchestration at a glance.
Play, pause, step forward, reset. Scrub through the timeline like a video player.
git clone https://github.com/ModernOps888/agentlens.git
cd agentlens
npm install
npm run devOpen http://localhost:3000 — the app ships with built-in demo data showing:
- Successful workflow: A 5-agent LinkedIn blog post pipeline (Orchestrator → Researcher → Writer → Editor → Publisher)
- Failed workflow: A coding agent caught in an infinite fix-test loop with automatic halt
pip install requestsfrom agentlens import AgentLens
# Start a trace session
lens = AgentLens(session_name="My Agent Pipeline")
# Option A: Wrap OpenAI (automatic tracing — zero code changes)
from openai import OpenAI
client = lens.wrap_openai(OpenAI(), agent_name="MyAgent")
response = client.chat.completions.create(model="gpt-4o", messages=[...])
# ^ Every call is now traced in AgentLens!
# Option B: Wrap Anthropic (Claude)
from anthropic import Anthropic
client = lens.wrap_anthropic(Anthropic(), agent_name="ClaudeAgent")
response = client.messages.create(model="claude-4-sonnet", max_tokens=1024, messages=[...])
# Option C: Wrap Google Gemini
import google.generativeai as genai
model = lens.wrap_google(genai.GenerativeModel("gemini-2.5-flash"), agent_name="GeminiAgent")
response = model.generate_content("Explain quantum computing")
# Option D: Wrap Ollama (local LLMs — no package needed)
ollama = lens.wrap_ollama(agent_name="LocalLLM")
response = ollama.chat(model="llama3", messages=[{"role": "user", "content": "Hello!"}])
# Option E: Wrap LiteLLM (any provider via proxy)
import litellm
litellm.callbacks = [lens.wrap_litellm(agent_name="MultiModel")]
# Option F: Manual tracing
lens.trace_llm_call(
agent_name="Researcher",
model="gpt-4o",
prompt="Research this topic...",
response="Here are the findings...",
tokens={"prompt_tokens": 150, "completion_tokens": 200, "total_tokens": 350},
)
# Trace tool calls, MCP invocations, agent spawns, decisions, errors
lens.trace_tool_call(agent_name="Coder", tool_name="file_read", tool_input={"path": "main.py"})
lens.trace_mcp_call(agent_name="Agent", server_name="web-search", tool_name="search", params={"q": "..."})
lens.trace_agent_spawn(parent_agent="Orchestrator", spawned_agent="Writer")
lens.trace_decision(agent_name="Orchestrator", reason="Quality score 9/10, proceeding")
lens.trace_error(agent_name="Coder", error_message="Test failed: assertion error")
lens.end() # Mark session completeNote: Copy
sdk/python/agentlens.pyinto your project, or add it to your Python path. The SDK sends traces tohttp://localhost:3000/api/ingestby default.
# Send a trace step
curl -X POST http://localhost:3000/api/ingest \
-H "Content-Type: application/json" \
-d '{"session_id":"my-session","session_name":"Test","agent_name":"Agent1","step_type":"llm_call","model":"gpt-4o","prompt":"Hello","response":"Hi there"}'
# End a session
curl -X POST "http://localhost:3000/api/ingest?action=end" \
-H "Content-Type: application/json" \
-d '{"session_id":"my-session","status":"completed"}'
# Get all live sessions
curl http://localhost:3000/api/ingest┌─────────────────────────────────────────────┐
│ AgentLens │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Proxy │ │ Recorder │ │ Storage │ │
│ │ (captures│→ │ (structs │→ │ (SQLite / │ │
│ │ calls) │ │ traces) │ │ JSON) │ │
│ └──────────┘ └──────────┘ └───────────┘ │
│ ↑ ↓ │
│ ┌──────────┐ ┌───────────┐ │
│ │ Your AI │ │ Web UI │ │
│ │ Agent │ │ (Timeline │ │
│ │ Code │ │ Replay │ │
│ └──────────┘ │ Inspector)│ │
│ └───────────┘ │
└─────────────────────────────────────────────┘
| Component | Technology |
|---|---|
| Frontend | Next.js 16 + React + TypeScript |
| Styling | Vanilla CSS (dark mode, glassmorphism) |
| Storage | SQLite + JSON |
| Fonts | Inter + JetBrains Mono |
| Provider | Models | Auto-Wrap | Cost Tracking |
|---|---|---|---|
| OpenAI | GPT-4o, GPT-4o-mini, o1, o3 | wrap_openai() |
✅ |
| Anthropic | Claude 4 Opus/Sonnet, Claude 3.5 | wrap_anthropic() |
✅ |
| Gemini 2.0/2.5 Flash/Pro | wrap_google() |
✅ | |
| Ollama | Llama 3, DeepSeek, Mistral, CodeLlama | wrap_ollama() |
✅ (free) |
| LiteLLM | Any provider via LiteLLM proxy | wrap_litellm() |
✅ |
| Custom | Any OpenAI-compatible API | Manual | ✅ (configurable) |
AgentLens pairs with MCPlex to create a complete agent toolkit:
- MCPlex = execution layer (routes, secures, caches MCP tools)
- AgentLens = observability layer (traces, debugs, replays, alerts)
Enable the bridge in MCPlex's mcplex.toml:
[agentlens]
enabled = true
url = "http://127.0.0.1:3000/api/ingest"
session_name = "MCPlex Gateway"Every tool call through MCPlex now appears as a traced step in AgentLens's timeline. Both tools work 100% independently — the bridge is opt-in.
AgentLens exposes an MCP server so IDE agents (Antigravity, Claude Code, Cursor, Windsurf) can query traces:
{
"mcpServers": {
"agentlens": {
"command": "node",
"args": ["path/to/agentlens/src/mcp-server-entry.mts"],
"env": { "AGENTLENS_URL": "http://127.0.0.1:3000" }
}
}
}Available tools:
| Tool | Description |
|---|---|
agentlens_list_sessions |
List recent sessions with cost/anomaly summary |
agentlens_get_session |
Full session with all steps |
agentlens_search_traces |
Cross-session search by text, agent, type |
agentlens_get_anomalies |
All detected anomalies |
agentlens_get_cost_summary |
Cost breakdown by agent/model/provider |
# Run AgentLens standalone
docker build -t agentlens .
docker run -p 3000:3000 agentlens
# Run AgentLens + MCPlex together
docker-compose up- Debug failing agents — See exactly where and why an agent went wrong
- Optimize costs — Find expensive agents and reduce token usage
- Detect loops — Catch infinite fix→test→fail cycles before they burn your budget
- Compare runs — Diff successful vs failed executions side-by-side
- Audit workflows — Full trace of every decision for compliance and review
- Demo & showcase — Beautiful UI for showing off your agent architecture
- Run comparison (diff view) ✅
- Export traces to JSON ✅
- Search & filter timeline ✅
- Keyboard shortcuts ✅
- OpenTelemetry export format ✅
- Budget alerts & cost projections ✅
- Live streaming simulation ✅
- Python SDK & REST API ✅
- Real-time trace streaming (SSE) ✅
- LangGraph / CrewAI / AutoGen framework adapters ✅
- Team collaboration (shared traces) ✅
- VS Code extension ✅
- npm package (
agentlens-sdk) ✅ - Anthropic (Claude) auto-tracing ✅
- Google (Gemini) auto-tracing ✅
- Ollama local LLM tracing ✅
- LiteLLM universal proxy tracing ✅
- Google ADK adapter ✅
- MCPlex integration bridge ✅
- MCP server for IDE agents ✅
- Cross-session search API ✅
- Docker & docker-compose ✅
- Async Python SDK (aiohttp) ✅
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT License. See LICENSE for details.
Built with ❤️ for the AI agent community
If this tool saved you from a $47 infinite loop, consider giving it a ⭐