Getting Started

Set up AgentLens from scratch in under 10 minutes.

Prerequisites

1. Clone the Repository

git clone https://github.com/sauravbhattacharya001/agentlens.git
cd agentlens

2. Start the Backend

cd backend
npm install
node server.js

The backend starts on http://localhost:3000 by default. You can override the port with the PORT environment variable:

PORT=8080 node server.js

Load Demo Data (Optional)

node seed.js

This creates sample sessions and events so you can explore the dashboard immediately.

3. Install the Python SDK

cd ../sdk
pip install -e .

This installs the SDK in development (editable) mode. For production, you can install from the directory:

pip install ./sdk

Dependencies

The SDK depends on:

• pydantic ≥2.0 — Data validation and serialization
• httpx ≥0.24 — Async-capable HTTP client

4. Instrument Your Agent

import agentlens

# Connect to the backend
agentlens.init(api_key="your-key", endpoint="http://localhost:3000")

# Start a tracking session
session = agentlens.start_session(agent_name="my-agent")

# Track an LLM call
agentlens.track(
    event_type="llm_call",
    input_data={"prompt": "What is 2+2?"},
    output_data={"response": "4"},
    model="gpt-4",
    tokens_in=12,
    tokens_out=3,
    reasoning="Simple arithmetic — answered directly",
)

# Get a human-readable explanation
print(agentlens.explain())

# End the session (flushes pending events)
agentlens.end_session()

5. Run the Demo

cd sdk/examples
python mock_agent.py

The demo runs two mock agents (a research agent and a code agent) that simulate realistic workflows with LLM calls, tool invocations, and decision traces. Open http://localhost:3000 to see the results in the dashboard.

6. View the Dashboard

Open http://localhost:3000 in your browser. The dashboard is served directly by the backend — no separate build step required.

You'll see:

• Sessions list — All agent sessions with status, agent name, and token counts
• Timeline view — Click a session to see every event on an interactive timeline
• Token charts — Per-event and cumulative token usage
• Explain tab — Auto-generated human-readable behavior summaries

Next Steps