agentdbg

AgentDbg has moved to Maida

The step-through debugger for AI agents.

agentdbg has been renamed to maida.

Please install the new package:

pip install maida-ai

New usage:

from maida import trace

The old agentdbg package is kept only as a compatibility shim and will not receive new features.

AgentDbg captures a structured trace of every agent run - LLM calls, tool calls, errors, state updates, loop warnings - and gives you a clean local timeline to see exactly what happened.

Add @trace, run your agent, then run:

agentdbg view

In under 10 minutes, you can inspect a full execution timeline with inputs, outputs, status, and failure evidence - all on your machine.

No cloud. No accounts. No telemetry. Everything stays on your machine.

Built-in run guardrails: stop runaway debug sessions when an agent starts looping or exceeds your limits for LLM calls, tool calls, total events, or duration.

Get running in 5 minutes

Three commands. No config files, no API keys, no sign-up. Install: pip install agentdbg. Then:

1. Install (one-time)
2. Run example
3. agentdbg view

Step 1: Install

pip install agentdbg

Step 2: Run the example agent

python examples/demo/pure_python.py

This simulates a tiny agent that makes several tool and LLM calls and includes loop warnings and errors. Trace data lands in ~/.agentdbg/runs/.

Step 3: Open the timeline

agentdbg view

A browser tab opens at http://127.0.0.1:8712 showing the full run timeline - every event, with inputs, outputs, and timing. The viewer stays running: run more agents and their timelines appear automatically.

That's it. You're debugging.

Instrument your own agent

Add three lines to any Python agent:

from agentdbg import trace, record_llm_call, record_tool_call

@trace
def run_agent():
    # ... your existing agent code ...

    record_tool_call(
        name="search_db",
        args={"query": "active users"},
        result={"count": 42},
    )

    record_llm_call(
        model="gpt-4",
        prompt="Summarize the search results.",
        response="There are 42 active users.",
        usage={"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20},
    )

run_agent()

Then agentdbg view to see the timeline.

What gets captured

Stop runaway runs with guardrails

Guardrails are opt-in and meant for development-time safety rails: they let you stop an agent when it starts looping or using more budget than intended, while still writing a normal trace you can inspect afterward.

from agentdbg import (
    AgentDbgGuardrailExceeded,
    AgentDbgLoopAbort,
    record_llm_call,
    record_tool_call,
    trace,
)


@trace(
    stop_on_loop=True,
    max_llm_calls=10,
    max_tool_calls=20,
    max_events=80,
    max_duration_s=30,
)
def run_agent():
    ...


try:
    run_agent()
except AgentDbgLoopAbort:
    print("AgentDbg stopped a repeated loop.")
except AgentDbgGuardrailExceeded as exc:
    print(exc.guardrail, exc.threshold, exc.actual)

When a guardrail fires, AgentDbg uses the existing lifecycle:

• it records the event that triggered the issue
• it records ERROR
• it records RUN_END(status=error)
• it re-raises a dedicated exception so your code knows the run was intentionally aborted

Available guardrails:

• stop_on_loop
• stop_on_loop_min_repetitions
• max_llm_calls
• max_tool_calls
• max_events
• max_duration_s

You can set them in @trace(...), traced_run(...), .agentdbg/config.yaml, ~/.agentdbg/config.yaml, or env vars like AGENTDBG_MAX_LLM_CALLS=50.

See docs/guardrails.md for full examples, precedence, and trace behavior.

What you see

In the UI, you see:

• Run summary panel: status (ok / error / running), duration, LLM call count, tool call count, error count, loop warnings, jump-to-first-error, jump-to-first-loop-warning
• Chronological timeline of events
• Expandable events: LLM calls (prompt, response, usage), tool calls (args, results, error status), loop warnings with evidence
• Live-refresh: leave agentdbg view running — new runs appear in the sidebar, events stream in real-time for running agents
• Filter chips: All, LLM, Tools, Errors, State, Loops

Each run produces run.json (metadata, status, counts) and events.jsonl (full structured event stream) under ~/.agentdbg/. Nothing leaves your machine.

What AgentDbg is

• Local-first: traces stored as JSONL on disk. No cloud, no accounts, no telemetry.
• Framework-agnostic: works with any Python code
• Redacted by default: secrets scrubbed before writing to disk
• Active prevention: stop-on-loop guardrails kill runaway agents before they burn your budget
• A development-time debugger for the "why did it do that?" moment

What AgentDbg is NOT

• Not a hosted service or cloud platform
• Not a production observability tool (no dashboards, alerts, or monitoring)
• Not tied to a single framework

CLI reference

List recent runs

agentdbg list              # last 20 runs
agentdbg list --limit 50   # more runs
agentdbg list --json       # machine-readable output

View a run timeline

agentdbg view              # opens latest run, stays running
agentdbg view <RUN_ID>     # specific run
agentdbg view --no-browser # just print the URL

Export a run

agentdbg export <RUN_ID> --out run.json

Capture a baseline

agentdbg baseline <RUN_ID>                          # saves to .agentdbg/baselines/<run_name>.json
agentdbg baseline <RUN_ID> --out baselines/v1.json  # custom path

Assert against a baseline

agentdbg assert <RUN_ID> --baseline .agentdbg/baselines/my_agent.json
agentdbg assert <RUN_ID> --max-steps 80 --no-loops  # standalone thresholds
agentdbg assert <RUN_ID> --baseline baseline.json --format markdown  # for CI summaries

Exit code 0 = pass, 1 = fail. See docs/regression-testing.md for the full workflow and docs/reference/policy.md for policy YAML configuration.

Diff two runs

agentdbg diff <RUN_A> <RUN_B>
agentdbg diff <RUN_A> --baseline .agentdbg/baselines/my_agent.json

Regression testing

Baselines, assertions, and diffs let you catch agent regressions — locally or in CI. The workflow:

1. Baseline a known-good run (agentdbg baseline)
2. Assert future runs against it (agentdbg assert --baseline ...)
3. Diff failures to see what changed (agentdbg diff)

Control assertion thresholds via a committed .agentdbg/policy.yaml file or CLI flags. Supports text, JSON, and markdown output formats.

See docs/regression-testing.md for the end-to-end guide and docs/reference/policy.md for the policy file reference.

Redaction & privacy

Redaction is ON by default. AgentDbg scrubs values for keys matching sensitive patterns (case-insensitive) before writing to disk. Large fields are truncated (marked with __TRUNCATED__ marker).

Default redacted keys: api_key, token, authorization, cookie, secret, password.

# Override defaults via environment variables
export AGENTDBG_REDACT=1                    # on by default
export AGENTDBG_REDACT_KEYS="api_key,token,authorization,cookie,secret,password"
export AGENTDBG_MAX_FIELD_BYTES=20000       # truncation limit

You can also configure redaction in .agentdbg/config.yaml (project root) or ~/.agentdbg/config.yaml.

Guardrails

Guardrails are separate from redaction and are disabled by default. They are useful when you want AgentDbg to actively stop a run instead of only recording what happened.

export AGENTDBG_STOP_ON_LOOP=1
export AGENTDBG_STOP_ON_LOOP_MIN_REPETITIONS=3
export AGENTDBG_MAX_LLM_CALLS=50
export AGENTDBG_MAX_TOOL_CALLS=50
export AGENTDBG_MAX_EVENTS=200
export AGENTDBG_MAX_DURATION_S=60

YAML example:

guardrails:
  stop_on_loop: true
  stop_on_loop_min_repetitions: 3
  max_llm_calls: 50
  max_tool_calls: 50
  max_events: 200
  max_duration_s: 60

Precedence:

1. Function arguments passed to @trace(...) or traced_run(...)
2. Environment variables
3. Project YAML: .agentdbg/config.yaml
4. User YAML: ~/.agentdbg/config.yaml
5. Defaults

See docs/guardrails.md and docs/reference/config.md.

Storage

All data is local. Plain files, easy to inspect or delete.

~/.agentdbg/
└── runs/
    └── <run_id>/
        ├── run.json        # run metadata (status, counts, timing)
        └── events.jsonl    # append-only event log

Override the location:

export AGENTDBG_DATA_DIR=/path/to/traces

Integrations

AgentDbg is framework-agnostic at its core. The SDK works with any Python code.

LangChain / LangGraph

Optional callback handler that auto-records LLM and tool events. Requires langchain-core:

pip install agentdbg[langchain]

from agentdbg import trace
from agentdbg.integrations import AgentDbgLangChainCallbackHandler

@trace
def run_agent():
    handler = AgentDbgLangChainCallbackHandler()
    # pass to your chain: config={"callbacks": [handler]}
    ...

See examples/langchain/minimal.py for a runnable example.

OpenAI Agents SDK

Optional tracing adapter that auto-records generation, function, and handoff spans. Requires openai-agents:

pip install agentdbg[openai]

from agentdbg import trace
from agentdbg.integrations import openai_agents  # registers hooks


@trace
def run_agent():
    # ... your OpenAI Agents SDK code ...
    ...

See examples/openai_agents/minimal.py for a runnable fake-data example with no API key and no networked model calls.

CrewAI

Optional execution-hook adapter that auto-records LLM and tool events from CrewAI crews and flows. Requires crewai[tools]:

pip install agentdbg[crewai]

import agentdbg
from agentdbg.integrations import crewai as adbg_crewai  # registers hooks

@agentdbg.trace
def run_crew():
    # ... your crew.kickoff() or flow.kickoff() ...
    ...

More framework adapters coming soon (Agno, and others).

Tutorials

Step-by-step Jupyter notebooks live in a separate repository: AgentDbg/tutorials. Covers LangChain, OpenAI Agents SDK, and guardrails — all runnable without API keys.

Development

git clone https://github.com/AgentDbg/AgentDbg.git
cd AgentDbg
uv venv && uv sync && uv pip install -e .

python -m venv .venv && source .venv/bin/activate
pip install -e .

For LangChain support: pip install -e ".[langchain]". For OpenAI Agents support: pip install -e ".[openai]". Run tests: uv run pytest (or pytest).

License

Licensed under the Apache License, Version 2.0. See LICENSE.