AgentDebugX

AgentDebugX

A local-first debugging framework for agentic AI systems: diagnose failures, attribute root causes, recover with evidence, and validate fixes through reruns.

AgentDebugX turns failed agent runs into structured, auditable debugging artifacts. It ingests a live or exported trajectory, detects visible failure signals, attributes them to responsible steps or agents, proposes recovery actions, and prepares controlled reruns so fixes can be validated instead of guessed.

The project is designed for researchers and engineers building complex LLM agents: multi-agent systems, tool-using agents, computer-use agents, benchmark runners, and local agent development workflows. AgentDebugX is local-first by default: traces stay on your machine, sharing is opt-in, and recovery proposals carry explicit policy and approval metadata into the Rerun boundary.

📰 News

• 🔌 2026-08-25 — Released

dsh-agentdebugx v0.1.0, the AgentDebugX plugin for DeepSeek Harness.

• 📄 2026-07-31 — Released

CUADebug, our framework for diagnosing and repairing computer-use agent failures.

• 📄 2026-07-21 — Released the

AgentDebugX paper, presenting our open-source toolkit for failure observability, attribution, recovery, and rerun in LLM agents.

• 📦 2026-05-16 — Released AgentDebugX on

PyPI.

• 📄 2025-09-29 — Released

Where LLM Agents Fail and How They Can Learn From Failures, introducing AgentErrorTaxonomy, AgentErrorBench, and AgentDebug.

System Overview

AgentDebugX follows the two-stage loop used by the project paper:

Diagnose = Detect -> Attribute -> Recover
Rerun    = checkpoint -> retry directive -> branch execution -> evaluation

Diagnose explains what failed and why. Rerun tests whether the proposed recovery actually improves the agent behavior.

Why AgentDebugX

Tracing tools show what happened. AgentDebugX focuses on the debugging step that usually comes next:

• Which earlier decision caused the visible failure?
• Which agent, tool call, memory read, handoff, or GUI action was responsible?
• What evidence supports that diagnosis?
• What concrete recovery should be tried?
• Did the rerun branch improve the outcome?

The output is a portable diagnostic report that can be inspected in a local UI, used by a CLI workflow, stored in an Error Hub bundle, or invoked from an agentic skill.

Core Capabilities

• Portable trace schema: framework-agnostic trajectory, event, finding, and

diagnostic report models.

• Ingest adapters: normalize raw JSON, LangGraph, CrewAI, OpenAI Agents SDK,

OpenTelemetry, GAIA/Open Deep Research, OSWorld, and other exported traces.

• Detect: deterministic analyzers, manifest-backed rule packs, LLM judge

mode, GUI-aware signals, and taxonomy induction support.

• Attribute: heuristic attribution, all-at-once analysis, step-by-step

localization, binary search, counterfactual attribution, MOE localization, and DeepDebug.

• Recover: Reflexion, CRITIC, Self-Refine, AutoManual, DeepDebug recovery,

and saga rollback style strategies.

• Rerun: three explicit modes for plan/export only, labeled simulation, or

observed execution in an application-owned process or persistent HTTP runner.

• Local inspection UI: no-build FastAPI dashboard for traces, reports,

before/after CUA visuals, debugger discussions, saved cases, debug branches, and rerun-from-event workflows.

• Error Hub: scrubbed, shareable failure bundles for regression tests,

benchmark corpora, and team debugging memory.

• Agent integrations: generate host-runtime assets such as debugging skills

for external agent tools.

Install

pip install agentdebugx

Optional extras:

pip install "agentdebugx[ui]"             # local FastAPI dashboard
pip install "agentdebugx[langgraph]"      # LangGraph adapter
pip install "agentdebugx[crewai]"         # CrewAI adapter
pip install "agentdebugx[openai-agents]"  # OpenAI Agents SDK adapter
pip install "agentdebugx[otel]"           # OpenTelemetry ingest
pip install "agentdebugx[gui]"            # screenshot decoding for GUI RCA
pip install "agentdebugx[all]"            # all optional integrations

Computer-use / OSWorld GUI root-cause analysis (agentdebug.gui) ships with the core install and needs no extra. The gui extra only adds pillow, which the RCA tools use to decode screenshots. Two heavier layers of the same package sit behind their own extras: gui-memory for the lesson/episodic memory stack, and gui-app for the provider adapters, the batch pipeline (python -m agentdebug.gui) and the Streamlit annotation app.

The package is installed as agentdebugx and imported as agentdebug:

import agentdebug

Claude Code and Codex Plugins

AgentDebugX ships native plugins for Claude Code and Codex so an agent can debug its own session. The plugin bundles capture hooks and the AgentDebug skill, which keeps two boundaries explicit:

• Capture is automatic once a project opts in. Sessions are normalized into

AgentDebugX trajectories locally and silently.

• Diagnosis is explicit. Ask AgentDebug in-session and the skill diagnoses

that exact captured trajectory with agentdebug run --current --profile deep. Re-running or repairing the agent's work stays a separately authorized step.

Follow the capture quickstart to install a plugin, enable project capture, diagnose a session, and turn capture off again.

The plugin bundles live in this repository:

Plugin · Bundle · Documentation Claude Code · integrations/claude-code/plugins/agentdebug · Claude Code plugin Codex · integrations/codex/plugins/agentdebug · Codex plugin

Each plugin's documentation covers its hooks, install scope, the capture consent step, and lazy session creation. See src/agentdebug/capture/README.md for the stored .agentdebug/ layout and src/agentdebug/workbench/README.md for agentdebug run profiles and run manifests.

DeepSeek Harness Plugin

AgentDebugX is also available as the dsh-agentdebugx plugin for DeepSeek Harness. It diagnoses current and saved Harness trajectories and starts the Python bridge and local dashboard only when they are needed.

pip install "agentdebugx[ui]>=0.3.1,<0.4"
dsh plugin --profile web add dsh-agentdebugx

See the plugin documentation for configuration, commands, saved-session discovery, and deep diagnosis.

Quick Start: Python API

Record a trajectory and analyze it locally:

from agentdebug import AgentDebug, EventType

debugger = AgentDebug()

with debugger.trace(
    goal="Book a refundable NYC to SFO flight",
    framework="my-agent",
) as trace:
    trace.record(
        EventType.PLAN,
        agent_name="planner",
        step_index=1,
        output="Search for the cheapest fares.",
    )
    trace.record(
        EventType.TOOL_RESULT,
        agent_name="browser",
        step_index=3,
        error="Checkout failed: refund_policy is required.",
    )

    report = trace.analyze()

print(report.summary)
for finding in report.findings:
    print(finding.failure_mode.mode_id, finding.step_index, finding.evidence)

The report localizes the responsible upstream step rather than only reporting the final visible error.

Quick Start: CLI

The CLI supports the complete Diagnose -> Rerun workflow. The web console is optional and is not required for trace conversion, diagnosis, attribution, recovery planning, or rerun preparation.

1. Normalize an external trace

AgentDebugX can auto-detect common JSON and JSONL exports:

agentdebug ingest raw_trace.json --format auto --out trace.json

Use --format when the source is known, for example messages, openai_agents_spans, crewai_events, langgraph_callbacks, claude_code, codex, or osworld.

Process a directory of independent JSON files or every non-empty line in a JSONL dataset:

agentdebug batch ingest AgentProcessBench/gaia_dev/test.jsonl \
  --out-dir data/agentprocessbench/gaia_dev

Batch diagnosis normalizes each record and writes independently rerunnable trajectories and reports:

agentdebug batch diagnose AgentProcessBench/gaia_dev/test.jsonl \
  --mode judge \
  --attributor all-at-once \
  --recovery self-refine \
  --out-dir runs/agentprocessbench/gaia_dev

Every batch writes batch-summary.json. Invalid records are isolated and do not discard successful outputs; a partially failed CLI batch exits with code 3.

2. Run a fully local diagnosis

The deterministic pipeline does not require an API key: