Metadata-Version: 2.4
Name: agent-debugger
Version: 0.1.4
Summary: Agent Debugger for LangChain/LangGraph
Project-URL: Homepage, https://github.com/dkondo/agent-tackle-box
Project-URL: Repository, https://github.com/dkondo/agent-tackle-box
Project-URL: Source Code, https://github.com/dkondo/agent-tackle-box/tree/main/projects/agent-debugger
Author-email: Derrick Kondo <dkondo@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,debugger,langchain,langgraph,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: deepdiff>=8.0
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph>=0.4
Requires-Dist: rich>=13.0
Requires-Dist: textual>=3.0
Provides-Extra: litellm
Requires-Dist: langchain-litellm>=0.5.1; extra == 'litellm'
Requires-Dist: python-dotenv>=1.0; extra == 'litellm'
Description-Content-Type: text/markdown

# adb: Agent Debugger for LangChain/LangGraph

A terminal UI 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**: "How did state or memory change? What tools were called and how?"
    
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?"
    
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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()`:

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

Then add `breakpoint()` calls in your code:

```python
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:

```python
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`](docs/Design.md).
