agent-debugger 0.1.3

Agent Debugger for LangChain/LangGraph

adb: Agent Debugger for LangChain/LangGraph

A TUI debugger that combines application-level agent inspection (state, memory, tool calls, messages) with Python-level debugging (breakpoints, stepping, variable inspection).

Motivation

An agent developer needs to answer two kinds of questions simultaneously:

1. Application-level: "Which node ran? What tool was called? How did state change?"

2. Code-level: "Why did this node produce that output? What's in the local variables at line 42? Why did the conditional branch go left?"

Today you have to choose one or the other. When you stop at a breakpoint inside a node, you want to see both the Python locals and the graph-level context (which node, what triggered it, the full agent state). A combined debugger makes "zoom in / zoom out" seamless

Quick Start

# Install
uv add agent-debugger

# Debug a LangGraph agent script
adb run my_agent.py

# Attach to a specific graph object
adb attach my_module:graph

# Attach with optional renderers/providers
adb attach my_module:graph \
  --store-renderer my_mod:StoreRenderer \
  --state-renderer my_mod:StateRenderer \
  --output-renderer my_mod:ChatOutputRenderer \
  --tool-renderer my_mod:ToolRenderer \
  --state-mutator my_mod:StateMutator

Run from Source

# Create/update local env from this repo
uv sync --dev

# Run adb directly from source (project root)
uv run adb run examples/simple_agent.py

# Equivalent module invocation
uv run python -m agent_debugger.cli run examples/simple_agent.py

Simple Agent Demo

# Run simple_agent with all demo renderer/mutator extensions
uv run adb run examples/simple_agent.py \
  --store-renderer examples.simple_extensions:SimpleStoreRenderer \
  --output-renderer examples.simple_extensions:SimpleChatOutputRenderer \
  --tool-renderer examples.simple_extensions:SimpleToolRenderer \
  --state-mutator examples.simple_extensions:SimpleStateMutator

# Optional: enable LiteLLM tool-calling path in examples/simple_agent.py
# (example model uses Vertex + service account/ADC auth)
USE_LITELLM=1 LITELLM_MODEL=vertex_ai/gemini-2.0-flash uv run adb run examples/simple_agent.py \
  --store-renderer examples.simple_extensions:SimpleStoreRenderer \
  --output-renderer examples.simple_extensions:SimpleChatOutputRenderer \
  --tool-renderer examples.simple_extensions:SimpleToolRenderer \
  --state-mutator examples.simple_extensions:SimpleStateMutator

Features

• Application-level debugging: See agent state, messages, tool calls, state diffs
• Code-level debugging: Set breakpoints, step through code, inspect variables
• Agent-level breakpoints: Break on node start, tool call, or state change
• Optional renderers/providers: Custom state, store, tools, chat output, and state mutation hooks
• Persistent tool history: Tool calls are kept across turns in the Tools pane and grouped by turn
• import agent_debugger as adb; adb.set_trace(): Drop into the debugger from anywhere in your agent code

Usage

# Set a breakpoint on a node
/break node agent

# Set a breakpoint on a tool
/break tool search_listings

# Break when a state key changes
/break state messages

# Standard Python breakpoint
/break line my_agent.py:42

# Clear local UI context
/clear

# Local clear + optional mutator mutation
/clear memory

See /help in the TUI for all commands.

Programmatic Breakpoints

You can drop into the adb debugger from anywhere in your agent code using Python's built-in breakpoint():

PYTHONBREAKPOINT="adb.set_trace" adb run my_agent.py

Then add breakpoint() calls in your code:

def my_node(state: dict) -> dict:
    messages = state.get("messages", [])
    breakpoint()  # execution pauses here in the adb UI
    return {"messages": [...]}

Or call adb.set_trace() directly:

def my_node(state: dict) -> dict:
    import agent_debugger as adb; adb.set_trace()
    return {"messages": [...]}

Debug Keys

When at a breakpoint, use pudb-style keys:

Key	Action
c	Continue execution
n	Step over (next line)
s	Step into
r	Step out (return / finish)

Implementation note: When a breakpoint hits, the Input widget is disabled (inp.disabled = True). This prevents it from consuming keystrokes, so c/n/s/r go to the App's BINDINGS instead. When the user presses c (continue), the Input is re-enabled and re-focused.

Design

See Design.md.