AgentLens
Local-first AI agent debugger with fork & replay.
AgentLens captures execution traces from multi-step AI agent workflows, visualizes them in a local web UI, and lets you fork a trace at any step, edit its output, and re-execute downstream steps with real API calls to see what would have happened differently.
Think of it as Chrome DevTools for AI agents — the Network tab + time-travel debugging, but for LLM agent workflows.
Install:
pip install agentlens-xray— the import name isagentlens.
Demo
https://github.com/user-attachments/assets/416a853c-4915-4a30-8590-f50fd0a7dc47
The Problem
AI agents are non-deterministic. When a multi-step agent fails at step 7 of 12, developers currently have no way to:
- See exactly what happened at each step (tool calls, LLM reasoning, intermediate state)
- Reproduce the failure deterministically
- Test a fix by replaying from the failure point without re-running the entire chain
Quick Start
pip install agentlens-xray
python examples/basic_agent.py # creates a sample trace (no API keys needed)
agentlens serve # opens the UI at localhost:7600
For a real agent with OpenAI:
export OPENAI_API_KEY="sk-..."
python examples/trip_planner_agent.py
agentlens serve
Usage
1. Instrument Your Code
Add decorators to your existing agent functions — zero logic changes:
import agentlens
@agentlens.trace(name="my_agent")
async def my_agent(query: str):
data = await fetch_data(query)
result = await analyze(data)
return result
@agentlens.wrap_tool(name="fetch_data")
async def fetch_data(query: str) -> dict:
return await api.search(query)
@agentlens.wrap_llm(name="analyze", model="gpt-4o-mini")
async def analyze(data: dict) -> str:
response = await openai.chat.completions.create(...)
return response.choices[0].message.content
There's also a context manager API:
async with agentlens.start_trace_async("my_agent") as t:
with t.span("fetch_data", kind="tool") as s:
data = await fetch(...)
s.record_output(data)
with t.span("analyze", kind="llm", model="gpt-4o") as s:
s.record_input({"messages": [...]})
result = await llm.complete(...)
s.record_output(result)
2. View Traces
agentlens serve # Web UI at localhost:7600
agentlens serve --port 8080 # Custom port
agentlens traces # List recent traces in terminal
agentlens traces --last 5 # Show last 5
3. Fork & Replay
In the web UI:
- Click a trace to see its span timeline
- Select a span and click Fork & Replay
- Edit the span's output in the code editor
- Choose a replay mode
- Click Replay from here to create a forked trace
- View the side-by-side comparison with diff highlighting
Replay Modes
| Mode | What happens | Cost | Use case |
|---|---|---|---|
| Deterministic | Only the edited span changes. Downstream spans are marked stale. | Free | Quick data annotation, bookmarking bugs |
| Live | All downstream spans re-execute with real API calls. | Token costs | "What would the LLM say if the tool returned different data?" |
| Hybrid | LLM spans re-execute live, tool spans return recorded data. | Lower token costs | Test LLM behavior with changed context, no tool side effects |
Example: Your weather tool returned "sunny" but the real weather is a blizzard. Fork the weather span, change it to blizzard, select Live mode. The LLM re-generates the itinerary accounting for severe weather — with real API calls, producing genuinely different output.
Framework Integrations
AgentLens works with popular frameworks out of the box — no decorators needed.
OpenAI / Anthropic SDK (wrap your client)
pip install agentlens-xray[openai] # or agentlens-xray[anthropic]
from openai import OpenAI
from agentlens import wrap_openai
client = wrap_openai(OpenAI())
# All chat.completions.create() calls are now traced automatically
response = client.chat.completions.create(model="gpt-4o", messages=[...])
LangChain / LangGraph
pip install agentlens-xray[langchain]
from agentlens.integrations.langchain import AgentLensCallbackHandler
with AgentLensCallbackHandler(trace_name="my_agent") as handler:
chain.invoke(input, config={"callbacks": [handler]})
# Full trace with LLM, tool, retrieval, and chain spans
OpenAI Agents SDK
pip install agentlens-xray[openai-agents]
from agentlens.integrations.openai_agents import install_agentlens_tracing
install_agentlens_tracing() # One line — all agent runs traced automatically
result = await Runner.run(agent, input="Process this refund")
CrewAI
pip install agentlens-xray[crewai]
from agentlens.integrations.crewai import CrewAIHandler
handler = CrewAIHandler(trace_name="my_crew")
crew = Crew(agents=[...], tasks=[...], callbacks=[handler])
crew.kickoff() # Crew, agent, and task spans captured
Features
- Zero-config tracing —
pip install agentlens-xrayand add decorators or use framework integrations - Framework integrations — LangChain, LangGraph, OpenAI Agents SDK, CrewAI, raw SDKs
- Live replay — re-execute downstream spans with real API calls after editing a span's output
- Hybrid replay — LLM calls go live, tool calls use recorded data (no side effects)
- Async-first — non-blocking trace capture, works in both sync and async code
- Local-first — no cloud accounts, no telemetry, everything stays on your machine
- Keyboard navigable — arrow keys / j/k to browse spans,
eto edit
Architecture
Your Agent Code
--> @trace, @wrap_tool, @wrap_llm decorators capture spans
--> Async queue --> SQLite (./.agentlens/traces.db)
--> FastAPI serves JSON API + bundled React frontend
--> localhost:7600
Fork & Replay (Live mode):
--> Load original trace, apply mutations
--> Re-import user's function, set ReplayContext
--> Decorators intercept each span:
Before mutation: execute normally
At mutation: return edited output
After mutation: execute live (real API calls)
--> Save new trace for side-by-side comparison
Web UI Pages
- Trace List — all captured traces with status, duration, token count, cost
- Trace Detail — span timeline (left) + selected span I/O (right), keyboard navigable
- Replay Comparison — side-by-side original vs forked trace, with RE-EXECUTED / EDITED / STALE badges
Configuration
| Variable | Default | Description |
|---|---|---|
AGENTLENS_DB_PATH |
./.agentlens/traces.db |
SQLite database path (project-local by default) |
AGENTLENS_PORT |
7600 |
Default server port |
AGENTLENS_ENABLED |
true |
Set false to disable tracing (decorators become no-ops) |
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Frontend development (hot reload)
cd frontend && npm install && npm run dev
# Build frontend for production
cd frontend && npm run build
# Run tests
pytest
# Type checking
mypy src/agentlens
cd frontend && npx tsc --noEmit
Project Structure
src/agentlens/
sdk/ # Tracing SDK (decorators, context management, SQLite writer)
server/ # FastAPI API + static file serving
replay/
engine.py # Replay dispatcher (deterministic vs live)
live.py # Live replay engine (re-executes user functions)
context.py # ReplayContext (decorators check this at runtime)
cli.py # CLI entry point
frontend/ # React + TypeScript + Tailwind UI (Vite)
examples/ # Working examples (basic + OpenAI trip planner)
Tech Stack
- SDK: Python 3.10+, Pydantic v2, aiosqlite, contextvars
- Server: FastAPI, Uvicorn
- Frontend: React 18, TypeScript, Tailwind CSS, CodeMirror, Vite
- Storage: SQLite (WAL mode, zero-config)
License
MIT
Metadata
Release files for agentlens-xray 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentlens_xray-0.3.2.tar.gz | 18.1 MB | Without provenance | Details for agentlens_xray-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentlens_xray-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for agentlens_xray-0.3.2-py3-none-any.whl |
Total release size: 18.6 MB
Release files / agentlens_xray-0.3.2.tar.gz
| Download URL | agentlens_xray-0.3.2.tar.gz |
|---|---|
| Size | 18.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0263f532c9cd8dbcae86546effebae934848f0d2bdf9544c33ca2c610b2a505
|
|
BLAKE2b-256 checksum How to use checksums |
e234f3ccfa0b5cfc436da349f0a4d19c0849915be2a1e65069183e0e0728e15d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / agentlens_xray-0.3.2-py3-none-any.whl
| Download URL | agentlens_xray-0.3.2-py3-none-any.whl |
|---|---|
| Size | 500.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4953564a02fab2b0fa6fa32c13a615ad3c4ac9dd673bced6568d6340d38d3b9d
|
|
BLAKE2b-256 checksum How to use checksums |
05980fb2645873dad64972545bbf1cbe9ab22754ef8ad01c2b84c39a0b8dafd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for agentlens-xray 0.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.