Metadata-Version: 2.4
Name: agent-debugger
Version: 0.1.3
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 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

```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).
