Debugging voice agents

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
Unexpected behavior or configuration errors

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

Benefits:

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

Check logs

Use the Logs overview to choose the right log, then open Logs in the Dashboard:

Calls

Review call transcripts, durations, and error messages

API

Check logged API requests and responses for integration issues

Webhooks

Verify logged webhook deliveries and server responses

Test individual components

Use dashboard testing features:

Simulations

Test outcomes across complete conversations

Evals

Test decisions at specific conversation points

Tool testing

Test supported 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

Open Logs → Calls to:

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

API request logs

Open Logs → API to:

Inspect logged API requests and responses
Review recorded 401 and 403 responses
Verify request payloads and response codes
Debug integrations that call the Vapi API

Webhook logs

Open Logs → Webhooks to:

Verify logged 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 →

Simulations and Evals

Use Simulations to reproduce a problem across a complete conversation and check the final outcome. Use Evals to isolate a specific decision, such as choosing a tool, asking for missing information, or escalating the call.

See testing voice agents for guidance on choosing a test and turning production failures into regression coverage.

Tool testing

The Dashboard can test API request, function, and Model Context Protocol (MCP) tools. To test one from Tools:

Select the tool.
Select Test.
Configure and run the test in the panel.
Review the response and any error details.

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	Make the system 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 specificity; check model configuration; adjust temperature to achieve consistency

Debug steps for response quality:

Review system prompt - Navigate to your assistant 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 in call logs

Tool and variable debugging

Problem Type	Issue	Solution
Tool execution	Tools failing, HTTP errors, parameter issues	Open Logs → Calls and check the Logs tab. For API request, function, and MCP tools, use Test, then validate the configuration.
Variable extraction	Variables not extracted, wrong values, missing data	Be specific in variable descriptions, use distinct enum values, add validation prompts

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 settings
Tool errors	API integration issue	Use Test for API request, function, and MCP tools, then 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:

Discord community

Ask other developers for help in the Vapi Discord community

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 the call ID and timestamp from Logs → Calls
Describe expected vs. actual behavior
Share relevant configuration (without API keys)
Include error messages from dashboard logs