agentdebugx 0.2.4__tar.gz → 0.2.5__tar.gz

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdebugx
-Version: 0.2.4
+Version: 0.2.5
 Summary: Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`.
 License: MIT
 License-File: LICENSE
@@ -26,6 +26,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
 Provides-Extra: all
+Provides-Extra: crewai
 Provides-Extra: hub-hf
 Provides-Extra: langgraph
 Provides-Extra: openhands

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/docs/21_integrations.md

@@ -58,6 +58,62 @@ command:
 | "I need a thorough postmortem" | `agentdebug deep <file|trace_id>` |
 | "share this with the team" | `agentdebug hub push <trace_id> --to git:...` |
 
+## 1.5 CrewAI integration
+
+CrewAI emits a typed event stream via a process-global
+`crewai.events.crewai_event_bus`. `agentdebug.adapters.crewai` ships two
+pieces:
+
+- `CrewAIBridge(debugger, trajectory)` — context manager that subscribes
+  to the bus and translates events into AgentDebug records.
+- `CrewAIAdapter().instrument(debugger)` — used by `agentdebug doctor` to
+  report whether CrewAI is importable.
+
+### Recording a Crew run
+
+```python
+from agentdebug import AgentDebug, SQLiteTraceStore
+from agentdebug.adapters.crewai import CrewAIBridge
+
+debugger = AgentDebug(store=SQLiteTraceStore('.agentdebug/errors.sqlite'))
+trajectory = debugger.start_trace(goal='build a marketing plan', framework='crewai')
+
+with CrewAIBridge(debugger, trajectory):
+    crew.kickoff(inputs={...})   # standard CrewAI call
+
+debugger.finish_trace(trajectory, success=True)
+```
+
+### What gets recorded
+
+| CrewAI event class | AgentDebug `EventType` | Module |
+|---|---|---|
+| `CrewKickoffStartedEvent` | `AGENT_STEP` | planning |
+| `CrewKickoffCompletedEvent` | `OBSERVATION` | planning |
+| `TaskStartedEvent` | `PLAN` | planning |
+| `TaskCompletedEvent` | `OBSERVATION` | planning |
+| `AgentExecutionStartedEvent` | `AGENT_STEP` | planning |
+| `AgentExecutionCompletedEvent` | `OBSERVATION` | reflection |
+| `LLMCallStartedEvent` | `LLM_CALL` | planning |
+| `LLMCallCompletedEvent` | `LLM_RESPONSE` | planning |
+| `ToolUsageStartedEvent` | `TOOL_CALL` | action |
+| `ToolUsageFinishedEvent` | `TOOL_RESULT` | action |
+| `ToolUsageErrorEvent` | `TOOL_RESULT` (with `error`) | action |
+
+Event class names not present in the installed CrewAI version are silently
+skipped — useful for forward/backward compatibility.
+
+### Install
+
+```bash
+pip install 'agentdebugx[crewai]'
+```
+
+### See also
+
+`examples/crewai_demo.py` shows a complete two-agent crew (researcher +
+editor) instrumented with `CrewAIBridge`.
+
 ## 2. OpenHands integration
 
 `agentdebug.integrations.openhands` ships two complementary pieces.

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/docs/22_industry_track_paper_eval_plan.md

@@ -233,3 +233,28 @@ Storage/export:
 4. Run rule, judge, All-at-Once, and DeepDebug on the same split.
 5. Add a small human/expert review with raw trace vs paired trace view.
 6. Trim main body to 6 pages while keeping appendix rich.
+
+## 9. Implemented Experiment Harness
+
+The repository now contains an `experiments/` directory for the first paper
+pipeline:
+
+- `prepare_who_when.py`: downloads the two public Who&When parquet files from
+  Hugging Face and normalizes them into `AgentTrajectory` JSONL plus separate
+  gold labels. On 2026-05-16 this produced 184 traces and 4,092 events.
+- `run_e2e_smoke.py`: exercises the public AgentDebugX modules end to end:
+  analyzer, detectors, traceback, recoverers, attribution, and Error Hub local
+  push/pull. It can optionally call a live OpenAI-compatible endpoint.
+- `run_who_when_eval.py`: runs attribution metrics against Who&When labels,
+  including responsible-agent match, exact step match, +/-1 step match, and
+  joint agent/step accuracy.
+- `generate_paper_figures_openai.py`: generates the optional paper pipeline
+  figure with `gpt-image-2` when `OPENAI_API_KEY` is available.
+
+The AgentDebug / AgentErrorBench dataset is currently linked from the upstream
+paper repository as a Google Drive folder rather than a stable direct download
+URL. `prepare_agenterrorbench.py` accepts a local extracted folder under
+`data/agenterrorbench/raw/`, can attempt `gdown` download when the optional
+dependency is installed, preserves environment metadata for ALFWorld, GAIA, and
+WebShop, and outputs the same `AgentTrajectory` + labels format used by the
+Who&When loader.

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/docs/23_status_v0_2.md

@@ -142,8 +142,12 @@ Before v0.3 ships, this doc should record green checkmarks for:
       default verifier templates (JSON-schema guard, final-state check,
       tool-result type-check, handoff contract, loop-detector guard) and
       emits per-finding `FixProposal` with rationale + suggested code.
-- [ ] One additional framework adapter that goes through the full conformance
-      suite (CrewAI is the most-requested).
+- [x] **One additional framework adapter** — CrewAI adapter shipped in
+      0.2.5 (`agentdebug.adapters.crewai`). `CrewAIBridge` context manager
+      subscribes to `crewai_event_bus`, translates 11 CrewAI event types
+      into `AgentEvent`s. Conformance test mocks the bus and verifies
+      every documented event mapping plus the version-skew degradation
+      path. `examples/crewai_demo.py` shows a working two-agent crew.
 - [ ] HuggingFace Hub round-trip live test (gated on `HF_TOKEN`).
 - [ ] Bench harness extended with one published-benchmark loader (Who&When
       is the obvious first target — we already cite its method).

agentdebugx-0.2.5/docs/benchmarks/e2e_v0_2_4.md

@@ -0,0 +1,365 @@
+# AgentDebugX v0.2.3 End-to-End Real-Usage Smoke
+
+Scenarios: **3**. LLM model: `gemini-3-flash`. Generated by `scripts/e2e_real_usage.py`.
+
+## Per-scenario pipeline status
+
+| Scenario | trace_id | OK / Total stages | Failed stages |
+|---|---|---|---|
+| `action_format_then_hallucination` | `trace_cde22f…` | 12 / 12 | — |
+| `multiagent_handoff_loss` | `trace_84fb3a…` | 12 / 12 | — |
+| `planning_loop` | `trace_c59dc1…` | 12 / 12 | — |
+
+**UI smoke:** ✅ all endpoints responded
+
+```
+GET /healthz -> 200 {"status":"ok"}
+GET /api/v1/traces -> 5 trace(s)
+GET /api/v1/traces/<id> -> 200 events=11 findings=4
+GET /api/v1/taxonomy -> modes=19
+GET / -> 200 content_length=33710 has_brand=True
+```
+
+## `action_format_then_hallucination`
+
+`trace_id=trace_cde22f0eb1ec499aa3bc5b88f472257d`
+
+### ✅ `heuristic_analyzer` (0.00s) — 1 finding(s); root=2
+### ✅ `cross_event_detectors` (0.00s) — 0 finding(s) from default_detectors()
+### ✅ `traceback_offline` (0.00s) — rendered
+
+```
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_cde22f0eb1ec499aa3bc5b88f472257d  framework=e2e-react  goal='Find the latest AgentDebug paper, summarize the method, then email alice@example.com'
+
+      File "root cause", in trajectory
+        Step 2  agent=search_web  mode=system.tool_execution_error  confidence=0.86
+          event_id=evt_1eb26b89fce447fa8d9d908b50741ac3
+          error>  JSON schema validation failed: missing parameter query
+          evidence:
+            - JSON schema validation failed: missing parameter query
+          suggested: Capture tool stderr/status/latency and classify retryable versus non-retryable failures.
+
+AgentFailure[system.tool_execution_error]: Likely root cause: Tool execution error in search_web at step 2.
+```
+
+### ✅ `reflexion_suggestion` (0.00s) — 1 proposal(s)
+
+```
+Reflexion retry hint for system.tool_execution_error at step 2
+```
+
+### ✅ `critic_recoverer` (0.00s) — 1 verifier proposal(s)
+
+```
+Add tool_result_typecheck before system.tool_execution_error (step 2, agent search_web)
+```
+
+### ✅ `llm_judge` (14.31s) — 3 finding(s); root=1
+
+```
+- action.parameter_error (conf=1.00) step=1 agent=search_web
+- verification.premature_stop (conf=1.00) step=4 agent=planner
+- verification.missing_task_validation (conf=0.90) step=None agent=system
+```
+
+### ✅ `attribute_heuristic` (0.00s) — method=heuristic agent=search_web step=1 conf=1.00
+
+```
+Earliest finding with non-trivial confidence: Parameter error
+```
+
+### ✅ `attribute_all_at_once` (7.52s) — method=all_at_once agent=search_web step=1 conf=0.90
+
+```
+The root cause is the malformed tool call in step 1, where the search_web tool was invoked without the required 'query' parameter, leading to a validation error that derailed the entire process.
+```
+
+### ✅ `attribute_step_by_step` (23.64s) — method=step_by_step agent=search_web step=1 conf=1.00
+
+```
+The agent invoked the search tool without providing a search query, which is a parameter error that prevents the retrieval of the required information.
+```
+
+### ✅ `attribute_binary_search` (8.01s) — method=binary_search agent=search_web step=2 conf=0.80
+
+```
+Binary search located the decisive step within 2 probes over 6 events.
+```
+
+### ✅ `deep_debug` (28.00s) — 3 finding(s); rounds=6
+
+```
+rounds: plan:4588ms / hypothesize:8051ms / verify:h1:2874ms / verify:h2:2392ms / verify:h3:2514ms / refine:7581ms
+summary: The agent failed to provide the required 'query' parameter when calling the search tool, and the planner subsequently ignored this failure, incorrectly claiming the task was complete without summarizing the paper or sending the email.
+
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_cde22f0eb1ec499aa3bc5b88f472257d  framework=e2e-react  goal='Find the latest AgentDebug paper, summarize the method, then email alice@example.com'
+
+      File "root cause", in trajectory
+        Step 2  agent=search_web  mode=action.parameter_error  confidence=1.00
+          event_id=evt_1eb26b89fce447fa8d9d908b50741ac3
+          error>  JSON schema validation failed: missing parameter query
+          evidence:
+            - JSON schema validation failed: missing parameter query
+            - kwargs='{}'
+          suggested: Validate parameters against tool schemas and ask for missing user/context fields.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 4  agent=planner  mode=reflection.progress_misjudge  confidence=1.00
+          module=reflection
+          event_id=evt_2b76fd64970544908fdb65eee79bbd9d
+          output> Final answer: AgentDebug is a popular paper. Done.
+          evidence:
+            - Final answer: AgentDebug is a popular paper. Done.
+            - meta={'metadata': {'final_answer': True}}
+          suggested: Add an external task verifier before termination.
+    ↓ cascaded to
+      File "cascade depth 2", in trajectory
+        Step ?  agent=system  mode=verification.missing_task_validation  confidence=1.00
+          event_id=evt_15fe36c6a23247cea25efb4a34fccedf
+          evidence:
+            - meta={'success': True}
+          suggested: Add final-state validation that is independent of the acting agent.
+
+AgentFailure[verification.missing_task_validation]: The agent failed to provide the required 'query' parameter when calling the search tool, and the planner subsequently ignored this failure, incorrectly claiming the task was complete without summarizing the paper or sending the email.
+```
+
+### ✅ `hub_round_trip` (0.00s) — pushed=/home/kunlunz2/AgentDebugX/.agentdebug/e2e_hub/bundle_e79cadee55524420ba4719ecd2934536 ; bundle_id=bundle_e79cadee55524420ba4719ecd2934536 ; listed=1 ; round-trip ok
+
+## `multiagent_handoff_loss`
+
+`trace_id=trace_84fb3ac2083c449b8f2ca80503861dc5`
+
+### ✅ `heuristic_analyzer` (0.00s) — 1 finding(s); root=2
+### ✅ `cross_event_detectors` (0.00s) — 0 finding(s) from default_detectors()
+### ✅ `traceback_offline` (0.00s) — rendered
+
+```
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_84fb3ac2083c449b8f2ca80503861dc5  framework=e2e-multiagent  goal='Find the best paper on agent debugging, prefer the most recent.'
+
+      File "root cause", in trajectory
+        Step 2  agent=researcher  mode=multiagent.handoff_loss  confidence=0.70
+          module=multiagent
+          event_id=evt_800ad2ca86644768b07990f0af08e1b6
+          output> Please summarize the agent debugging paper.
+          evidence:
+            - handoff/context signal in event payload
+          suggested: Make handoff payloads typed and include goal, constraints, evidence, confidence, and open questions.
+
+AgentFailure[multiagent.handoff_loss]: Likely root cause: Handoff context loss in researcher at step 2.
+```
+
+### ✅ `reflexion_suggestion` (0.00s) — 1 proposal(s)
+
+```
+Reflexion retry hint for multiagent.handoff_loss at step 2
+```
+
+### ✅ `critic_recoverer` (0.00s) — 1 verifier proposal(s)
+
+```
+Add handoff_context_contract before multiagent.handoff_loss (step 2, agent researcher)
+```
+
+### ✅ `llm_judge` (9.36s) — 2 finding(s); root=2
+
+```
+- multiagent.handoff_loss (conf=1.00) step=2 agent=researcher
+- verification.missing_task_validation (conf=0.90) step=None agent=system
+```
+
+### ✅ `attribute_heuristic` (0.00s) — method=heuristic agent=researcher step=2 conf=1.00
+
+```
+Earliest finding with non-trivial confidence: Handoff context loss
+```
+
+### ✅ `attribute_all_at_once` (3.72s) — method=all_at_once agent=researcher step=2 conf=1.00
+
+```
+The researcher correctly identified Paper A as the most recent in step 1 but failed to specify this choice or the recency constraint during the handoff in step 2, leading the summarizer to pick the wrong paper.
+```
+
+### ✅ `attribute_step_by_step` (21.99s) — method=step_by_step agent=researcher step=2 conf=1.00
+
+```
+The researcher failed to specify which paper to summarize during the handoff, losing the context of the 'most recent' paper identified in the previous step.
+```
+
+### ✅ `attribute_binary_search` (16.41s) — method=binary_search agent=summarizer step=4 conf=0.90
+
+```
+Binary search located the decisive step within 3 probes over 6 events.
+```
+
+### ✅ `deep_debug` (45.65s) — 3 finding(s); rounds=6
+
+```
+rounds: plan:4990ms / hypothesize:7110ms / verify:h1:2939ms / verify:h2:2320ms / verify:h3:5377ms / refine:22907ms
+summary: The researcher agent hallucinated finding specific papers without performing a search and subsequently failed to communicate the paper selection or user constraints to the summarizer, leading to a total failure of the summarization step.
+
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_84fb3ac2083c449b8f2ca80503861dc5  framework=e2e-multiagent  goal='Find the best paper on agent debugging, prefer the most recent.'
+
+      File "root cause", in trajectory
+        Step 1  agent=researcher  mode=memory.hallucination  confidence=0.95
+          module=planning
+          event_id=evt_a4f22a565af84663bab9f0460b122ea8
+          output> Found two candidate papers: A (May 2025) and B (Mar 2024). A is preferred because it is more recent (per user constraint).
+          evidence:
+            - Found two candidate papers: A (May 2025) and B (Mar 2024)
+            - The trajectory shows a premature handoff... without any evidence of search or data retrieval occurring.
+          suggested: Require memory reads to cite the source event or artifact before use.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 2  agent=researcher  mode=multiagent.handoff_loss  confidence=1.00
+          module=multiagent
+          event_id=evt_800ad2ca86644768b07990f0af08e1b6
+          output> Please summarize the agent debugging paper.
+          evidence:
+            - Please summarize the agent debugging paper.
+            - omitted_context: 'preference for A; recency constraint'
+          suggested: Make handoff payloads typed and include goal, constraints, evidence, confidence, and open questions.
+    ↓ cascaded to
+      File "cascade depth 2", in trajectory
+        Step 3  agent=summarizer  mode=memory.retrieval_failure  confidence=0.90
+          module=planning
+          event_id=evt_8f20248aa2b64a6dad966bd9f336cc77
+          input>  Please summarize the agent debugging paper.
+          evidence:
+            - input=Please summarize the agent debugging paper.
+            - output=None
+            - omitted_context: 'preference for A; recency constraint'
+          suggested: Persist the missing state as structured memory and attach it to the next planning step.
+
+AgentFailure[memory.retrieval_failure]: The researcher agent hallucinated finding specific papers without performing a search and subsequently failed to communicate the paper selection or user constraints to the summarizer, leading to a total failure of the summarization step.
+```
+
+### ✅ `hub_round_trip` (0.00s) — pushed=/home/kunlunz2/AgentDebugX/.agentdebug/e2e_hub/bundle_27e79ad1f5454df4b89f9f7fe75bab3e ; bundle_id=bundle_27e79ad1f5454df4b89f9f7fe75bab3e ; listed=3 ; round-trip ok
+
+## `planning_loop`
+
+`trace_id=trace_c59dc17f26994841ad361176ddf6b7c0`
+
+### ✅ `heuristic_analyzer` (0.00s) — 4 finding(s); root=2
+### ✅ `cross_event_detectors` (0.00s) — 3 finding(s) from default_detectors()
+
+```
+- planning.inefficient_plan (source=repeated_tool_call)
+- planning.inefficient_plan (source=repeated_state)
+- planning.inefficient_plan (source=repeated_state)
+```
+
+### ✅ `traceback_offline` (0.00s) — rendered
+
+```
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_c59dc17f26994841ad361176ddf6b7c0  framework=e2e-browser  goal='Submit the checkout form on shop.example.com'
+
+      File "root cause", in trajectory
+        Step 2  agent=browser  mode=planning.inefficient_plan  confidence=0.67
+          event_id=evt_1d189d0f66de4329a6d11f567721eea4
+          output> no progress; same checkout screen
+          evidence:
+            - loop/progress signal in event payload
+          suggested: Add loop detection over tool calls and state deltas.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 4  agent=browser  mode=planning.inefficient_plan  confidence=0.67
+          event_id=evt_d6e7dd127fab458896b58bae5cac1954
+          output> no progress; same checkout screen
+          evidence:
+            - loop/progress signal in event payload
+          suggested: Add loop detection over tool calls and state deltas.
+    ↓ cascaded to
+      File "cascade depth 2", in trajectory
+        Step 6  agent=browser  mode=planning.inefficient_plan  confidence=0.67
+          event_id=evt_c92a15e9cc894bffaff61ec5f6169150
+          output> no progress; same checkout screen
+          evidence:
+            - loop/progress signal in event payload
+          suggested: Add loop detection over tool calls and state deltas.
+    ↓ cascaded to
+      File "cascade depth 3", in trajectory
+        Step 8  agent=browser  mode=planning.inefficient_plan  confidence=0.67
+          event_id=evt_df07344c3e9e4f7fba9cb3df92a73bfd
+          output> no progress; same checkout screen
+          evidence:
+            - loop/progress signal in event payload
+          suggested: Add loop detection over tool calls and state deltas.
+
+AgentFailure[planning.inefficient_plan]: Likely root cause: Inefficient plan in browser at step 2.
+```
+
+### ✅ `reflexion_suggestion` (0.00s) — 4 proposal(s)
+
+```
+Reflexion retry hint for planning.inefficient_plan at step 2
+Reflexion retry hint for planning.inefficient_plan at step 4
+Reflexion retry hint for planning.inefficient_plan at step 6
+Reflexion retry hint for planning.inefficient_plan at step 8
+```
+
+### ✅ `critic_recoverer` (0.00s) — 4 verifier proposal(s)
+
+```
+Add loop_detector_guard before planning.inefficient_plan (step 2, agent browser)
+Add loop_detector_guard before planning.inefficient_plan (step 4, agent browser)
+Add loop_detector_guard before planning.inefficient_plan (step 6, agent browser)
+Add loop_detector_guard before planning.inefficient_plan (step 8, agent browser)
+```
+
+### ✅ `llm_judge` (23.10s) — 0 finding(s); root=None
+### ✅ `attribute_heuristic` (0.00s) — method=heuristic (no hypotheses)
+### ✅ `attribute_all_at_once` (5.36s) — method=all_at_once agent=planner step=1 conf=0.90
+
+```
+The planner established a flawed strategy of repeatedly clicking the submit button without any logic to handle potential form validation errors or investigate why the submission was failing.
+```
+
+### ✅ `attribute_step_by_step` (57.37s) — method=step_by_step agent=planner step=1 conf=0.90
+
+```
+The planner's strategy is fundamentally flawed as it attempts to click a submit button without first navigating to the website or filling out the required form fields.
+```
+
+### ✅ `attribute_binary_search` (24.84s) — method=binary_search agent=browser step=4 conf=0.90
+
+```
+Binary search located the decisive step within 3 probes over 11 events.
+```
+
+### ✅ `deep_debug` (38.32s) — 2 finding(s); rounds=6
+
+```
+rounds: plan:3303ms / hypothesize:9554ms / verify:h1:3739ms / verify:h2:4204ms / verify:h3:8529ms / refine:8988ms
+summary: The agent failed to submit the checkout form because it repeatedly attempted to click the submit button without ensuring all required fields (such as address or payment details) were populated, ignoring the lack of progress between attempts.
+
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_c59dc17f26994841ad361176ddf6b7c0  framework=e2e-browser  goal='Submit the checkout form on shop.example.com'
+
+      File "root cause", in trajectory
+        Step 7  agent=browser  mode=planning.inefficient_plan  confidence=0.95
+          event_id=evt_0b22e12ef8bb48bdad049706d6b77d33
+          input>  {'tool': 'click', 'args': '()', 'kwargs': "{'selector': '#submit'}"}
+          evidence:
+            - step=5 ... click ... #submit
+            - step=7 ... click ... #submit
+            - output=no progress; same checkout screen
+          suggested: Add loop detection over tool calls and state deltas.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 8  agent=browser  mode=planning.constraint_ignorance  confidence=1.00
+          event_id=evt_df07344c3e9e4f7fba9cb3df92a73bfd
+          output> no progress; same checkout screen
+          evidence:
+            - no progress; same checkout screen
+            - Strategy: click #submit until success
+          suggested: Compile task and tool constraints into pre-action checks.
+
+AgentFailure[planning.constraint_ignorance]: The agent failed to submit the checkout form because it repeatedly attempted to click the submit button without ensuring all required fields (such as address or payment details) were populated, ignoring the lack of progress between attempts.
+```
+
+### ✅ `hub_round_trip` (0.01s) — pushed=/home/kunlunz2/AgentDebugX/.agentdebug/e2e_hub/bundle_8f2dab82d8e74638ab8656f834d353ab ; bundle_id=bundle_8f2dab82d8e74638ab8656f834d353ab ; listed=4 ; round-trip ok

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentdebugx"
-version = "0.2.4"
+version = "0.2.5"
 description = "Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`."
 authors = ["ULab @ UIUC <ulab@illinois.edu>"]
 license = "MIT"
@@ -52,12 +52,14 @@ httpx = ">=0.24,<1.0"
 # Optional integrations — install via `pip install agentdebugx[langgraph]` etc.
 [tool.poetry.extras]
 langgraph = ["langchain-core"]
+crewai = ["crewai"]
 otel = ["opentelemetry-api", "opentelemetry-sdk"]
 ui = ["fastapi", "uvicorn"]
 hub-hf = ["huggingface_hub"]
 openhands = ["openhands-ai"]
 all = [
     "langchain-core",
+    "crewai",
     "opentelemetry-api",
     "opentelemetry-sdk",
     "fastapi",

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/src/agentdebug/__init__.py

@@ -96,4 +96,4 @@ __all__ = [
     'get_failure_mode',
 ]
 
-__version__ = '0.2.4'
+__version__ = '0.2.5'

agentdebugx-0.2.5/src/agentdebug/adapters/crewai.py

@@ -0,0 +1,233 @@
+"""CrewAI adapter — subscribe to ``crewai_event_bus`` and record into AgentDebug.
+
+CrewAI's runtime emits typed events through a process-global event bus
+(``crewai.events.crewai_event_bus``). The bus has ~50 event types covering
+crew lifecycle, task lifecycle, agent execution, LLM calls, tool usage,
+flows, memory operations, A2A messages, MCP calls, knowledge ops, and
+guardrails. This adapter subscribes to the subset that matters for
+debugging and translates each into an :class:`agentdebug.models.AgentEvent`.
+
+Why a class (not a free-function listener)? CrewAI's documented gotcha is
+that listeners must be instantiated at module level OR explicitly kept
+alive; otherwise the GC reclaims them before the bus fires. We hide that
+by exposing a context-manager friendly :class:`CrewAIBridge` that holds
+the listener instance for its lifetime.
+
+Usage::
+
+    from agentdebug import AgentDebug, SQLiteTraceStore
+    from agentdebug.adapters.crewai import CrewAIBridge
+
+    debugger = AgentDebug(store=SQLiteTraceStore('.agentdebug/errors.sqlite'))
+    trajectory = debugger.start_trace(goal='build a marketing plan', framework='crewai')
+
+    with CrewAIBridge(debugger, trajectory):
+        crew.kickoff(inputs={...})   # normal CrewAI call; events flow into AgentDebug
+
+    debugger.finish_trace(trajectory, success=True)
+
+The bridge defers the ``crewai`` import, so this module is safe to import
+even when CrewAI is not installed.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any, List, Literal, Optional, Tuple, Type
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+from agentdebug.models import AgentTrajectory, EventType
+from agentdebug.recorder import AgentDebug
+
+LOG = logging.getLogger('agentdebug.adapters.crewai')
+
+
+def _import_crewai_events() -> Any:
+    """Import crewai.events lazily; raise a clear ImportError if missing."""
+    try:
+        import crewai.events as crewai_events
+    except ImportError as exc:
+        raise ImportError(
+            'CrewAIBridge requires the `crewai` package. '
+            "Install with `pip install 'agentdebugx[crewai]'` or `pip install crewai`."
+        ) from exc
+    return crewai_events
+
+
+# Event-type name → (EventType, module, agent-field-name) mapping. We resolve
+# the class objects at attach-time (after import) so module import stays
+# dep-free; class names are stable across CrewAI versions.
+_EVENT_MAP: List[Tuple[str, EventType, Optional[str], Optional[str]]] = [
+    # (CrewAI event class name, agentdebug EventType, module, agent_attr)
+    ('CrewKickoffStartedEvent',    EventType.AGENT_STEP,  'planning', None),
+    ('CrewKickoffCompletedEvent',  EventType.OBSERVATION, 'planning', None),
+    ('TaskStartedEvent',           EventType.PLAN,        'planning', 'agent'),
+    ('TaskCompletedEvent',         EventType.OBSERVATION, 'planning', 'agent'),
+    ('AgentExecutionStartedEvent', EventType.AGENT_STEP,  'planning', 'agent'),
+    ('AgentExecutionCompletedEvent', EventType.OBSERVATION, 'reflection', 'agent'),
+    ('LLMCallStartedEvent',        EventType.LLM_CALL,    'planning', 'agent'),
+    ('LLMCallCompletedEvent',      EventType.LLM_RESPONSE, 'planning', 'agent'),
+    ('ToolUsageStartedEvent',      EventType.TOOL_CALL,   'action',   'agent_role'),
+    ('ToolUsageFinishedEvent',     EventType.TOOL_RESULT, 'action',   'agent_role'),
+    ('ToolUsageErrorEvent',        EventType.TOOL_RESULT, 'action',   'agent_role'),
+]
+
+
+def _attr(obj: Any, *names: str) -> Optional[str]:
+    """Return the first non-None attribute on `obj` from `names`, stringified."""
+    for name in names:
+        v = getattr(obj, name, None)
+        if v is not None:
+            try:
+                return str(v)
+            except Exception:
+                continue
+    return None
+
+
+def _agent_name(event: Any, fallback: str) -> str:
+    # CrewAI events expose the agent in a handful of slightly different fields
+    # depending on the event class; try the common ones in order.
+    return _attr(event, 'agent_role', 'agent_name', 'agent', 'role', 'name') or fallback
+
+
+def _output_for(event: Any) -> Any:
+    return _attr(event, 'output', 'result', 'response', 'completion', 'tool_response')
+
+
+def _input_for(event: Any) -> Any:
+    return _attr(event, 'prompt', 'input', 'tool_input', 'tool_args', 'description')
+
+
+def _error_for(event: Any) -> Optional[str]:
+    err = _attr(event, 'error', 'exception', 'error_message')
+    return err if err else None
+
+
+class CrewAIBridge:
+    """Subscribe to crewai_event_bus and record events into an AgentDebug trajectory.
+
+    Behaves as both a context manager (``with CrewAIBridge(...): ...``) and a
+    plain object with ``attach()`` / ``detach()``.
+    """
+
+    framework = 'crewai'
+
+    def __init__(
+        self,
+        debugger: AgentDebug,
+        trajectory: AgentTrajectory,
+        *,
+        bus: Any = None,
+    ) -> None:
+        self.debugger = debugger
+        self.trajectory = trajectory
+        self._bus = bus
+        self._attached = False
+        # Keep refs to closures so they don't get GC'd while bus holds them.
+        self._handlers: List[Any] = []
+
+    def attach(self) -> 'CrewAIBridge':
+        if self._attached:
+            return self
+        ce = _import_crewai_events()
+        bus = self._bus or getattr(ce, 'crewai_event_bus', None)
+        if bus is None:
+            raise RuntimeError('crewai.events.crewai_event_bus is not available')
+        for class_name, et, module, _agent_attr in _EVENT_MAP:
+            evt_cls = getattr(ce, class_name, None)
+            if evt_cls is None:
+                LOG.debug('CrewAI event class %s not found; skipping', class_name)
+                continue
+            handler = self._make_handler(et, module, class_name)
+            self._handlers.append(handler)
+            bus.on(evt_cls)(handler)
+        self._attached = True
+        return self
+
+    def detach(self) -> None:
+        # CrewAI's event bus does not expose a public unsubscribe surface as
+        # of the versions we target. Drop our handler references so they
+        # become eligible for GC; the bus will skip dead refs.
+        self._handlers.clear()
+        self._attached = False
+
+    # Context-manager sugar — equivalent to attach/detach.
+
+    def __enter__(self) -> 'CrewAIBridge':
+        return self.attach()
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> Literal[False]:
+        self.detach()
+        return False
+
+    # ---- internals ----
+
+    def _make_handler(
+        self,
+        event_type: EventType,
+        module: Optional[str],
+        class_name: str,
+    ) -> Any:
+        debugger = self.debugger
+        trajectory = self.trajectory
+
+        def _on_event(source: Any, event: Any) -> None:
+            try:
+                # NB: record_event takes metadata via **kwargs, so we pass
+                # the per-event tags as flat keyword args. Passing them as
+                # `metadata={...}` would wrap them under `metadata['metadata']`.
+                debugger.record_event(
+                    trajectory,
+                    event_type=event_type,
+                    agent_name=_agent_name(event, fallback=class_name),
+                    module=module,
+                    input=_input_for(event),
+                    output=_output_for(event),
+                    error=_error_for(event),
+                    crewai_event_class=class_name,
+                    crewai_source_type=type(source).__name__,
+                )
+            except Exception as exc:  # pragma: no cover - defensive
+                LOG.warning(
+                    'CrewAIBridge handler for %s raised: %s', class_name, exc
+                )
+
+        return _on_event
+
+
+class CrewAIAdapter:
+    """Structural :class:`FrameworkAdapter` — used by `agentdebug doctor`."""
+
+    framework = 'crewai'
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:  # noqa: D401
+        try:
+            _import_crewai_events()
+        except ImportError as exc:
+            return AdapterStatus(
+                framework=self.framework,
+                implemented=False,
+                notes=str(exc),
+            )
+        return AdapterStatus(
+            framework=self.framework,
+            implemented=True,
+            notes=(
+                'Create a trajectory, then use '
+                '`with CrewAIBridge(debugger, trajectory): crew.kickoff(...)` '
+                'to record every Crew/Task/Agent/LLM/Tool event into AgentDebug.'
+            ),
+        )
+
+
+_: FrameworkAdapter = CrewAIAdapter()  # static structural check
+
+
+__all__ = ['CrewAIAdapter', 'CrewAIBridge']

{agentdebugx-0.2.4 → agentdebugx-0.2.5}/src/agentdebug/cli.py

@@ -447,6 +447,12 @@ def _cmd_doctor() -> int:
         statuses.append(LangGraphAdapter().instrument(_dummy_debugger()))
     except Exception as exc:  # pragma: no cover - defensive
         statuses.append(_status('langgraph', False, str(exc)))
+    try:
+        from agentdebug.adapters.crewai import CrewAIAdapter
+
+        statuses.append(CrewAIAdapter().instrument(_dummy_debugger()))
+    except Exception as exc:  # pragma: no cover - defensive
+        statuses.append(_status('crewai', False, str(exc)))
     try:
         from agentdebug.adapters.otel import OTelExportAdapter