AgentLens

MCP-native, hybrid RAG built-in, every step observable — a lightweight Python Agent framework.

pip install agentlens-framework
agentlens init && agentlens run          # 30 lines, zero API key needed

---

Architecture

User Query ──> ReAct Agent ──> LLM (OpenAI / Anthropic / DemoLLM)
                    │
         ┌──────────┼──────────┐
      Tools       Memory    Observatory
         │           │           │
    MCP Client   Conversation  Trace + Cost + Dashboard
         │
    RAG Engine (BM25 + Dense + Cross-encoder Rerank)

• DemoLLM and MockEmbedder replace all real API calls — the entire framework runs without any API key
• MCP is a first-class citizen: MCPToolClient auto-connects and wraps remote tools
• Every step is traced (OpenTelemetry-compatible) and cost-tracked in real time

---

Quick Start (30 lines)

from agentlens import SyncReActAgent, DemoLLM, tool, ConversationMemory, ApprovalPolicy
import os

@tool(description="Search the web")
async def search(query: str) -> str:
    return f"Results for '{query}': AgentLens is a lightweight Agent framework..."

@tool(description="Read a local file")
async def read_file(path: str) -> str:
    try:
        return open(path, encoding="utf-8").read()[:2000]
    except FileNotFoundError:
        return f"[Error] File not found: {path}"

# Auto-detect API key, fall back to DemoLLM
if os.environ.get("OPENAI_API_KEY"):
    from agentlens import OpenAILLM; llm = OpenAILLM(model="gpt-4o-mini")
else:
    llm = DemoLLM()

agent = SyncReActAgent(
    llm=llm, tools=[search, read_file],
    memory=ConversationMemory(), approval=ApprovalPolicy.AUTO_APPROVE,
)

for step in agent.run("Analyze README.md and search for related info"):
    print(f"[{step.step_number}] {step.thought}")
    if step.action: print(f"  Action: {step.action}({step.action_input})")
    print(f"  {step.latency_ms:.0f}ms | {step.token_usage} tokens\n")

Run it:

python -m agentlens.demo          # zero-dependency demo mode
AGENTLENS_LIVE=1 python -m agentlens.demo   # use real LLM (needs API key)

---

Comparison

AgentLens doesn't aim to be "better" — it aims to be different: smaller, faster to start, more transparent.

	AgentLens	LangChain	LlamaIndex
Positioning	Lightweight Agent framework	General LLM orchestration	Data indexing framework
Lines to first Agent	~30	~100	~80
MCP-native	Yes	Plugin	No
Built-in hybrid RAG	BM25 + Dense + Rerank	No	Yes
Zero-API-key demo	DemoLLM + MockEmbedder	No	No
Observability	Trace + Cost + Dashboard	Callbacks	Instrumentation
Best for	Small-medium Agent projects, demos	Complex multi-step pipelines	Document Q&A

---

Key Features

ReAct Agent

from agentlens import SyncReActAgent, OpenAILLM, tool

agent = SyncReActAgent(llm=OpenAILLM(model="gpt-4o-mini"), tools=[...])
for step in agent.run("your task"):
    print(step.thought, step.action, step.observation)

MCP Tool Client

from agentlens import MCPToolClient

async with MCPToolClient("http://localhost:8000") as client:
    tools = await client.list_tools()
    agent = SyncReActAgent(llm=llm, tools=tools)

Hybrid RAG

agentlens rag index ./docs/ --output ./index/ --embedder mock
agentlens rag search "Python machine learning" --index ./index/
agentlens rag eval --queries queries.jsonl --index ./index/

Observatory & Dashboard

from agentlens import Observatory, ReActAgent

obs = Observatory(tracer=True, cost_tracking=True)
agent = ReActAgent(llm=llm, tools=tools, observatory=obs)
# ...run agent...
print(obs.cost_report())        # token + cost by model
obs.export_traces("trace.json") # full trace export

agentlens serve --port 8848     # Dashboard at http://localhost:8848
agentlens trace list            # list all traces
agentlens trace replay <id>     # step-by-step replay

Custom Tools

from agentlens import tool, ToolBase

@tool(description="Get weather for a city")
async def get_weather(city: str, unit: str = "celsius") -> str:
    return f"{city}: 25C, sunny"

# Or use Pydantic validation
class SearchTool(ToolBase):
    name = "web_search"
    description = "Search the internet"
    class Input(BaseModel):
        query: str
        max_results: int = 5
    async def execute(self, query: str, max_results: int = 5) -> str: ...

Error Handling

from agentlens import ErrorStrategy, RetryConfig

agent = SyncReActAgent(
    llm=llm, tools=tools,
    retry_config=RetryConfig(max_retries=3, backoff_factor=2.0),
    on_error=ErrorStrategy.RETURN_PARTIAL,  # RETRY_THEN_FAIL | SKIP_AND_CONTINUE
)

---

Installation

# Minimal install (Agent + Tools + Memory)
pip install agentlens-framework

# With RAG engine
pip install agentlens-framework[rag]

# With Dashboard + Tracing
pip install agentlens-framework[observatory]

# Everything
pip install agentlens-framework[all]

---

Project Structure

agentlens/
├── core/
│   ├── agent/          # Agent protocol + ReAct implementation
│   ├── llm/            # LLM protocol + adapters (OpenAI, Anthropic, Demo)
│   ├── tools/          # @tool decorator, ToolBase, MCP client
│   ├── memory/         # ConversationMemory, WorkingMemory
│   └── trace/          # Trace/Span models, TraceCollector, TraceStore
├── rag/
│   ├── loader/         # Multi-format document loader (.txt, .md, .pdf, .html)
│   ├── chunker/        # Fixed / recursive / semantic chunking
│   ├── embedder/       # OpenAI API embedder + MockEmbedder
│   ├── retriever/      # BM25 + Dense hybrid retrieval
│   └── query/          # Query rewrite, HyDE, decomposition
├── observatory/
│   ├── facade.py       # Unified Observatory entry point
│   ├── cost.py         # Real-time token counting + cost calculation
│   ├── eval.py         # MRR / NDCG / Recall / Precision
│   └── dashboard/      # FastAPI + Tailwind dashboard
├── cli.py              # Unified CLI: init, run, serve, rag, trace
├── demo.py             # Zero-dependency demo (python -m agentlens.demo)
└── _version.py         # Single source of version truth

---

Roadmap

• ReAct Agent with MCP support
• Hybrid RAG (BM25 + Dense + Rerank)
• Observatory (Trace + Cost + Dashboard)
• Zero-API-key demo mode
• CLI and evaluation tools
• Multi-agent orchestration
• Streaming SSE dashboard
• Langfuse / Weights & Biases integration

---

MIT License. Built to showcase what a production-ready Agent framework looks like in Python.