What problems AgentDbg solves
Debugging AI agents is hard because standard tools don’t give you visibility into the sequence of decisions an agent makes. A single run might trigger dozens of LLM calls, multiple tool calls, and several state transitions before something goes wrong—and a stack trace at the end tells you almost nothing about why it happened. AgentDbg gives you a chronological, event-by-event view of every run. You can jump to the first error, filter to just LLM calls, inspect every prompt and response, and see exactly which tool arguments produced which result. When an agent starts looping—calling the same tool repeatedly with the same arguments—AgentDbg detects the pattern and surfaces it as a warning before it spirals into a budget burn.Key features
Full execution timeline
Every run produces a chronological event log: run start, LLM calls, tool calls, state updates, errors, and loop warnings—all with inputs, outputs, and timing.
Local browser UI
Run
agentdbg view to open a live timeline in your browser at http://127.0.0.1:8712. Filter by event type, expand any event, and jump directly to errors or loop warnings.Loop detection and guardrails
AgentDbg automatically detects repeated tool call patterns and fires a warning. You can also set hard limits on LLM calls, tool calls, total events, and run duration to stop runaway agents before they burn your budget.
Framework-agnostic
Works with any Python agent code. Optional integrations for LangChain, OpenAI Agents SDK, and CrewAI auto-record events without manual instrumentation.
Redaction by default
Sensitive values—
api_key, token, authorization, password, and others—are scrubbed before writing to disk. Large fields are truncated automatically.Live refresh
Leave
agentdbg view running while you iterate. New runs appear in the sidebar automatically, and events stream in real time for runs still in progress.What gets captured
When you decorate your agent function with@trace and call the recording helpers, AgentDbg writes structured events to a local file under ~/.agentdbg/runs/.
| Event | How it’s recorded | What you see |
|---|---|---|
| Run start / end | @trace (automatic) | Duration, status, error if any |
| LLM calls | record_llm_call() | Model, prompt, response, token usage |
| Tool calls | record_tool_call() | Tool name, args, result, status |
| State updates | record_state() | Arbitrary state snapshots |
| Errors | @trace (automatic) | Exception type, message, stack trace |
| Loop warnings | Automatic detection | Repetitive pattern and evidence |
run.json— run metadata: status, counts, timingevents.jsonl— append-only structured event stream, one JSON object per line
What AgentDbg is and is not
AgentDbg is a development-time debugging tool. It is designed for the “why did it do that?” moment when you’re iterating locally on an agent. AgentDbg is:- A local-first debugger—traces are stored as plain files on disk
- Framework-agnostic—works with any Python code
- A development aid—built for the debugging loop, not production
- A hosted service or cloud platform
- A production observability tool—there are no dashboards, alerts, or monitoring
- Tied to any specific framework or LLM provider
All trace data is stored locally under
~/.agentdbg/runs/ as plain JSON files. No data is sent to any server. AgentDbg has no telemetry, no accounts, and no network requirements beyond your own agent’s calls.