Skip to content

Commit 54a1d79

Browse files
goosewingoosewin
authored
feat: debugging guide (VapiAI#472)
1 parent 472cd9d commit 54a1d79

File tree

2 files changed

+182
-0
lines changed

2 files changed

+182
-0
lines changed

‎fern/debugging.mdx

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: Debugging voice agents
3+
subtitle: Learn to identify, diagnose, and fix common issues with your voice assistants and workflows
4+
slug: debugging
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
**Common debugging scenarios:**
12+
- Agent doesn't understand user input correctly
13+
- Responses are inappropriate or inconsistent
14+
- Call quality issues or audio problems
15+
- Tool integrations failing or returning errors
16+
- Workflow logic not executing as expected
17+
18+
## Quick diagnostics
19+
20+
Start with these immediate checks before diving deeper:
21+
22+
<Steps>
23+
<Step title="Test in dashboard">
24+
Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/):
25+
26+
- **Assistants**: `Dashboard > Assistants > [Select Assistant] > Talk to Assistant`
27+
- **Workflows**: `Dashboard > Workflows > [Select Workflow] > Call`
28+
- Eliminates phone network variables
29+
- Provides real-time transcript view
30+
- Shows tool execution results immediately
31+
</Step>
32+
<Step title="Check logs">
33+
Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar:
34+
35+
- **Call Logs**: Review call transcripts, durations, and error messages
36+
- **API Logs**: Check API requests and responses for integration issues
37+
- **Webhook Logs**: Verify webhook deliveries and server responses
38+
</Step>
39+
<Step title="Test individual components">
40+
Use [dashboard](https://dashboard.vapi.ai/) testing features:
41+
42+
- **Voice Test Suites**: `Test > Voice Test Suites` (assistants only)
43+
- **Tool Testing**: `Tools > [Select Tool] > Test` with sample payloads
44+
</Step>
45+
<Step title="Verify provider status">
46+
Check if AI service providers are experiencing issues:
47+
48+
- Visit [Vapi Status Page](https://status.vapi.ai/) for real-time provider status
49+
- Review speech-to-text, language model, and voice synthesis availability
50+
- Check for ongoing maintenance or outages
51+
</Step>
52+
</Steps>
53+
54+
## Dashboard debugging resources
55+
56+
The [Vapi dashboard](https://dashboard.vapi.ai/) provides powerful debugging features to help you identify and fix issues quickly:
57+
58+
### Call Logs
59+
60+
Navigate to `Observe > Call Logs` to:
61+
- Review complete call transcripts
62+
- Check call duration and completion status
63+
- Identify where calls failed or ended unexpectedly
64+
- See tool execution results and errors
65+
- Analyze conversation flow in workflows
66+
67+
### API Logs
68+
69+
Navigate to `Observe > API Logs` to:
70+
- Monitor all API requests and responses
71+
- Check for authentication errors
72+
- Verify request payloads and response codes
73+
- Debug integration issues with external services
74+
75+
### Webhook Logs
76+
77+
Navigate to `Observe > Webhook Logs` to:
78+
- Verify webhook deliveries to your server
79+
- Check server response codes and timing
80+
- Debug webhook authentication issues
81+
- Monitor event delivery failures
82+
83+
### Voice Test Suites
84+
85+
Navigate to `Test > Voice Test Suites` to:
86+
- Run automated tests on your assistants (not available for workflows)
87+
- Test conversation flows with predefined scenarios
88+
- Verify assistant behavior across different inputs
89+
- Monitor performance over time
90+
91+
### Tool Testing
92+
93+
For any tool in your `Tools` section:
94+
- Navigate to `Tools > [Select Tool]`
95+
- Use the `Test` button to send sample payloads
96+
- Verify tool responses and error handling
97+
- Debug parameter extraction and API calls
98+
99+
## Speech and language issues
100+
101+
| Problem | Symptoms | Solution |
102+
|---------|----------|----------|
103+
| **Transcription accuracy** | Incorrect words in transcripts, missing words/phrases, poor performance with accents | Switch to more accurate transcriber. |
104+
| **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 |
105+
| **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 |
106+
107+
**Debug steps for response quality:**
108+
1. **Review system prompt** - Navigate to your assistant/workflow in the [dashboard](https://dashboard.vapi.ai/) and check the system prompt specificity
109+
2. **Check model configuration** - Scroll down to `Model` section and verify:
110+
- You're using an appropriate model (e.g., `gpt-4o`)
111+
- `Max Tokens` is sufficient for response length
112+
- Necessary tools are enabled and configured correctly
113+
114+
| Response Issue | Solution |
115+
|----------------|----------|
116+
| **Responses too long** | Add "Keep responses under X words" to system prompt |
117+
| **Robotic speech** | Switch to a different voice provider |
118+
| **Forgetting context** | Use models with larger context windows |
119+
| **Wrong information** | Check tool outputs and knowledge base accuracy via `Call Logs` |
120+
121+
## Tool and workflow debugging
122+
123+
| Problem Type | Issue | Solution |
124+
|--------------|-------|----------|
125+
| **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 |
126+
| **Variable extraction** | Variables not extracted, wrong values, missing data | Be specific in variable descriptions, use distinct enum values, add validation prompts |
127+
| **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 |
128+
129+
**Variable extraction details:**
130+
131+
| Problem | Cause | Solution |
132+
|---------|-------|----------|
133+
| **Variables not extracted** | Unclear description | Be specific in variable descriptions: "Customer's 10-digit phone number" |
134+
| **Wrong variable values** | Ambiguous enum options | Use distinct enum values: "schedule", "cancel", "reschedule" |
135+
| **Missing required variables** | User didn't provide info | Add validation prompts to request missing data |
136+
137+
## Common error patterns
138+
139+
| Error Pattern | Likely Cause | Quick Fix |
140+
|---------------|--------------|-----------|
141+
| **"I didn't understand"** | Speech recognition issue | Check transcriber model, add custom keyterms |
142+
| **Irrelevant responses** | Poor prompt engineering | Be more specific in system prompt |
143+
| **Call drops immediately** | Configuration error | Check all required fields in assistant/workflow settings |
144+
| **Tool errors** | API integration issue | Test tools individually, verify endpoint URLs |
145+
| **Long silences** | Model processing delay | Use faster models or reduce response length |
146+
147+
## Getting help
148+
149+
When you're stuck:
150+
151+
<Card
152+
title="Community Support"
153+
icon="user-group"
154+
href="https://discord.com/invite/pUFNcf2WmH"
155+
>
156+
Join the Vapi Discord for real-time help from the community and team
157+
</Card>
158+
159+
<Card
160+
title="API Reference"
161+
icon="book"
162+
href="/api-reference"
163+
>
164+
Check the API reference for detailed configuration options
165+
</Card>
166+
167+
<Card
168+
title="Status Page"
169+
icon="fa-light fa-heartbeat"
170+
href="https://status.vapi.ai/"
171+
>
172+
Check real-time status of Vapi services and AI providers
173+
</Card>
174+
175+
**Before asking for help:**
176+
- Include call ID and timestamp from `Call Logs` in your [dashboard](https://dashboard.vapi.ai/)
177+
- Describe expected vs. actual behavior
178+
- Share relevant configuration (without API keys)
179+
- Include error messages from [dashboard](https://dashboard.vapi.ai/) logs

‎fern/docs.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,9 @@ navigation:
244244
- page: Prompting guide
245245
path: prompting-guide.mdx
246246
icon: fa-light fa-pen-to-square
247+
- page: Debugging voice agents
248+
path: debugging.mdx
249+
icon: fa-light fa-bug
247250
- section: Testing
248251
collapsed: true
249252
icon: fa-light fa-clipboard-check

0 commit comments

Comments
 (0)