How to Debug Multi-Agent AI Systems Using AgentLens (2026 Guide)

The Problem AgentLens Solves

Building a single-prompt LLM application is relatively straightforward, but as soon as you move into the territory of multi-agent systems—where agents spawn sub-agents, call external tools, and hand off tasks to one another—visibility vanishes. Most existing observability tools focus on linear LLM call tracking, which fails to capture the branching logic and decision trees inherent in agentic workflows. When an agent fails, developers often struggle to identify whether the breakdown happened during a tool call, a logic handoff, or a recursive loop.

Engineers currently face a difficult choice: use expensive, cloud-only proprietary platforms that raise data privacy concerns, or use generic logging tools that do not understand agent-specific structures. These generic tools often flatten the hierarchy, making it nearly impossible to reconstruct the "why" behind an agent's specific path. The complexity increases when you factor in token costs across multiple models and the need for real-time feedback during the development cycle.

AgentLens fixes this by treating the agent run as a topology rather than a list. It ingests data via OpenTelemetry (OTel) and renders it as an interactive DAG, allowing you to see the exact moment an agent decided to spawn a sub-task or call a specific function. By providing a self-hosted, MIT-licensed solution, it ensures that sensitive execution data stays within your infrastructure while offering features like time-travel replay and side-by-side trace comparisons.

In this tutorial, you'll learn exactly how to use AgentLens — step by step.

How to Get Started with AgentLens in 5 Minutes

1. Launch the Backend: Use Docker to run the AgentLens observer container on your local machine or server using docker run -p 3000:3000 tranhoangtu/agentlens-observe:0.6.0.
2. Install the SDK: Add the observability client to your Python environment by running pip install agentlens-observe in your terminal.
3. Configure Your Framework: Initialize AgentLens in your code by pointing it to your local host (default: http://localhost:3000) and wrapping your agent tasks.
4. Run an Agent Task: Execute a multi-agent workflow using supported frameworks like CrewAI or AutoGen to begin sending telemetry data to the dashboard.
5. Open the Dashboard: Navigate to your browser and access the interactive UI to see your agent's execution nodes appear in real-time via the streaming interface.

How to Use AgentLens: Complete Tutorial

Step 1: Setting Up the Self-Hosted Environment

AgentLens is built on a modern stack comprising React 19 for the frontend and FastAPI for the backend. Because it is self-hosted, your first step is deciding on your storage engine. For local development, the default SQLite setup is sufficient, but for production-grade tracking, you should configure it to use PostgreSQL. Start the system using the provided Docker image, ensuring port 3000 is mapped correctly. This container handles the OTLP HTTP JSON ingestion, meaning it can receive data from any application instrumented with OpenTelemetry standard protocols.

Step 2: Instrumenting Your Multi-Agent Workflow

Once the backend is running, you need to instrument your code. AgentLens provides direct compatibility with popular frameworks like LangChain, CrewAI, and LlamaIndex. You will use the agentlens-observe library to wrap your agent's execution loop. This instrumentation captures not just the text input and output, but the "spans" that represent internal logic. When an agent in CrewAI delegates a task, AgentLens captures that delegation as a child node in the trace, preserving the parent-child relationship that is often lost in flat logging systems.

Step 3: Visualizing Agent Topology and Tool Calls

The core of AgentLens is the interactive topology graph. Unlike a standard table of logs, the DAG (Directed Acyclic Graph) view shows you the flow of information. You can click on individual nodes to see the specific tool calls made, the arguments passed to those tools, and the raw LLM responses. This is particularly useful for debugging "hallucination loops" where an agent might be stuck repeatedly calling a tool with the same incorrect parameters. The visualization makes these circular dependencies immediately obvious.

Step 4: Using Time-Travel Replay and Trace Comparison

One of the most powerful features of AgentLens is the time-travel replay. If an agent run took five minutes and eventually failed, you can use the scrubber timeline to step through the execution frame-by-frame. This allows you to see the exact state of the agent's memory at any given second. Furthermore, if you have a "good" run and a "bad" run, use the Side-by-Side Trace Comparison tool. It provides a color-coded diff of the two spans, highlighting where the logic diverged, which is essential for regression testing when updating prompts or switching models.

AgentLens: Pros & Cons

Pros	Cons
Self-hosted architecture ensures total data privacy and security.	Currently in early-stage development (v0.6.0), which may mean occasional bugs.
MIT licensed and fully open-source with 100% test coverage.	Requires manual infrastructure setup and Docker management.
Specialized topology visualization for sub-agent spawns and handoffs.	Niche focus might feel restrictive for simple, single-prompt apps.
Real-time streaming via SSE provides immediate debugging feedback.	Documentation is still evolving alongside the rapid release cycle.
Cost tracking for 27+ models helps monitor multi-model overhead.	Limited built-in collaboration features compared to enterprise cloud tools.

AgentLens Pricing: Free vs Paid

AgentLens is fundamentally an open-source project released under the MIT License. This means that the core software is completely free to use, modify, and distribute. There are no hidden tiers, usage limits, or "paywalls" for basic features like the number of traces or the number of agents tracked. Because you host it yourself, your only costs are the underlying compute and storage resources (such as your own AWS, GCP, or local server costs).

The developer, Tran Hoang Tu, has focused on making the tool accessible to the community. By opting for a self-hosted model, AgentLens removes the "data tax" often associated with observability platforms where you pay per span or per gigabyte of ingested data. For teams concerned about privacy or working in regulated industries, this free, open-source approach provides an enterprise-level feature set without the enterprise price tag.

👉 Check the latest updates and repository status on the official AgentLens GitHub page.

Who is AgentLens BEST FOR?

For DevOps and Security Engineers: AgentLens is an ideal choice if you work in an environment where sending LLM traces to a third-party cloud is prohibited. Since it is self-hosted and open-source, you maintain absolute control over the execution data and can audit the code to ensure it meets internal compliance standards.

For AI Application Developers: If you are building complex systems using CrewAI, AutoGen, or LangChain, this tool provides the specific topological insights you need. It is particularly valuable when your architecture relies on multiple agents passing context back and forth, as it allows you to visualize the handoff logic clearly.

For Budget-Conscious Startups: Teams that are scaling their AI features but want to avoid the high monthly fees of proprietary observability platforms will find AgentLens perfect. The built-in cost tracking for over 27 models allows you to monitor token usage without having to build custom monitoring dashboards from scratch.

Alternatives to AgentLens

LangSmith: A comprehensive, cloud-based platform by the LangChain team that offers deep testing and monitoring but can be expensive and lacks a self-hosted open-source version. Langfuse: A popular open-source alternative that focuses heavily on LLM call tracking and analytics but doesn't emphasize agent topology and sub-agent spawns as much as AgentLens. Arize Phoenix: An observability tool that excels in data science metrics and embedding visualization but may feel overly complex for developers who just want to debug agent logic flows. While these tools are powerful, AgentLens remains the better choice for developers who specifically need to visualize the complex "tree" of agent handoffs in a lightweight, self-hosted package.

Final Verdict: Is AgentLens Worth It?

AgentLens is a highly specialized and effective tool for developers who have outgrown simple logging and need to understand the structural behavior of their AI agents. Its commitment to the MIT license and 100% test coverage makes it a reliable addition to a modern AI development stack, especially for those prioritizing data privacy.

📋 Disclosure: This is an independent tutorial based on AgentLens's publicly available documentation and website content as of March 1, 2026. AI Wikis is not affiliated with, sponsored by, or endorsed by AgentLens or news.ycombinator.com. Pricing and features may have changed — always verify on the official AgentLens website.