adk-debugger

lavinigam-gcp's avatarfrom lavinigam-gcp

Troubleshoot ADK errors and issues. Use when encountering API errors, model overloaded errors, state issues, tool failures, authentication problems, or unexpected agent behavior.

⭐0stars🔀1forks📁View on GitHub🕐Updated Jan 7, 2026
[Debugging]

When & Why to Use This Skill

The ADK Debugger is a specialized Claude skill designed to streamline the troubleshooting process for Agent Development Kit (ADK) projects. It provides instant diagnostic solutions and actionable fixes for common API errors, model rate limits, tool calling conflicts, and state management issues, significantly reducing development downtime for AI agent engineers.

Use Cases

  • Resolving authentication and environment configuration errors such as missing or invalid GOOGLE_API_KEY in the app directory.
  • Mitigating '503 Model Overloaded' errors by guiding users through model switching and configuration optimization.
  • Fixing tool execution failures caused by schema conflicts, specifically when output_schema inadvertently disables tool calling.
  • Debugging state flow inconsistencies where output keys do not match instruction placeholders, ensuring seamless data transfer between agents.
  • Performing quick environment health checks and log analysis to identify the root cause of unexpected agent behavior.
nameadk-debugger
descriptionTroubleshoot ADK errors and issues. Use when encountering API errors, model overloaded errors, state issues, tool failures, authentication problems, or unexpected agent behavior.

ADK Debugger

Quick Diagnosis

Symptom Likely Cause Quick Fix
GOOGLE_API_KEY not set Missing .env Create app/.env
503 model overloaded Gemini 3 rate limit Switch to Gemini 2.5 Pro
Tool not being called output_schema set Remove output_schema
State variable empty Key mismatch Check output_key names
TTS fails Vertex AI mode Use AI Studio for multi-speaker

Common Errors & Fixes

API Key Issues

Error: GOOGLE_API_KEY not set or Invalid API key

Fix: Create .env file in app/ folder (not project root):

echo "GOOGLE_API_KEY=your_key" >> app/.env
echo "MAPS_API_KEY=your_maps_key" >> app/.env

Model Overloaded (503)

Error: 503 UNAVAILABLE - model overloaded

Fix: Edit app/config.py:

# Switch from Gemini 3 to 2.5
FAST_MODEL = "gemini-2.5-pro"  # More stable
PRO_MODEL = "gemini-2.5-pro"

Tool Not Called

Cause: Using output_schema disables tool calling.

Fix: Remove output_schema or use separate agent:

# DON'T: This disables tools
agent = LlmAgent(
    tools=[my_tool],
    output_schema=MySchema,  # Conflicts!
)

# DO: Separate concerns
tool_agent = LlmAgent(tools=[my_tool], ...)
schema_agent = LlmAgent(output_schema=MySchema, ...)

State Variable Empty

Cause: output_key doesn't match instruction placeholder.

Fix: Ensure names match exactly:

# Agent 1
agent1 = LlmAgent(output_key="market_data", ...)

# Agent 2 instruction must use same key
INSTRUCTION = "Use this data: {market_data}"  # Must match!

Debugging Steps

  1. Check environment: cat app/.env
  2. Run quick test: make test-intake
  3. Check logs: Look for callback messages
  4. Verify state flow: Check output_key → instruction placeholders

[See references/common-errors.md for complete error catalog]