agent-debugging
by MattMagg
Claude Code plugins for building AI agents across frameworks (Google ADK, OpenAI, and more)
Run in ManusSKILL.md
name: Agent Debugging description: Systematic debugging workflow for all agentic frameworks. Directs to RAG for solutions.
Agent Debugging Workflow
Diagnostic Categories
| Category | Symptoms | First Checks |
|---|---|---|
| IMPORT | ModuleNotFoundError, ImportError | pip list, venv active, import paths |
| TOOL | "tool not found", wrong args | docstrings, decorators, registration |
| AUTH | 401, 403, "invalid key" | .env exists, env vars set, key format |
| CONFIG | "missing config", wrong values | .env format (no quotes!), required fields |
| RUNTIME | Unexpected behavior, crashes | logs, state inspection, callbacks |
| MULTI_AGENT | Wrong routing, delegation fails | agent descriptions, routing logic |
| STREAMING | Connection issues, timeouts | SSE config, network, timeout settings |
Systematic Debug Process
Step 1: Reproduce
Enable verbose/trace mode for the framework.
RAG Query: mcp__agentic-rag__search("[framework] debugging tracing", mode="explain")
Step 2: Isolate
- Comment out components one by one
- Test tool functions in isolation
- Check agent without tools first
- Test with minimal prompt
Step 3: Categorize
Match symptoms to category above. This determines the fix strategy.
Step 4: Diagnose
RAG Query: mcp__agentic-rag__search("error: [error message]", mode="explain")
Check framework-specific gotchas in the relevant @framework skill.
Step 5: Fix & Verify
- Make ONE minimal change
- Run verification command
- If fails, revert and try next hypothesis
Quick Diagnostics
Import Failures
- Is virtual environment active?
- Is package installed? (
pip list | grep [package]) - Is import path correct for version?
RAG Query: mcp__agentic-rag__search("[framework] installation imports", mode="explain")
Tool Not Working
- Does tool have a docstring? (Most frameworks require it)
- Is decorator applied correctly?
- Is tool registered with agent?
- Do parameter types match docstring?
RAG Query: mcp__agentic-rag__search("tool definition", mode="build")
Auth Failures
- Does .env file exist and load?
- Is key format correct? (NO quotes in .env files)
- Is env var name correct for framework?
- Is key valid and not expired?
RAG Query: mcp__agentic-rag__search("[framework] authentication", mode="explain")
Wrong Routing (Multi-Agent)
- Are agent descriptions specific enough?
- Is routing logic correct?
- Are all agents registered?
RAG Query: mcp__agentic-rag__search("agent routing delegation", mode="build")
Framework Debug Commands
| Framework | How to Enable Tracing | RAG Query |
|---|---|---|
| ADK | Tracing plugins | "ADK tracing debugging" |
| OpenAI | Debug env var | "openai agents debug" |
| LangChain | LangSmith / set_debug | "langchain tracing langsmith" |
| LangGraph | LangSmith | "langgraph debugging" |
| CrewAI | verbose=True | "crewai verbose debugging" |
| Anthropic | Logging | "anthropic logging debug" |
Common Fix Patterns
| Problem | Typical Fix |
|---|---|
| Missing module | pip install [package] + check venv |
| Tool ignored | Add/fix docstring with Args/Returns |
| Auth failure | Check .env format, no quotes |
| Wrong agent called | Make descriptions more specific |
| State lost | Check state passing between nodes/agents |
| Infinite loop | Add termination condition, max iterations |
When Nothing Works
- Strip to minimal reproducer
- Query RAG with exact error:
mcp__agentic-rag__query_docs("exact error message") - Check framework's GitHub issues
- Verify you're on supported version
Score
Total Score
Based on repository quality metrics
SKILL.mdファイルが含まれている
ライセンスが設定されている
100文字以上の説明がある
GitHub Stars 100以上
3ヶ月以内に更新がある
10回以上フォークされている
オープンIssueが50未満
プログラミング言語が設定されている
1つ以上のタグが設定されている
Reviews
Reviews coming soon