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

Name	agent-debugging
Description	Systematic debugging workflow for all agentic frameworks. Directs to RAG for solutions.

agent-debugging

SKILL.md