Skip to main content
AgentDbg is a local-first step-through debugger for AI agents. Add @trace to your agent function, run it, then open the timeline UI to see exactly what happened: every LLM call, tool call, state update, error, and loop warning—all on your machine, with no data ever leaving.

Quick Start

Install AgentDbg and trace your first agent run in under 5 minutes.

SDK Reference

Explore @trace, traced_run, and all recording functions.

Integrations

Auto-instrument LangChain, OpenAI Agents SDK, and CrewAI agents.

Guardrails

Stop runaway agents with built-in loop detection and usage limits.

​
What AgentDbg does

When you wrap your agent with @trace, AgentDbg automatically records every event and writes it to a structured local file. Run agentdbg view to open a live timeline in your browser showing every step—inputs, outputs, timing, and failure evidence.

Timeline Viewer

Inspect runs with filter chips, expandable events, and live refresh.

CLI Commands

Use agentdbg list, view, and export to manage your runs.

Configuration

Control data directory, redaction, guardrails, and loop detection.

Trace Format

Understand the run.json and events.jsonl storage layout.

​
How it works

1

Install

pip install agentdbg
2

Instrument your agent

from agentdbg import trace, record_llm_call, record_tool_call

@trace
def run_agent():
    record_tool_call(name="search", args={"q": "users"}, result={"count": 42})
    record_llm_call(model="gpt-4", prompt="Summarize results", response="42 users.")
3

Open the timeline

agentdbg view
A browser tab opens at http://127.0.0.1:8712 showing the full run timeline.
AgentDbg is a development-time tool. All data is stored as plain files on your machine under ~/.agentdbg/runs/. No data is sent to any server.