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]