ai-agent-profiler 0.3.0

Runtime profiler and optimization engine for AI agents using MCP

AgentLens

Runtime profiler and optimization engine for AI agents using MCP.

AgentLens sits between your agent and its tools — observing every MCP schema load, tool call, and LLM call, then using that history to automatically pre-select the minimal tool set for future runs. The result: 80–95% reduction in schema token overhead, zero code changes in the agent.

pip install agentlens

---

The Problem

Every agent connecting to an MCP server loads all tool schemas on every call — even tools it will never use. A 50-tool server dumps 8,000–15,000 tokens of schema into every LLM call. No existing observability tool (LangSmith, Arize, Helicone) measures or optimizes this.

The Solution

Before AgentLens                    After AgentLens
─────────────────                   ───────────────
Agent → 50 tool schemas             Agent → 6 tool schemas (snapshot)
        ↓ 12,000 tokens                     ↓ 800 tokens
        LLM picks 6 tools                   LLM calls correct tools
        Cost: $0.036/call                   Cost: $0.0024/call  (93% saving)

AgentLens profiles your agent, builds a snapshot of the tools it actually uses per task type, and on the next run pre-loads only those tools.

---

Installation

# Core
pip install agentlens

# With Postgres support
pip install "agentlens[postgres]"

# With LangChain support
pip install "agentlens[langchain]"

# With OpenAI support
pip install "agentlens[openai]"

# Everything
pip install "agentlens[postgres,langchain,openai]"

Requires Python 3.11+.

---

Quick Start

1. Wrap your Anthropic client (10 lines)

import anthropic
from agentlens import AgentLens

lens = AgentLens(store="sqlite:///agentlens.db")
await lens.init()

raw = anthropic.Anthropic()

async with lens.session(agent_id="my-agent", task_type="code-review") as sess:
    client = lens.wrap_anthropic(session=sess)
    # client records every call — token counts, cost, latency

2. Wrap your MCP client (zero code in the agent)

# Start AgentLens as a transparent proxy in front of your MCP server
agentlens proxy start --upstream "uvx mcp-server-filesystem /tmp"

# Your agent now points to this proxy instead of the real server
# All tool calls are profiled automatically

3. Build a snapshot after enough sessions

agentlens snapshot build code-review --min-sessions 5

4. Use the snapshot — agent loads only 6 tools instead of 50

agentlens proxy start --upstream "uvx mcp-server-filesystem /tmp" --task-type code-review

5. View your savings

agentlens stats show --last 7d
agentlens dashboard show        # live terminal UI

---

Architecture

┌────────────────────────────────────────────────────────┐
│                     Agent / LLM App                     │
└──────────────┬───────────────────────────┬─────────────┘
               │ SDK wrapper               │ MCP proxy
     ┌─────────▼──────────┐     ┌──────────▼──────────┐
     │   AgentLens SDK     │     │  AgentLens Proxy     │
     │  wrap_anthropic()   │     │  (zero code change)  │
     │  wrap_openai()      │     │  stdio / HTTP        │
     └─────────┬──────────┘     └──────────┬───────────┘
               └──────────────┬────────────┘
                              │
                   ┌──────────▼──────────┐
                   │   Profiler Engine    │
                   │  LensEvent stream    │
                   └──────────┬──────────┘
                              │
                   ┌──────────▼──────────┐
                   │    Profile Store     │
                   │  SQLite · Postgres   │
                   └──────────┬──────────┘
                              │
                   ┌──────────▼──────────┐
                   │  Snapshot System     │
                   │  build · export      │
                   │  import · predict    │
                   └──────────┬──────────┘
                              │
                   ┌──────────▼──────────┐
                   │  Optimization Engine │
                   │  pre-select tools    │
                   │  compress schemas    │
                   └─────────────────────┘

---

SDK Reference

AgentLens facade

from agentlens import AgentLens

lens = AgentLens(
    store="sqlite:///agentlens.db",  # or "postgresql://..."
    model="claude-sonnet-4-6",
)
await lens.init()

# Session context manager
async with lens.session(agent_id="my-agent", task_type="code-review") as sess:
    client = lens.wrap_anthropic(session=sess)   # Anthropic
    client = lens.wrap_openai(session=sess)       # OpenAI (pip install agentlens[openai])
    interceptor = lens.wrap_mcp(session=sess, source="my-mcp-server")

# Predictive task inference (v3)
task_type = await lens.classify_task(
    message="Please review this pull request",
    known_task_types=["code-review", "db-query", "deploy"],
)

Snapshot Registry (share snapshots across teams)

from agentlens.snapshot.registry import SnapshotRegistry

# Export
registry = SnapshotRegistry()
registry.add(snapshot)
registry.export("my_snapshots.json")

# Import
registry = SnapshotRegistry.import_from("my_snapshots.json")
snap = registry.get("code-review")

LangChain Integration

from agentlens.integrations.langchain import LangChainLensCallback

cb = LangChainLensCallback(store=store, session_id="my-session")
chain.invoke({"input": "..."}, config={"callbacks": [cb]})

---

CLI Reference

# Traces
agentlens trace show <session-id>

# Stats
agentlens stats show --last 7d

# Snapshots
agentlens snapshot build <task-type> --min-sessions 5
agentlens snapshot list
agentlens snapshot export <task-type> snapshots.json
agentlens snapshot import snapshots.json

# MCP Proxy
agentlens proxy start --upstream "uvx mcp-server-filesystem /tmp"
agentlens proxy start --upstream "..." --task-type code-review --port 3100

# Dashboard
agentlens dashboard show --refresh 2

---

Competitive Landscape

Tool	Observability	Token cost	MCP-aware	Snapshot optimization	Predictive inference
LangSmith	✅	Partial	❌	❌	❌
Arize Phoenix	✅	Partial	❌	❌	❌
Helicone	Partial	✅	❌	❌	❌
AgentLens	✅	✅	✅	✅	✅

---

Roadmap

Version	Status	What shipped
v1 (0.1.0)	✅	Profiler engine, LensEvent, SQLiteStore, Anthropic + MCP integrations, CLI basics
v2 (0.2.0)	✅	MCP proxy server, SnapshotStore, PostgresStore, LangChain integration, live dashboard
v3 (0.3.0)	✅	Predictive task inference, SnapshotRegistry, OpenAI integration, PyPI publish

---

License

MIT