Voice Agent Expert – Debugging Cheat Sheet (Skill)

Diagnose Letta voice agent issues with automated scripts and restart steps.

Updated Sep 22, 2025

Search Tags:#debug #voice #diagnostic #livekit #letta

Ready to run

npx skills add https://github.com/EGAdams/planner --skill voice-agent-expert-debugging-cheat-sheet-skill

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: Voice Agent Expert – Debugging Cheat Sheet (Skill)
Source: https://github.com/EGAdams/planner/tree/main/.claude/skills/voice-agent-expert
Command: npx skills add https://github.com/EGAdams/planner --skill voice-agent-expert-debugging-cheat-sheet-skill

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Quick-reference guidance and automated tips for diagnosing and fixing Letta Voice Agent issues, including duplicate processes, stale Livekit rooms, token expiry, and proper mode usage.

Core Features & Use Cases

Duplicate Prevention: Detect and automatically clean duplicate voice-agent processes.
Health Checks: Quick status checks for Letta, Livekit, and tokens.
Emergency Fixes: Nuclear reset workflows and safe restarts.

Quick Start

Run the diagnostic and follow the recommended restart steps:

python3 /path/to/diagnose_voice_system.py

Frequently Asked Questions about Voice Agent Expert – Debugging Cheat Sheet (Skill)

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I debug duplicate voice agent processes in Letta?▼

Duplicate voice agent processes occur when startup scripts fail to clean stale instances. Run the diagnostic script to detect and automatically remove duplicate Letta processes, then execute the idempotent startup flow to prevent recurrence.

What causes stale Livekit rooms and how do I fix them?▼

Stale Livekit rooms result from incomplete disconnections or token expiry. The diagnostic identifies disconnected rooms and token status, then provides automated remediation steps to reset rooms and refresh tokens for clean reconnection.

How do I perform a safe restart of my Letta voice system?▼

Safe restart workflows clean duplicate processes, validate token expiry, and verify Livekit connectivity before restarting. Run the included diagnostic and follow the recommended restart sequence to avoid timeouts and misrouted traffic.

Can I use this troubleshooting approach in production environments?▼

Yes, the Skill applies to development, testing, and production scenarios. It provides actionable remediation steps and automated diagnostics through scripts, supporting both emergency fixes and preventative health checks across environments.

What should I check first when voice agents fail to connect?▼

Start with health checks for Letta, Livekit, and token validity. The diagnostic script runs these checks automatically and surfaces connectivity issues, duplicate processes, and token problems to guide your troubleshooting.

Why am I seeing timeouts and misrouted traffic in my voice system?▼

Timeouts and misrouting typically stem from duplicate processes, stale rooms, or expired tokens. The diagnostic identifies these root causes and provides automated cleanup and restart procedures to restore normal traffic flow.