agentlens

See what your AI agent actually did, one span at a time

Wrap your agent in @trace and its steps in span(...). AgentLens records LLM calls, tool calls, retrieval and handoffs — with timings, tokens and exceptions — to a local SQLite file, then shows them in a dashboard that never leaves your

1
stars
0
forks
0
open issues
MIT
licence

What it does

AgentLens is a Python tracing library plus a local dashboard for AI agent code. You mark an agent run with a `@trace` decorator/context manager and individual steps with `span(...)`, and the library records a nested tree of spans (agent, llm, tool, retrieval, workflow, custom) with timings, inputs, outputs, metadata, model names, token counts and exceptions. Traces are written to a local SQLite file (`~/.agentlens/traces.db` by default), and a read-only FastAPI server bundled with a prebuilt React dashboard renders a run list, waterfall timeline and span inspector, launched via `agentlens ui`. A LlamaIndex integration hooks that framework's instrumentation dispatcher to capture spans automatically.

When an agent run plans, calls several tools (some concurrently), hands off to a sub-agent, retries a failure and then answers, print statements and flat logs do not show which step was slow or wrong. Existing hosted observability services require an account and send prompts and user data over the network. AgentLens gives a nested, timed view of the run stored only on the developer's own machine.

Key features

  • Decorator and context-manager tracing API (`@trace`, `span`, `current_span`)

    README "The API" section and the examples both use `@trace` plus `with span(...)`.

  • Correct nesting for async and concurrent work via contextvars

    examples/async_agent.py traces `asyncio.gather` fetches; the docstring states context is tracked with contextvars.

  • Local SQLite storage with no network egress

    README "Local-first and private" section names the default DB path and the `AGENTLENS_DB` override.

  • Bundled web dashboard served by FastAPI, shipped prebuilt in the wheel

    fastapi/uvicorn are runtime dependencies; the release workflow asserts the wheel contains the built dashboard.

  • CLI with ui/demo/list/clear commands

    pyproject declares the `agentlens` console script; README documents the subcommands.

  • Payload capture control and redaction hook applied before disk writes

    README shows `agentlens.configure(capture_io=False, redactor=...)` and env vars; CHANGELOG lists `redact_keys()`.

  • LlamaIndex auto-instrumentation as an optional extra

    `llamaindex = ["llama-index-core>=0.11"]` extra in pyproject and a runnable example using MockLLM/MockEmbedding.

  • Cross-platform, multi-version CI with lint, format, type checks and a dashboard staleness gate

    .github/workflows/ci.yml matrix covers Python 3.9–3.13 plus macOS/Windows, and runs ruff, mypy and a frontend build diff check.

  • Pluggable storage interface behind the tracing API

    README "How it works" describes an abstract Storage interface with a SQLite implementation; CHANGELOG repeats it.

Use cases

  • Debugging a hand-written Python agent

    Add `@trace` to the agent entrypoint and `span(...)` around tool and LLM calls, then run `agentlens ui` to inspect the execution tree, per-step durations and payloads.

  • Diagnosing latency in concurrent async agents

    Trace an `async def` agent that runs several fetches under `asyncio.gather`; the waterfall view shows overlapping bars so you can see which concurrent branch dominated total run time.

  • Automatic tracing of LlamaIndex pipelines

    Call `instrument()` from `agentlens.integrations.llamaindex` so query engines, retrievers, LLMs, embeddings and workflows are recorded as spans without adding manual instrumentation.

  • Tracing with sensitive payloads suppressed

    Set `capture_io=False` or supply a redactor callable (or the `AGENTLENS_CAPTURE_IO` / `AGENTLENS_DISABLED` env vars) to keep timings and token counts while dropping or filtering prompts and documents before they're written.

  • Inspecting a failed run

    Open the span inspector to find the exact failing span, with its exception type, message and traceback attached, rather than scanning interleaved logs.

Who it's for

  • Python developers building custom LLM agents without a framework
  • LlamaIndex users debugging RAG and agent workflows
  • Engineers who cannot send prompts or user data to a hosted observability service
  • Developers profiling latency in async/concurrent agent code

What makes it different

  • Traces stay on disk in SQLite with no account, server or telemetry, and the dashboard binds to 127.0.0.1 by default.
  • The dashboard is committed prebuilt into the wheel, so users need no Node toolchain; CI fails if the committed build is stale.
  • The core tracing API is framework-agnostic — integrations are built on the same public SDK, with LlamaIndex as the first one.
  • Privacy controls are first-class: a redactor callable runs before anything is written, plus env vars to disable tracing or payload capture in CI/shared machines.

More

When an agent plans, calls several tools (some concurrently), hands off to a sub-agent, retries a failure, and finally answers, print statements and flat logs don't tell you which step was slow or wrong. AgentLens instruments your Python agent code with a @trace decorator/context manager and a span() call around individual steps, capturing a nested tree of spans — agent, llm, tool, retrieval, workflow, custom — with timings, inputs, outputs, metadata, model names, token counts and exceptions.

Everything is written to a local SQLite file (~/.agentlens/traces.db by default). A read-only FastAPI server with a prebuilt React dashboard, launched with agentlens ui, renders a run list, waterfall timeline and span inspector — no Node toolchain required to install it, and the dashboard binds to 127.0.0.1 by default. Context is tracked with contextvars, so nesting stays correct across await points and asyncio.gather, which makes it useful for diagnosing which branch of a concurrent run actually dominated the latency.

For LlamaIndex users, calling instrument() from agentlens.integrations.llamaindex hooks the framework's instrumentation dispatcher so retrievers, embeddings, LLM calls and workflow steps are captured automatically, with no manual spans. Privacy controls are built into the core API: set capture_io=False, supply a redactor callable, or use the AGENTLENS_CAPTURE_IO / AGENTLENS_DISABLED env vars to keep timings and token counts while dropping or filtering prompts and documents before they ever touch disk.

The project is early-stage — a single-maintainer, EARLY-maturity project with CI across Python 3.9–3.13 on Linux, macOS and Windows, but no published adoption numbers, no performance benchmarks, and no OpenTelemetry export yet (it's listed only on the roadmap). It targets a single developer's machine, not a multi-user or production-scale deployment.

Contributing

Contributions are welcome — see the contributing guide in the repository.

Links

Analysed by Orviqa. Grade your own README, free