Debugging voice agents

Learn to identify, diagnose, and fix common issues with your voice assistants and workflows

Overview

Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause.

Most common issues fall into these categories:

Speech & Understanding

Agent doesn’t understand user input correctly
Responses are inappropriate or inconsistent
Agent sounds robotic or unnatural

Technical & Integration

Call quality issues or audio problems
Tool integrations failing or returning errors
Workflow logic not executing as expected

Quick diagnostics

Start with these immediate checks before diving deeper:

Test in dashboard

Test your voice agent directly in the dashboard:

Assistants

Click “Talk to Assistant” to test

Workflows

Click “Call” to test workflow

Benefits:

Eliminates phone network variables
Provides real-time transcript view
Shows tool execution results immediately

Check logs

Navigate to the Observe section in your dashboard sidebar:

Call Logs

Review call transcripts, durations, and error messages

API Logs

Check API requests and responses for integration issues

Webhook Logs

Verify webhook deliveries and server responses

Test individual components

Use dashboard testing features:

Voice Test Suites

Automated testing for assistants

Tool Testing

Test tools with sample data

Verify provider status

Check if AI service providers are experiencing issues:

Core Services:

Visit Vapi Status Page for Vapi service status

Provider Status Pages:

OpenAI Status for OpenAI language models
Anthropic Status for Anthropic language models
ElevenLabs Status for ElevenLabs voice synthesis
Deepgram Status for Deepgram speech-to-text
Gladia Status for Gladia speech-to-text
And other providers’ status pages as needed

Dashboard debugging resources

The Vapi dashboard provides powerful debugging features to help you identify and fix issues quickly:

Call Logs

Navigate to Observe > Call Logs to:

Review complete call transcripts
Check call duration and completion status
Identify where calls failed or ended unexpectedly
See tool execution results and errors
Analyze conversation flow in workflows

API Logs

Navigate to Observe > API Logs to:

Monitor all API requests and responses
Check for authentication errors
Verify request payloads and response codes
Debug integration issues with external services

Webhook Logs

Navigate to Observe > Webhook Logs to:

Verify webhook deliveries to your server
Check server response codes and timing
Debug webhook authentication issues
Monitor event delivery failures

Use the Vapi CLI to forward webhooks to your local development server:

$ # Terminal 1: Create tunnel (e.g., with ngrok)
$ ngrok http 4242
$ 
$ # Terminal 2: Forward webhooks
$ vapi listen --forward-to localhost:3000/webhook

vapi listen is a local forwarder that requires a separate tunneling service. Update your webhook URLs in Vapi to use the tunnel’s public URL. Learn more →

Voice Test Suites

Navigate to Test > Voice Test Suites to:

Run automated tests on your assistants (not available for workflows)
Test conversation flows with predefined scenarios
Verify assistant behavior across different inputs
Monitor performance over time

Tool Testing

For any tool in your Tools section:

Navigate to Tools > [Select Tool]
Use the Test button to send sample payloads
Verify tool responses and error handling
Debug parameter extraction and API calls

Speech and language issues

Problem	Symptoms	Solution
Transcription accuracy	Incorrect words in transcripts, missing words/phrases, poor performance with accents	Switch to more accurate transcriber.
Intent recognition	Agent responds to wrong intent, fails to extract variables, workflow routing to wrong nodes	Make system prompt / node prompt more specific; use clear enum values; adjust the temperature to ensure consistent outputs
Response quality	Different responses to identical inputs, agent forgets context, doesn’t follow instructions	Review system prompt / node prompt specificity; check model configuration; adjust temperature to achieve consistency

Debug steps for response quality:

Review system prompt - Navigate to your assistant/workflow in the dashboard and check the system prompt specificity
Check model configuration - Scroll down to Model section and verify:
- You’re using an appropriate model (e.g., gpt-4o)
- Max Tokens is sufficient for response length
- Necessary tools are enabled and configured correctly

Response Issue	Solution
Responses too long	Add “Keep responses under X words” to system prompt
Robotic speech	Switch to a different voice provider
Forgetting context	Use models with larger context windows
Wrong information	Check tool outputs and knowledge base accuracy via `Call Logs`

Tool and workflow debugging

Problem Type	Issue	Solution
Tool execution	Tools failing, HTTP errors, parameter issues	Navigate to `Observe > Call Logs` and check tool execution section, test tools individually at `Tools > [Select Tool] > Test`, validate configuration
Variable extraction	Variables not extracted, wrong values, missing data	Be specific in variable descriptions, use distinct enum values, add validation prompts
Workflow logic	Wrong node routing, conditions not triggering, variables not passing	Use `Call Logs` to trace conversation path, verify edge conditions are clear, check global node conflicts

Variable extraction details:

Problem	Cause	Solution
Variables not extracted	Unclear description	Be specific in variable descriptions: “Customer’s 10-digit phone number”
Wrong variable values	Ambiguous enum options	Use distinct enum values: “schedule”, “cancel”, “reschedule”
Missing required variables	User didn’t provide info	Add validation prompts to request missing data

Common error patterns

Error Pattern	Likely Cause	Quick Fix
Agent misinterpreting speech	Speech recognition issue	Check transcriber model, add custom keyterms
Irrelevant responses	Poor prompt engineering	Be more specific in system prompt
Call drops immediately	Configuration error	Check all required fields in assistant/workflow settings
Tool errors	API integration issue	Test tools individually, verify endpoint URLs
Long silences	Model processing delay	Use faster models or reduce response length

For a complete list of error codes and what they mean, see Call end reasons. To diagnose a failed call by symptom (e.g., “call dropped mid-conversation” or “assistant went silent”), see Troubleshoot call errors.

Getting help

When you’re stuck:

Community Support

Join the Vapi Discord for real-time help from the community and team

API Reference

Check the API reference for detailed configuration options

Status Page

Check real-time status of Vapi services and AI providers

Before asking for help:

Include call ID and timestamp from Call Logs in your dashboard
Describe expected vs. actual behavior
Share relevant configuration (without API keys)
Include error messages from dashboard logs

$	# Terminal 1: Create tunnel (e.g., with ngrok)
$	ngrok http 4242
$
$	# Terminal 2: Forward webhooks
$	vapi listen --forward-to localhost:3000/webhook