agent-debugging

Agent Debugging Skill

Systematic debugging and troubleshooting framework for ElevenLabs Conversational AI + Twilio integration on the Next Level Real Estate platform. This skill provides diagnostic procedures, root cause analysis techniques, and resolution strategies.

When to Use This Skill

Invoke this skill when you need to:

• ✅ Debug agent configuration issues
• ✅ Analyze failed or poor-quality calls
• ✅ Troubleshoot audio/latency problems
• ✅ Investigate conversation breakdowns
• ✅ Review and interpret error logs
• ✅ Diagnose context injection failures
• ✅ Identify performance bottlenecks
• ✅ Generate diagnostic reports

Debugging Methodology

The 5-Step Debug Process

1. OBSERVE   → Gather symptoms and error data
2. REPRODUCE → Confirm issue is consistent
3. ISOLATE   → Narrow down to specific component
4. DIAGNOSE  → Identify root cause
5. FIX       → Implement and verify solution

Common Issues & Solutions

Issue Category 1: Agent Configuration

Problem: Agent Not Starting/Responding

Symptoms:

• Agent status shows "inactive" or "error"
• Conversation fails to start
• No greeting heard on call
• Error: "Agent not found" or "Invalid agent ID"

Diagnostic Steps:

# 1. Check agent exists and is active
Use mcp__elevenlabs__elevenlabs_get_agent with:
{
  "agentId": "your_agent_id"
}

# Expected output:
# - status: "active"
# - voiceId: valid voice ID
# - modelId: valid model
# - systemPrompt: non-empty

# 2. Verify voice is valid
Use mcp__elevenlabs__elevenlabs_get_voice with:
{
  "voiceId": "voice_from_agent_config"
}

# 3. Check agent configuration file
Read .claude/agents/elevenlabs-agent-manager.md

# Look for:
# - Syntax errors in frontmatter
# - Invalid tool names
# - Malformed YAML

Common Root Causes:

Root Cause	Symptoms	Solution
Invalid voice ID	Agent fails to start	Use list_voices to find valid ID
Voice not available for TTS	"Voice not supported" error	Select voice with availableForTts: true
Empty system prompt	Generic/confused responses	Add detailed system prompt
Wrong model ID	"Model not found" error	Use: eleven_flash_v2_5, eleven_turbo_v2_5, or eleven_multilingual_v2
Agent not deployed	"Agent not found"	Re-create agent or verify agent ID