AgentDbg
AgentDbg is a local-first debugger for AI agents. It captures structured traces (LLM calls, tool calls, state, errors) and gives you a timeline UI to inspect what happened-inputs, outputs, latency, and loop warnings.
What it is: A developer tool to instrument your agent, run it, and see a full event timeline locally. No cloud, no accounts.
What it is not: It is not observability or production monitoring. It does not do deterministic replay (planned for a later version), and it does not lock you into any framework.
In 60 seconds
1. Install:
pip install agentdbg
Or from source:
git clone https://github.com/AgentDbg/AgentDbg.git
cd AgentDbg/agentdbg
uv sync
2. Run the example agent:
python examples/minimal/simple_agent.py
3. Open the timeline viewer:
agentdbg view
A browser tab opens showing every event in the run - tool calls, LLM calls, timing. Data is stored locally under ~/.agentdbg/runs/<run_id>/.
Demos and examples
| Example | Path | How to run |
|---|---|---|
| Minimal agent (pure Python) | examples/minimal/ |
python examples/minimal/simple_agent.py |
| LangChain minimal | examples/langchain/minimal.py |
uv run --extra langchain python examples/langchain/minimal.py |
| OpenAI Agents minimal | examples/openai_agents/minimal.py |
uv run --extra openai python examples/openai_agents/minimal.py |
| LangChain customer support (advanced) | examples/langchain/ |
Set API keys, then follow _customer_support/README.md |
| Demos (short scripts) | examples/demo/ |
python examples/demo/pure_python.py or python examples/demo/langchain.py |
After any run, open the timeline with agentdbg view.
Documentation
| Page | Description |
|---|---|
| Getting started | Installation (uv/pip), quickstart, data dir, redaction |
| Guardrails | Stop runaway runs with loop, count, and duration limits |
| Regression testing | Baseline, assert, and diff workflow for catching agent regressions |
| CLI | list, view, export, baseline, assert, diff with options and exit codes |
| Viewer | Timeline UI usage, URL params, live refresh, and development |
| SDK | @trace, traced_run, has_active_run, record_llm_call, record_tool_call, record_state |
| Integrations | LangChain handler, OpenAI Agents adapter, and planned adapters |
| Architecture | Event schema, storage layout, viewer API, loop detection |
| Reference | |
| Trace format | Event envelope, event types, payload schemas, run.json (public contract) |
| Configuration | Env vars, YAML precedence, redaction, truncation, loop detection, guardrails |
| Policy YAML | Assertion policy file format, fields, threshold semantics, CLI mapping |